feat(llm,core,shared,db): 1.AG — media output generation (Phase D, ADR-0045/0046)

CLAUDE.md

@@ -38,7 +38,7 @@ A run executes in one of **three execution modes** behind the one `LLMProvider`
 engine is identical across all three. See [ADR-0012](docs/decisions/0012-managed-inference-dual-mode.md) to [ADR-0015](docs/decisions/0015-managed-mode-data-handling-and-compliance.md)
 and [docs/architecture/managed-inference.md](docs/architecture/managed-inference.md).
 
-**Status:** Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2; and the **pre-egress budget governor (1.AC, [ADR-0028](docs/decisions/0028-workflow-resource-governance.md)) + the `AgentSession` agent-first entry point (1.V, [ADR-0024](docs/decisions/0024-agent-first-entry-point-agentsession.md)) landed together (PR #26, 2026-06-16)** — 1.AC was the last 1.m4 component, so **1.m4 is complete** (the full engine stack: node handlers, gate, checkpoint/resume, retry, tools, sandbox, budget governor), and 1.V opens the Lane-C agent-first sub-spine (1.m5); then the **end-to-end Node harness (1.U) landed (PR #27, 2026-06-16), reaching 🎯 M2** — the engine runs end-to-end (live streaming + per-node-boundary checkpointing + cross-process resume + node retry + provider failover, gap-free), **completing the Phase-1 engine critical path**. The remaining Phase-1 work is additive and off the critical path (Lane C: the **`session:*` namespace (1.W) landed (PR #28, 2026-06-17)** — the `SessionEventSink`→`RunEventBus` adapter + per-session `sequenceNumber`, the `SessionHandle`, and the combined `RunOrSessionEventSchema` gate — and **session persistence (1.X) landed (PR #29, 2026-06-17)** — the `agent_sessions`/`session_messages` tables + migration, `SessionMessageSchema`/`AgentSessionSchema`, and the `SessionStore` + domain↔row mappers (data-layer only); then **session checkpoint/resume (1.Y) + export-to-workflow (1.Z) landed (PR #30, 2026-06-17)** — `reconstructSessionState`/`AgentSession.resume` (reload-not-replay; preload the text-only transcript, re-seed turnCount/cost, no `session:started` re-emit) + the `serializeWorkflow`/`sessionToWorkflow` pair (one agent node per completed turn, transcript in `metadata`, secret/signature exclusion structural) — leaving only the **1.AA** chat-regression harness ‖ the 1.m6 multimodal sub-spine, whose first step — **media-input adapters + the shared SSRF policy primitive (1.AE) — landed (PR #32, 2026-06-18)** (base64 image/audio across the three adapters behind per-modality `assertMediaCapabilities`, and the one `@relavium/shared` SSRF policy primitive reused by the provider-`baseURL` + `http_request` callers; the SSRF *mechanism* half + per-modality FallbackChain gating moved into **1.AF**). **1.AF (engine media plumbing) is in progress: P1+P2 merged (PR #33)** — the `MediaStore`/`deInlineMedia` choke point (the active I3 enforcement), per-modality capability gating (`mediaSupportReason`/`requestSupportReason` — replacing coarse vision), the `media_objects`/`media_references` tables, and ADR-0042/0043/0044 — and **P3 + P4/D13 have landed on `development` in a follow-on PR (pending merge):** the binary media-egress + the **SSRF mechanism half** (D9 — the `MediaUrlFetch` re-host hook + the `fetchMediaBytes` SSRF-validated host reference wired at the choke point), the `FallbackChain` resolve-before-egress + the **byte-free re-materialization sidecar** (D8/D7), and the byte-delivery **`Range` gate** (D13 — `MediaStore.readRange` + `validateByteRange`), with the dedicated **P3 egress/SSRF security-review clean** (0 blockers/highs). The rest of **P4** follows: `read_media` + the scope-set authz (D12), the terminal sweep + GC (D11), `save_to` (D16), the `output_modalities` load-check (D15), the per-modality media cost governor (D17), the byte-delivery security-review + the keychain IPC test. **Phase 2 (CLI, M3) is unblocked**.
+**Status:** Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2; and the **pre-egress budget governor (1.AC, [ADR-0028](docs/decisions/0028-workflow-resource-governance.md)) + the `AgentSession` agent-first entry point (1.V, [ADR-0024](docs/decisions/0024-agent-first-entry-point-agentsession.md)) landed together (PR #26, 2026-06-16)** — 1.AC was the last 1.m4 component, so **1.m4 is complete** (the full engine stack: node handlers, gate, checkpoint/resume, retry, tools, sandbox, budget governor), and 1.V opens the Lane-C agent-first sub-spine (1.m5); then the **end-to-end Node harness (1.U) landed (PR #27, 2026-06-16), reaching 🎯 M2** — the engine runs end-to-end (live streaming + per-node-boundary checkpointing + cross-process resume + node retry + provider failover, gap-free), **completing the Phase-1 engine critical path**. The remaining Phase-1 work is additive and off the critical path (Lane C: the **`session:*` namespace (1.W) landed (PR #28, 2026-06-17)** — the `SessionEventSink`→`RunEventBus` adapter + per-session `sequenceNumber`, the `SessionHandle`, and the combined `RunOrSessionEventSchema` gate — and **session persistence (1.X) landed (PR #29, 2026-06-17)** — the `agent_sessions`/`session_messages` tables + migration, `SessionMessageSchema`/`AgentSessionSchema`, and the `SessionStore` + domain↔row mappers (data-layer only); then **session checkpoint/resume (1.Y) + export-to-workflow (1.Z) landed (PR #30, 2026-06-17)** — `reconstructSessionState`/`AgentSession.resume` (reload-not-replay; preload the text-only transcript, re-seed turnCount/cost, no `session:started` re-emit) + the `serializeWorkflow`/`sessionToWorkflow` pair (one agent node per completed turn, transcript in `metadata`, secret/signature exclusion structural) — leaving only the **1.AA** chat-regression harness ‖ the 1.m6 multimodal sub-spine, whose first step — **media-input adapters + the shared SSRF policy primitive (1.AE) — landed (PR #32, 2026-06-18)** (base64 image/audio across the three adapters behind per-modality `assertMediaCapabilities`, and the one `@relavium/shared` SSRF policy primitive reused by the provider-`baseURL` + `http_request` callers; the SSRF *mechanism* half + per-modality FallbackChain gating moved into **1.AF**). **1.AF (engine media plumbing) is ✅ Done (PR #33/#34/#35/#36, 2026-06-20):** the `MediaStore`/`deInlineMedia` choke point (the active I3 enforcement), per-modality capability gating (`mediaSupportReason`/`requestSupportReason` — replacing coarse vision), the `media_objects`/`media_references` tables, and ADR-0042/0043/0044 (P1+P2, PR #33); the binary media-egress + the **SSRF mechanism half** (D9 — the `MediaUrlFetch` re-host hook + the SSRF-validated `fetchMediaBytes` wired at the choke point), the `FallbackChain` resolve-before-egress + the **byte-free re-materialization sidecar** (D8/D7), and the byte-delivery **`Range` gate** (D13) (P3 + P4/D13, PR #34); `read_media` + the scope-set authz (D12), the terminal sweep + grace-window GC (D11), `save_to` (D16), the `output_modalities` load-check (D15), and the per-modality media cost governor (D17) (P4 remainder, PR #35); plus a **13-dimension end-to-end review + an external Sonar/CodeRabbit pass** (PR #36 — H1 `agent:tool_call.toolInput` byte-redaction, H2 the unified exact-membership output-combination gate, the GC grace-basis fix, the `nodeMediaEgressDeps` egress-mechanism test). Each phase passed a dedicated adversarial security-review (0 blockers/highs). The deferred **host-wiring** half (D12 `MediaReadAccess` + session-scope population, the D15 loader, the D17/`resolveForEgress` config) + the keychain no-raw-key IPC test are owned by **1.AH** (recorded in deferred-tasks.md). The remaining Phase-1 work is **1.AG/1.AH**; **Phase 2 (CLI, M3) is unblocked**.
 Phase 0 (M0, 2026-06-04) landed the monorepo, strict toolchain + CI, `@relavium/shared` (the
 full Zod contract set), the no-vendor-type seam fence, and `@relavium/db`. Phase 1 has since
 landed `@relavium/llm` — the `LLMProvider` seam + all three adapters (Anthropic, OpenAI/DeepSeek,
@@ -64,7 +64,7 @@ The pre-egress budget governor (1.AC) + the agent-first `AgentSession` (1.V) lan
 **completing 1.m4**; then the end-to-end Node harness (1.U) landed (PR #27, 2026-06-16) **reaching M2** —
 the Phase-1 engine critical path is complete. The additive Lane-C agent-first sub-spine is now **complete**
 (session events **1.W ✅ (PR #28)** + persistence **1.X ✅ (PR #29)** + checkpoint/resume **1.Y** & export **1.Z ✅ (PR #30, 2026-06-17)** + the **1.AA** chat-regression harness ✅ (2026-06-17), closing **1.m5**);
-on the 1.m6 multimodal sub-spine, **media-input adapters + the shared SSRF policy primitive (1.AE) landed (PR #32, 2026-06-18)** — after a multi-round + final 8-dimension adversarial review (no SSRF bypass found); the SSRF *mechanism* half + per-modality gating moved into 1.AF. **1.AF (engine media plumbing) is in progress: P1+P2 merged (PR #33)**; **P3 + P4/D13 landed on `development` (pending merge)** — the media-egress + SSRF mechanism half (D9), the `FallbackChain` resolve-before-egress + byte-free re-materialization sidecar (D8/D7), the byte-delivery `Range` gate (D13), and a clean P3 egress/SSRF security-review — with the rest of P4 (D12 `read_media` + authz, D11 GC sweep, D16 `save_to`, D15 load-check, D17 cost governor) to follow. The remaining Phase-1 work is 1.AF (in progress) + 1.AG/1.AH; Phase 2 (CLI) is unblocked. See
+on the 1.m6 multimodal sub-spine, **media-input adapters + the shared SSRF policy primitive (1.AE) landed (PR #32, 2026-06-18)** — after a multi-round + final 8-dimension adversarial review (no SSRF bypass found); the SSRF *mechanism* half + per-modality gating moved into 1.AF. **1.AF (engine media plumbing) is ✅ Done (PR #33/#34/#35/#36, 2026-06-20)** — P1+P2 (PR #33); the media-egress + SSRF mechanism half (D9), the `FallbackChain` resolve-before-egress + byte-free re-materialization sidecar (D8/D7), the byte-delivery `Range` gate (D13), and a clean P3 egress/SSRF security-review (P3 + P4/D13, PR #34); D12 `read_media` + authz, D11 GC sweep, D16 `save_to`, D15 load-check, D17 cost governor (P4 remainder, PR #35); and a 13-dimension end-to-end + external Sonar/CodeRabbit review (PR #36 — toolInput byte-redaction, the unified exact-membership output gate, the GC grace-basis fix, the egress-mechanism test). The host-wiring half (D12/D15/D17 mechanism) + the keychain IPC test are deferred to **1.AH**. The remaining Phase-1 work is 1.AG/1.AH; Phase 2 (CLI) is unblocked. See
 [docs/roadmap/current.md](docs/roadmap/current.md). See [README.md](README.md) for the public overview.
 
 ## Non-negotiable rules for AI agents

README.md

@@ -53,5 +53,5 @@ both landed in **PR #26 (2026-06-16)**. With the budget governor in, **milestone
 end-to-end (live streaming + checkpoint + cross-process resume + retry + provider failover), completing the
 Phase-1 engine critical path. The remaining Phase-1 work is additive (the agent-first sub-spine — **session
 events 1.W ✅ (PR #28)** + **persistence 1.X ✅ (PR #29)** + **session checkpoint/resume 1.Y & export-to-workflow 1.Z ✅ (PR #30, 2026-06-17)** + **the 1.AA chat-regression harness ✅ (2026-06-17)**, completing **1.m5** — and the
-multimodal sub-spine, whose first step — **media-input adapters + the shared SSRF policy primitive 1.AE ✅ (PR #32, 2026-06-18)** — landed); **Phase 2 (the CLI) is unblocked**. See
+multimodal sub-spine — **media-input adapters + the shared SSRF policy primitive 1.AE ✅ (PR #32)**, then **engine media plumbing 1.AF ✅ (PR #33/#34/#35/#36, 2026-06-20)** — landed; 1.AG/1.AH remain); **Phase 2 (the CLI) is unblocked**. See
 [docs/roadmap/current.md](docs/roadmap/current.md) for live status.

docs/decisions/0031-llm-seam-shape-amendment-multimodal-io.md

@@ -19,6 +19,10 @@
 
 > **Amended 2026-06-18 by [ADR-0042](0042-engine-media-storage-substrate-mediastore-deinline-retention.md), [ADR-0043](0043-media-egress-failover-rematerialization-ssrf.md), and [ADR-0044](0044-media-access-governance-read-media-save-to-cost.md).** The 1.AF wiring of this ADR's reserved media shape, refining (never reversing) it: ADR-0042 lands the `MediaStore` host-port injection + the `deInlineMedia` choke-point ordering + the `media_objects` retention/GC store (promoting this ADR's "Open implementation details" retention default to a decision); ADR-0043 lands the binary media-egress capability + the SSRF mechanism half, and **resolves this ADR's sidecar-ownership wording** (the `(provider, sha256)` sidecar is held per-`FallbackChain` run-instance via a narrow injected hook, not the stateless adapter); ADR-0044 lands the `read_media` scope-set authz + the byte-delivery gate + the `save_to` write port + the per-modality media cost. The seam shape here is unchanged.
 
+> **Amended 2026-06-20 by [ADR-0045](0045-async-media-job-loop-poll-checkpoint-resume-cancel.md).** A refinement, not a reversal: 1.AG wires the reserved `generateMedia`/`pollMediaJob` methods and **additively adds a `signal?` param to `pollMediaJob`** (so a cancel aborts the in-flight poll) — the only shape change to the 1.AD-frozen seam, made while the methods are still un-implemented. The reserved shapes (`MediaGenRequest`/`MediaGenResult`/`MediaJobStatus`, the opaque-jobId rule) stand.
+
+> **Amended 2026-06-20 by [ADR-0046](0046-inline-media-out-via-generate-streaming-triad-deferred.md).** A refinement, not a reversal: it pins which of §5.1's two inline-media-out paths Phase-1 (1.AG) uses — the non-streaming `generate()` path ("the more common"), de-inlined at the `#emitDurable` choke point — and defers the streaming `media_start`/`media_delta`/`media_end` triad to the host (1.AH). The seam shape (incl. the handle-only `media_end`) is unchanged.
+
 ## Context
 
 The `@relavium/llm` seam — the request/result/stream/usage/content shapes in

docs/decisions/0036-run-loop-substrate-event-bus-and-execution-host.md

@@ -6,6 +6,8 @@
 
 > **Amended 2026-06-18 by [ADR-0042](0042-engine-media-storage-substrate-mediastore-deinline-retention.md).** A refinement, not a reversal: ADR-0042 adds an optional `mediaStore?` port to the `ExecutionHost` seam (1.AF) and pins where the async `deInlineMedia` pass sits relative to the single producer-side translation point this ADR defines (the gap-free `sequenceNumber` + persist-before-deliver chokepoint is unchanged). This ADR's substrate decisions stand.
 
+> **Amended 2026-06-20 by [ADR-0045](0045-async-media-job-loop-poll-checkpoint-resume-cancel.md).** A refinement, not a reversal: 1.AG adds a new non-terminal node **suspension state** (a parked async media job) + a durable `media_job:submitted` event, both settling through the single `#emitDurable` choke point this ADR defines (the gap-free `sequenceNumber` + persist-before-deliver are unchanged). This ADR's substrate decisions stand.
+
 ## Context
 
 Workstream **1.N** builds the engine run loop: `WorkflowEngine.start(workflowId, input)` / `resume` / `cancel` walking the `RunPlan` (1.M), the `RunEventBus` surfaces subscribe to, and the `RunHandle.events` async iterable every surface consumes. Two of its three contracts are already settled and have a canonical home — the emitted **event shapes** are pinned by [sse-event-schema.md](../reference/contracts/sse-event-schema.md) and the Zod source in `@relavium/shared` (`run-event.ts`), and the **dispatch shape** (a plain async orchestrator over a static topological plan, a dispatch table, state-after-each-node, a *derived* checkpoint, no second state machine, no LangGraph) is pinned by [ADR-0003](0003-pure-ts-engine-not-langgraph-python.md). This ADR does not re-open either; it records the three run-loop **substrate** decisions that no existing ADR covers and that 1.N cannot make implicitly.

docs/decisions/0038-agentrunner-llm-call-boundary.md

@@ -9,6 +9,8 @@
 > the chain's own default backoff. Everything else in this ADR stands. (Within-chain same-model retry of the
 > primary, if wanted, is an optional primary chain-entry `max_attempts`.)
 
+> **Amended 2026-06-20 by [ADR-0046](0046-inline-media-out-via-generate-streaming-triad-deferred.md).** A refinement, not a reversal: the per-node turn loop (stream-only today) gains a single-shot `generate()` branch for a media-output turn (a `media_surface: 'chat'` model whose node requests media `output_modalities`), so inline media-out arrives as an in-flight `media` part in `LlmResult.content` de-inlined at `#emitDurable`. The text-only streaming path + the tool/reasoning/cost machinery are unchanged.
+
 - **Related**: [ADR-0006](0006-os-keychain-for-api-keys.md), [ADR-0011](0011-internal-llm-abstraction.md), [ADR-0018](0018-desktop-execution-and-rust-egress.md), [ADR-0019](0019-cli-node-keychain-library.md), [ADR-0024](0024-agent-first-entry-point-agentsession.md), [ADR-0025](0025-agent-surface-refines-desktop-scope.md), [ADR-0026](0026-session-export-to-workflow.md), [ADR-0028](0028-workflow-resource-governance.md), [ADR-0029](0029-tool-policy-hardening.md), [ADR-0030](0030-llm-seam-shape-amendment-reasoning-response-format-provider-executed.md), [ADR-0036](0036-run-loop-substrate-event-bus-and-execution-host.md), [ADR-0037](0037-engine-tool-execution-boundary.md), [ADR-0039](0039-same-provider-reasoning-replay.md), [ADR-0040](0040-node-retry-budget-above-the-chain.md), [llm-provider-seam.md](../reference/shared-core/llm-provider-seam.md), [run-plan.md](../reference/shared-core/run-plan.md), [sse-event-schema.md](../reference/contracts/sse-event-schema.md), [error-handling.md](../standards/error-handling.md), [security-review.md](../standards/security-review.md), [shared-core-engine.md](../architecture/shared-core-engine.md)
 
 ## Context