Transcript detail parity across spawn modes (none/local/ephemeral) in /v1/agents/run

[jameswnl]

Problem

POST /v1/agents/run returns a transcript field whose level of detail (and shape) depends on the spawn mode, so the same logical run is not comparable across modes. Verified against the current code and a live demo against POST /v1/agents/run:

spawn	executor	transcript content
none	DirectExecutor (in-process)	Single summary entry (llm.call, agent.run, or agent.stream) with model + aggregate token counts. Individual LLM turns and tool calls inside the agent loop are not listed.
local	SubprocessExecutor	Pass-through from the subprocess child, defaulting to a 2-message [{role: "user", ...}, {role: "assistant", ...}] pair (prompt + final text). Different shape, no typed events.
ephemeral	SandboxExecutor	Per-event list with canonical typed entries (tool_call, tool_result, thinking, result, error, see TranscriptEvent in cloud_agents.workflow.core.models). The only mode that records individual tool calls.

References:

• Endpoint returns StepResult.transcript verbatim: src/app/endpoints/agents.py (run_agent_handler, transcript field of the response body).
• DirectExecutor single-entry transcripts: direct.py (llm.call / agent.run / agent.stream).
• SubprocessExecutor child default transcript: subprocess_child.py (setdefault("transcript", [{role: user...}, {role: assistant...}])).
• Canonical event model: TranscriptEvent / normalize_transcript_events in cloud_agents.workflow.core.models.

Why it matters

• Demos and consumers cannot rely on transcript to show tool use unless they happen to use spawn: ephemeral.
• Any transcript consumer (UI, audit, eval) must special-case three shapes/granularities.

Proposal

Emit the same per-event canonical transcript (tool_call, tool_result, thinking, result, error) for spawn: none and spawn: local as spawn: ephemeral already does, so the transcript response field has parity across modes. Where an executor genuinely cannot produce an event type, document the gap rather than silently returning a coarser shape.

Acceptance

• The same agent run (same prompt/tools) yields the same transcript event types across none, local, and ephemeral.
• Any remaining per-mode limitation is documented (e.g. in docs/cloud-agents-integration.html or the endpoint description).
• Demo script (docs/cloud-agents-demo-curl.sh) transcripts reflect the unified shape.