No live, per-step trace of an in-flight loop run over MCP — only `coding_loop_status` and a post-hoc `detail`

[serge-ivo]

The gap

Owner feedback (instance bd43f4de, 2026-08-15): there is no real-time, per-step observability into a running coding/agent loop from an external MCP client. While a run is in flight the only signal is coding_loop_status (status, iteration, lastProgressAt, and — once finished — a one-line detail). There is no way to see what the agent is actually doing mid-run: no per-iteration tool calls with their inputs/outputs, no reasoning, no partial output, no streaming progress. instance_activity records chat-session events only and shows nothing from loop runs, so during a run the instance looks idle even though work is happening.

Why it matters

When a run stalls or fails, the owner cannot tell whether it is mid-way through a legitimate long step, silently stuck, or doing something it was told not to do. In one case the only evidence of destructive behaviour was the phrase Acts: deleted files recursively in the post-hoc summary, with no way to see which files or why while it was happening.

Ask

Expose a live, per-step trace of a loop run to the owner — each iteration's tool calls with arguments and results, plus streaming/incremental output — through the same MCP surface that starts the run, queryable while the run is still in flight. agent_trace already does this for chat turns (chat.in/tool.call/chat.out); loop runs need the equivalent, not just a terminal detail after the fact.

Not a duplicate of

• Notify proactively when an agent run finishes (webhook / event feed) - investigation #579 (notify proactively when a run finishes) — that is the end-of-run signal; this is the during-run trace.
• coding_timeline records no per-step token, cost, files-changed or test-result summary — the ordering half of this is fixed #674 (coding_timeline per-step token/cost/files summary) — post-hoc timeline, not a live in-flight feed.

Filed from owner feedback fd60c895-bc18-4ee3-b4f1-de9b351ad4f7.

[serge-ivo]

BA/dev triage — keep P1, narrow the MVP

This is correctly P1, but the implementation scope needs to be stated more tightly.

Important correction from the code pass: the platform already has some of the raw material. coding_timeline can be read while a run is in flight, terminal snapshots are persisted, engine-tool-calls can reconstruct tool calls from terminal rows, and agent_events/agent_trace already carry lifecycle and consequential-act rows. The gap is that a caller who starts a loop run over MCP does not get one run-id-addressable, live trace feed that answers "what is this run doing right now?" without knowing the session id or stitching several surfaces together.

Recommended MVP:

1. Add a read-only MCP surface for an in-flight coding loop trace, cursorable by run_id and usable while the run is still running.
2. Resolve run_id -> session_id through agent_loop_runs.session_id, falling back to the existing session resolution only when a caller explicitly asks by session.
3. Return ordered events with timestamps, run/session ids, iteration/progress markers, tool name, argument summary, result status (ok: true | false | null), output/error summary, and incremental terminal/progress text where available.
4. Reuse the existing trace/timeline/tool-call readers where possible; avoid a second write-heavy event store unless the current stores cannot satisfy cursor correctness.

Out of MVP: hidden model reasoning, full raw tool payloads by default, and a replay/debugger UI. Those need a separate safety/redaction decision.

Acceptance criteria should explicitly cover owner-only access, secret redaction, pagination/cursor semantics, behavior after run completion, duplicate suppression across terminal snapshots, and whether agent_trace is extended or a loop-specific trace tool is added.

Likely code areas: workers/mcp/src/instance-tools/coding.ts, workers/api/src/routes/coding-feed.ts, workers/api/src/lib/coding-timeline.ts, workers/api/src/lib/engine-tool-calls.ts, workers/api/src/lib/events.ts, and agent_loop_runs.session_id from migration 0116.

[serge-ivo]

Shipped: run-id-addressable live coding loop trace

Implemented across three pushed commits:

• 675059eb — API accepts run_id on GET /v1/instances/:id/coding/timeline and resolves it through agent_loop_runs.session_id.
• ebb2d76b — MCP exposes read-only, coding-surface-gated coding_loop_trace; MCP surface bumped to 0.1.19, counts/lock/docs updated.
• 5876486a — API hardening: run_id and session_id are mutually exclusive, wrong-instance run ids return a distinct 404, non-coding loop runs return a distinct 404, and timeline responses echo runId when resolved by run.

What the owner/client can do now:

1. Call coding_loop_start and keep the returned runId.
2. Poll coding_loop_trace with that run_id and optional since_seq.
3. Read the same timeline feed as coding_timeline: objective/progress rows, terminal tails, parsed toolCalls, ok, runState, runner connectivity, and cursor fields while the run is in flight or after it ends.

Validation run:

• pnpm vitest run workers/api/src/routes/coding-feed.test.ts — 17 passed.
• pnpm vitest run workers/mcp/src/conformance.test.ts workers/mcp/src/index.test.ts workers/mcp/src/instance-tools.test.ts workers/mcp/src/instance-tools/contract.test.ts — 181 passed.
• pnpm --filter proagentstore-mcp typecheck — passed.
• pnpm docs:drift — passed.
• pnpm exec biome check ... on changed TS files — passed.
• git diff --check — passed.

Not live-verified against a real in-flight production loop in this pass; this is verified through the API/MCP route and surface tests.