[aryasaatvik]

Adds the execution-observer foundation — the seam the history and metrics plugins build on.

• New ExecutionObserver contract in the SDK: six tagged lifecycle events (ExecutionStarted/Finished, ToolCallStarted/Finished, InteractionStarted/Resolved) + composeExecutionObservers, with a plugin.runtime.executionObserver hook.
• The execution engine emits the events (re-derived onto the current Queue-based pause model), exposes Executor.owner, and tags the run span with the execution id + trigger.
• makeExecutionStack composes plugin observers — one seam covers every HTTP host and the MCP Durable Objects; local's fixed-execution + in-process MCP are wired directly.

Behaviour-neutral / opt-in: with no plugin observing, every path is a no-op.

Gates: format:check, lint, full-monorepo typecheck, and observer unit tests all green. Live app verification still to come.

Stack

1. feat: add the execution-observer foundation #12 👈 current
2. feat: add the execution-history plugin #13
3. feat: add the execution-metrics plugin #14

[greptile-apps]

Greptile Summary

This PR introduces the execution-observer foundation: a typed lifecycle event stream (ExecutionStarted/Finished, ToolCallStarted/Finished, InteractionStarted/Resolved) that the engine emits, with plugins subscribing via a new runtime.executionObserver hook composed by makeExecutionStack and the two local wiring points.

• execution-observer.ts defines the six tagged event classes, the ExecutionObserver interface, and composeExecutionObservers with parallel fan-out (concurrency: "unbounded") and per-observer error isolation via Effect.catchCause.
• engine.ts brackets both the inline and pausable execution paths with ExecutionStarted/Finished events, wraps the invoker with observeToolCalls, and mirrors InteractionResolved on the tapCause path in the pausable handler so every InteractionStarted is paired even on interrupt.
• executor.ts exposes Executor.owner so engine-level machinery can attribute events without re-threading identity; makeExecutionStack, app.ts, and main.ts each wire composeExecutionObservers at the correct seam for their host.

Confidence Score: 5/5

Safe to merge — the observer is fully opt-in, every event is emitted under error isolation, and all existing execution paths are unaffected when no plugin registers an observer.

The new lifecycle stream is additive and behaviour-neutral: the no-op default means zero runtime change for current hosts. Both the inline and pausable paths correctly pair every Started event with a Finished counterpart — including on the interrupt/failure path via tapCause. The only finding is a test assertion that works today but relies on an implicit assumption about Effect's synchronous scheduler ordering.

No files require special attention.

Important Files Changed

Filename	Overview
packages/core/sdk/src/execution-observer.ts	New file: defines all execution lifecycle event types (6 tagged classes), ExecutionObserver interface, noopExecutionObserver, ignoreExecutionObserverErrors, and composeExecutionObservers with correct parallel fan-out (concurrency: "unbounded") and per-observer error isolation.
packages/core/execution/src/engine.ts	Wires execution observer into both the inline and pausable execution paths; ExecutionStarted/Finished bracket each run, ToolCallStarted/Finished bracket each invoke, and InteractionStarted/Resolved bracket each elicitation in both paths with tapCause on the interrupt/failure path.
packages/core/sdk/src/execution-observer.test.ts	Unit tests for composeExecutionObservers; the fan-out isolation test asserts ordered results (["first", "last"]) from concurrent execution, which works today for synchronous Effect.sync effects but is an implicit scheduler-ordering assumption.
packages/core/execution/src/engine-observer.test.ts	Integration test verifying the full lifecycle event sequence (ExecutionStarted → ToolCallStarted → ToolCallFinished → ExecutionFinished) and the no-op path; event ordering assertions are safe here as they check first/last slot, not mid-sequence order.
packages/core/api/src/server/execution-stack.ts	Adds composeExecutionObservers wiring inside makeExecutionStack; plugins() is correctly cast to the caller's phantom TPlugins type so extensions lookup aligns, and the no-op path is preserved when no plugin registers an observer.
packages/core/sdk/src/plugin.ts	Adds optional runtime.executionObserver hook to PluginSpec; uses NoInfer to prevent TypeScript from widening TExtension through the self parameter, which is the correct technique for this constraint.
apps/local/src/app.ts	Passes plugins to localFixedExecutionLayer so composeExecutionObservers can run; local bypasses makeExecutionStack so this is the correct wiring point.
apps/local/src/main.ts	Also wires composeExecutionObservers for the local in-process MCP engine; correctly passes executor as extensions since Executor extends PluginExtensions.
packages/core/sdk/src/executor.ts	Exposes owner: OwnerBinding on the Executor type and wires ownerBinding into createExecutor; clean addition with no side effects on existing call sites.

Sequence Diagram

sequenceDiagram
    participant C as Caller
    participant E as Engine (startPausableExecution)
    participant O as ExecutionObserver(s)
    participant F as Daemon Fiber

    C->>E: "executeWithPause(code, {trigger})"
    E->>O: "ExecutionStarted {executionId, owner, trigger}"
    E->>F: forkDetach(codeExecutor.execute)
    E->>E: awaitCompletionOrPause (race Fiber.join vs Queue.take)

    alt No elicitation (completes directly)
        F->>O: "ToolCallStarted {executionId, toolCallId, path}"
        F->>O: "ToolCallFinished {executionId, toolCallId, status}"
        F->>O: "ExecutionFinished {executionId, status: completed}"
        F-->>E: Fiber.join resolves
        E-->>C: "{status: completed}"
    else Elicitation required (pause path)
        F->>O: "InteractionStarted {executionId, interactionId}"
        F->>E: Queue.offer(paused)
        E-->>C: "{status: paused, execution}"
        Note over F: Fiber blocked on Deferred.await
        C->>E: resume(pauseId, response)
        E->>F: Deferred.succeed(response)
        F->>O: "InteractionResolved {status: accepted/declined/cancelled}"
        Note over F,O: tapCause also emits InteractionResolved on interrupt/failure
        F->>O: "ExecutionFinished {executionId, status}"
        F-->>E: Fiber.join resolves
        E-->>C: "{status: completed}"
    end

Loading

_{Reviews (3): Last reviewed commit: "fix(execution): parallelize observer fan..." | Re-trigger Greptile}