From a024cb7954ddc1d33ffb11a6a31ec0c94f875b23 Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Sat, 10 Jan 2026 08:09:21 -0800 Subject: [PATCH 1/2] docs: require orchestrator:complete event emission in contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added documentation that orchestrators MUST emit orchestrator:complete at the end of execute(). This enables session analytics, hooks that trigger on completion, and observability. Updated validation checklist. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- docs/contracts/ORCHESTRATOR_CONTRACT.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/contracts/ORCHESTRATOR_CONTRACT.md b/docs/contracts/ORCHESTRATOR_CONTRACT.md index ac5cb72c..88ab9db8 100644 --- a/docs/contracts/ORCHESTRATOR_CONTRACT.md +++ b/docs/contracts/ORCHESTRATOR_CONTRACT.md @@ -167,8 +167,28 @@ async def execute(self, prompt, context, providers, tools, hooks): "tool_input": tool_call.input, "tool_result": result }) + + # REQUIRED: At the end of execute(), emit orchestrator:complete + await hooks.emit("orchestrator:complete", { + "orchestrator": "my-orchestrator", # Your orchestrator name + "turn_count": iteration_count, # Number of LLM turns + "status": "success" # "success", "incomplete", or "cancelled" + }) ``` +#### Required: orchestrator:complete Event + +**All orchestrators MUST emit `orchestrator:complete`** at the end of their `execute()` method. This event enables: +- Session analytics and debugging +- Hooks that trigger on turn completion (e.g., session naming) +- Observability and monitoring + +| Field | Type | Description | +|-------|------|-------------| +| `orchestrator` | string | Name of the orchestrator module | +| `turn_count` | int | Number of LLM call iterations | +| `status` | string | Exit status: `"success"`, `"incomplete"`, or `"cancelled"` | + ### Hook Processing Handle HookResult actions: @@ -295,6 +315,7 @@ Additional examples: - [ ] Implements `execute(prompt, context, providers, tools, hooks) -> str` - [ ] `mount()` function with entry point in pyproject.toml - [ ] Emits standard events (provider:request/response, tool:pre/post) +- [ ] **Emits `orchestrator:complete` at the end of execute()** - [ ] Handles HookResult actions appropriately - [ ] Manages context (add messages, check compaction) From 5ab7c2f8da2bc8a123a22c23253d3913ce92a71e Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Sat, 10 Jan 2026 08:21:29 -0800 Subject: [PATCH 2/2] feat: add debug/raw LLM events to ALL_EVENTS for comprehensive logging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add missing event constants for complete LLM request/response logging: - LLM_REQUEST_DEBUG, LLM_REQUEST_RAW - LLM_RESPONSE_DEBUG, LLM_RESPONSE_RAW These are now included in ALL_EVENTS, making it the canonical comprehensive list that downstream modules can use. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- amplifier_core/events.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/amplifier_core/events.py b/amplifier_core/events.py index 245715dd..74227819 100644 --- a/amplifier_core/events.py +++ b/amplifier_core/events.py @@ -57,7 +57,11 @@ SESSION_RESUME = "session:resume" LLM_REQUEST = "llm:request" +LLM_REQUEST_DEBUG = "llm:request:debug" +LLM_REQUEST_RAW = "llm:request:raw" LLM_RESPONSE = "llm:response" +LLM_RESPONSE_DEBUG = "llm:response:debug" +LLM_RESPONSE_RAW = "llm:response:raw" THINKING_DELTA = "thinking:delta" THINKING_FINAL = "thinking:final" CONTEXT_INCLUDE = "context:include" @@ -76,7 +80,11 @@ PROVIDER_RESPONSE, PROVIDER_ERROR, LLM_REQUEST, + LLM_REQUEST_DEBUG, + LLM_REQUEST_RAW, LLM_RESPONSE, + LLM_RESPONSE_DEBUG, + LLM_RESPONSE_RAW, CONTENT_BLOCK_START, CONTENT_BLOCK_DELTA, CONTENT_BLOCK_END,