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

[cemililik]

What this is

1.AG — Output generation (Phase D, 1.m6): media output across the @relavium/llm seam, built on the 1.AF media substrate. Both inline media-out (a chat model emitting media in a turn) and separate-endpoint generation (generateMedia) — synchronous (gpt-image-1) and the engine-owned async long-running-operation loop (Sora/Veo-shaped jobs: park → poll → checkpoint → resume → cancel). Governed by two new ADRs:

• ADR-0045 — the async media-job LRO (durable media_job:submitted, the derived pendingMediaJobs checkpoint slot, re-attach-on-resume, host-timer poll cadence, deadline→timeout, cancel→abort→sweep, the one realized cost addend).
• ADR-0046 — inline media-out via the existing chain.generate(); the streaming triad host-deferred to 1.AH.

How it was built — five sections, each dual-reviewed

Section	Scope
A Contracts & shapes	pollMediaJob seam signal param, media_job:submitted event, pendingMediaJobs slot, content_filter ErrorCode, model_catalog.media_surface, poll-cadence config defaults
B Inline media-out	Gemini responseModalities + OpenAI inline audio → generate(); the runner de-inlines media parts to media:// handles
C Sync generateMedia + routing	the AgentRunner generative dispatch fork, the OpenAI gpt-image-1 adapter, the pre-egress gate + the lone realized cost addend
D Async media-job LRO	the engine-owned poll/checkpoint/resume/cancel loop (MJ-1 re-attach, AG-A-FC-3 gate-vs-media disambiguation, deadline→retryable-timeout, cancel→terminal sweep)
E Acceptance + conformance + docs	the cancel-sweep acceptance test, generative conformance (sync OpenAI + a stub async seam-contract suite), the reserved→wired doc reconcile

Each section ran the same loop: develop → Opus adversarial review → fix → Sonnet adversarial review → fix — all rounds 0 blocker/high.

Final pre-PR review (the whole workstream)

A comprehensive full-diff pass (18 dimension/area/integration finders → dedup → 2 perspective+model-diverse adversarial verifiers per finding) caught two real cross-section bugs no per-section review could see, now fixed with regression tests:

• H1 — media_job:submitted was missing from RESUMABLE_LAST_TYPES: a crash in the submit→pause window reconciled the run to run:failed, orphaning a paid, still-generating provider LRO (the checkpoint fold already treated it as resumable — the two classifications disagreed).
• H2 — resumeFromCheckpoint leaked the constructor-armed poll/run-timeout timers when a resume misuse-guard threw, so an orphan timer kept polling the provider for a rejected run (and a retry could double-attach the same jobId). Fixed via a new RunExecution.abandon().

A focused re-verification of the fix round returned GO (both HIGH fixes independently reproduced pre-fix / confirmed post-fix; regression sweep clean). The remaining low/nit findings were fixed or recorded as 1.AH deferrals — notably no generative MODEL_PRICING rows were fabricated (the mis-bill risk Section C deliberately avoided).

Invariants held (verified clean)

I3 durable-boundary byte-safety (all three media-out paths de-inline to media://sha256-… handles) · ADR-0011 seam purity (no vendor type crosses the seam; opaque jobId) · engine purity (zero platform imports; all timing via injected setTimer) · secret redaction (keyFor-throw → fixed secret-free error on both sync and async paths) · exactly-one-terminal · exactly-one realized cost addend across every terminal path.

Deferred to 1.AH (recorded in deferred-tasks.md)

The real Sora/Veo pollMediaJob adapters + OpenAI-TTS/Gemini-Imagen sync adapters, the per-model media_surface host lookup, verified generative pricing rows, and the streaming media triad. No generative model is runtime-reachable in Phase 1 (the engine mechanism + the OpenAI-image adapter are proven via injected-surface tests + a conforming stub).

Validation

pnpm turbo run lint typecheck test build — 16/16 green (core 846 tests, llm 381+8 skipped). Leakwatch — 0 findings. The 1.AG roadmap row is intentionally NOT marked ✅ Done — it flips on merge (Roadmap-Done-After-Merge).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added async long-running media generation for agent nodes with polling, durable checkpoint resume/reattach, and best-effort cancellation.
  • Introduced model “media surface” routing for chat vs generative media flows.
  • Updated inline media output to use non-streaming generation for media parts.
• Bug Fixes
  • Enforced non-retryable failures when requested media isn’t returned and improved content_filter fatal handling.
  • Improved media cost rounding consistency.
• Documentation
  • Updated ADRs, roadmap/status, contracts (including SSE run events), and config/media capability references.
• Tests
  • Expanded end-to-end, engine, adapter, checkpoint, and conformance coverage for inline and async media.

[sourcery-ai]

Sorry @cemililik, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 97da971a-a4e3-4851-b432-bfb3584479dc

📥 Commits

Reviewing files that changed from the base of the PR and between 30915d9 and c34238f.

📒 Files selected for processing (3)

• packages/core/src/engine/agent-runner.test.ts
• packages/core/src/engine/engine.ts
• packages/core/src/engine/m2-e2e-harness.e2e.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/core/src/engine/engine.ts
• packages/core/src/engine/m2-e2e-harness.e2e.test.ts
• packages/core/src/engine/agent-runner.test.ts

---

📝 Walkthrough

Walkthrough

This PR implements 1.AG engine sections A–E: async media-job loop (ADR-0045) and inline media-out routing (ADR-0046), wiring media-surface discriminator through database schema, shared constants, LLM adapters, agent-runner generative fork, agent-turn generate path, checkpoint reconstruction with pending media jobs, and a complete WorkflowEngine lifecycle for media-job park/poll/resume/cancel/settle with pre-egress budget gating, realized cost emission, and checkpoint re-attachment semantics. Includes comprehensive unit and end-to-end tests, conformance suite updates, and aligned documentation.

Changes

1.AG Engine Media Pipeline (Async Job Loop and Inline Media-Out)

Layer / File(s)	Summary
ADRs, reference specs, roadmap, and status docs docs/decisions/0045-async-media-job-..., docs/decisions/0046-inline-media-out-..., docs/decisions/0031/0036/0038/0040-... (amended), docs/reference/contracts/*, docs/reference/shared-core/*, docs/reference/desktop/database-schema.md, docs/standards/error-handling.md, docs/roadmap/*, CLAUDE.md, README.md	Adds ADR-0045 (async media-job loop with park/poll/resume/cancel semantics, durable state via media_job:submitted, cost gating/realization, content_filter taxonomy) and ADR-0046 (inline media-out via generate() with de-inline at #emitDurable, streaming triad deferred to host). Amends ADR-0031/0036/0038/0040 to reflect media seam changes. Updates all reference contracts, provider seam, agent-runner, node-types, error-handling docs. Updates roadmap/current status to mark 1.AF done and 1.AG sections A–E landed on development.
Shared constants, run events, node schema, and config defaults packages/shared/src/constants.ts, packages/shared/src/constants.test.ts, packages/shared/src/run-event.ts, packages/shared/src/run-event.test.ts, packages/shared/src/node.ts, packages/shared/src/node.test.ts, packages/shared/src/config.ts, packages/shared/src/config.test.ts	Adds MEDIA_SURFACES ('chat' / 'generative'), MEDIA_JOB_POLL_DEFAULTS, content_filter as fatal non-retryable error code, media_job:submitted run-event schema with jobId/provider/model/modality/startedAt/deadlineAt. Updates run:paused to support media-only suspension with pendingMediaJobNodeIds and relaxes pendingGateCount to non-negative. Adds agent node count/duration_seconds volume knobs. Adds config defaults for media_job_poll_initial_ms, media_job_poll_max_ms, media_job_deadline_ms with cross-field validation.
Database schema migration and LLM seam contracts packages/db/drizzle/0004_numerous_ultimatum.sql, packages/db/drizzle/meta/_journal.json, packages/db/drizzle/meta/0004_snapshot.json, packages/db/src/schema.ts, packages/llm/src/types.ts, packages/llm/src/cost-tracker.ts, packages/llm/src/cost-tracker.test.ts, packages/llm/src/budget-estimator.ts, packages/llm/src/fallback-chain.ts	Adds media_surface text NOT NULL DEFAULT 'chat' to model_catalog via SQL migration with Drizzle schema and snapshot. Extends MediaCapabilitiesSchema with optional surface field, updates pollMediaJob signature to accept optional signal?: AbortSignalLike for aborting in-flight polls. Rounds per-entry media costs to integer micro-cents in both mediaCost() and estimateMediaCost() to align realized with estimated. Fixes NUL-character escape in fallback-chain cache key.
LLM adapters: streaming guard, media output, generateMedia support packages/llm/src/adapters/shared.ts, packages/llm/src/adapters/gemini.ts, packages/llm/src/adapters/gemini.test.ts, packages/llm/src/adapters/openai.ts, packages/llm/src/adapters/openai.test.ts, packages/llm/src/adapters/anthropic.ts, packages/llm/src/adapters/anthropic.test.ts	Introduces assertNoStreamingMediaOutput guard to prevent streaming requests with media-out modalities. Gemini: emits inlineData as base64 media parts, lowers outputModalities to responseModalities on generate. OpenAI: adds inline audio output parsing from message.audio, implements generateMedia for synchronous image generation mapping to base64, normalizes content-policy/moderation errors to content_filter code. All adapters annotate surface: 'chat' in capabilities. Includes comprehensive tests for round-trip normalization and error mapping.
LLM conformance: generative seam and media surface validation packages/llm/src/conformance/generative-seam.conformance.test.ts, packages/llm/src/conformance/spec.ts, packages/llm/src/conformance/fixtures/openai.ts	Adds generative-seam conformance tests covering generateMedia result shape validation, MediaGenResult exactly-one-of (jobId vs media), polling state transitions (pending → done → failed), content_filter error classification as non-retryable, and abort-signal forwarding identity. Extends ConformanceExpectations/ConformanceFixtures with mediaGenerate for sync generateMedia. Adds media-surface capability value validation. Wires OpenAI image-generation fixture.
Core executor contracts and catalog validation packages/core/src/engine/node-executor.ts, packages/core/src/engine/node-handlers/dispatcher.ts, packages/core/src/index.ts, packages/core/src/validate-catalog.ts, packages/core/src/validate-catalog.test.ts	Introduces MediaJobSubmission interface with jobId/provider/model/modality/units/deadlineMs. Extends NodeOutcome with kind: 'media_job' variant. Adds optional pollMediaJob(job, signal) to NodeExecutor interface. Wires dispatcher to conditionally forward pollMediaJob when agent handler is present. Re-exports CheckpointPendingMediaJob. Updates catalog validation to bypass output-combination checks for generative-surface models and require exactly one billed media modality.
Agent turn: media-output generate branch and error mapping packages/core/src/engine/agent-turn.ts, packages/core/src/engine/agent-turn.test.ts	Exports codeForLlmError for media dispatch reuse. Omits tools in LLM requests when non-text outputModalities are requested. Introduces generateOneTurn non-streaming wrapper. Refactors error mapping through throwMappedChainError helper. Adds early media-output branch with requestsMediaOutput predicate that applies primary-model pre-egress budget gate, calls chain.generate(), validates stop-reason (throws provider_unavailable on tool_use), and maps failures. Includes tests for inline media routing, cost events, failover, budget exceed, cancellation, and content_filter classification.
AgentRunner: media-surface fork and executeGenerativeMedia packages/core/src/engine/agent-runner.ts, packages/core/src/engine/agent-runner.test.ts	Extends AgentRunnerDeps with optional resolveMediaSurface(model) dependency. Routes to executeGenerativeMedia for 'generative' models, otherwise continues chat-turn. executeGenerativeMedia validates exactly one billed modality, requires non-empty prompt, verifies provider.generateMedia exists, computes authored units, applies pre-egress budget gate with maxTokens: 0, checks cancellation, resolves credentials with secret redaction on failure, calls provider, and returns either sync media parts or async media_job jobId. Adds pollMediaJobThroughDeps helper that re-resolves provider/credentials and gracefully handles missing/failing polling. Extracts inline media from chat-turn results, fails non-retryable validation when media requested but not produced. Exports generativeUnits/realizedMediaCost helpers. Comprehensive test coverage.
Checkpoint: pending media job reconstruction and settlement tracking packages/core/src/engine/checkpoint.ts, packages/core/src/engine/checkpoint.test.ts	Introduces CheckpointPendingMediaJob interface storing opaque jobId, provider/model/modality, and submit/deadline timestamps. Extends CheckpointState with pendingMediaJobs array. Implements applyMediaJobEvent that folds media_job:submitted into reconstruction: marks node as paused, per-node latest-wins keying, defensive stale-event skipping (events for already-terminal nodes ignored). Clears pending jobs when nodes reach terminal settlement (completed/failed/skipped). Tests validate per-node isolation and stale-event idempotence.
WorkflowEngine: async media park/poll/resume/cancel lifecycle packages/core/src/engine/engine.ts, packages/core/src/engine/engine.test.ts, packages/core/src/engine/errors.ts, packages/core/src/engine/execution-host.ts, packages/core/src/engine/execution-host.test.ts	Introduces ParkedMediaJob runtime record and per-run poll timer disarms. On checkpoint resume, re-attaches jobs by reconstructing metadata (deadline, units, submittedAtMs). Nodes parked on media_job outcomes emit durable media_job:submitted, record in-memory parked job, and arm poll timers. Idle handling emits run:paused with pendingMediaJobNodeIds when media jobs pending. Poll loop with deadline short-circuit, adapter fault classification, and exponential backoff. Terminal settlement disarms timers, emits realized cost addends for still-pending jobs, then clears state. Paused nodes transition to failed on internal failure. Updates resumeFromCheckpoint input to optional gate fields (both provided = gate resume, both omitted = media-only resume), adds assertValidResumeInput, introduces beginResumeMediaJobs, and routes correctly. Adds pending_gate_requires_decision error code. Updates crash reconciliation to classify media_job:submitted as resumable. Comprehensive engine tests.
M2 end-to-end harness: full media scenario coverage packages/core/src/engine/m2-e2e-harness.e2e.test.ts	Adds media-specific test infrastructure: inline/generative/async media provider stubs with scripted responses and call-count tracking. Poll-timer driver concurrently consumes run events and fires armed timers until terminal settlement. In-memory MediaStore storing bytes with deterministic media://sha256-... handle generation. Media capability fixtures and workflow fixtures for inline-out, generative-out, concurrent gate+job scenarios. End-to-end tests validate inline routing and de-inline to handles with base64 exclusion, generative routing with raw diagnostic exclusion, async job submit/poll success and failure with content_filter terminal errors, cross-process checkpoint re-attach without re-submission, cancel behavior (abort in-flight polls, cleanup), concurrent gate+media resume (both advance), rejection of media-only resume without gate decision, deadline short-circuit to retryable timeout, abort signal propagation, loud failure on unknown poll states, and repeated pending polls with correct backoff/re-arming.

Sequence Diagram(s)

sequenceDiagram
  participant Host
  participant WorkflowEngine
  participant AgentRunner
  participant LlmAdapter
  participant RunStore

  Host->>WorkflowEngine: executeRun(workflow)
  WorkflowEngine->>AgentRunner: executeAgent(node)
  AgentRunner->>AgentRunner: resolveMediaSurface(model)
  alt surface is 'generative'
    AgentRunner->>LlmAdapter: generateMedia(request)
    LlmAdapter-->>AgentRunner: MediaGenResult {jobId}
    AgentRunner-->>WorkflowEngine: NodeOutcome {kind:'media_job'}
    WorkflowEngine->>RunStore: persist media_job:submitted
    WorkflowEngine->>WorkflowEngine: arm poll timer
    loop poll with backoff until terminal
      WorkflowEngine->>LlmAdapter: pollMediaJob(jobId, signal)
      LlmAdapter-->>WorkflowEngine: MediaJobStatus
    end
    WorkflowEngine->>RunStore: emit cost:updated addend
    WorkflowEngine->>RunStore: emit node:completed/failed
    WorkflowEngine-->>Host: terminal node event
  else surface is 'chat'
    AgentRunner->>LlmAdapter: generate(request with outputModalities)
    LlmAdapter-->>AgentRunner: LlmResult {content:[media part]}
    AgentRunner->>RunStore: de-inline media to media://sha256-...
    AgentRunner-->>WorkflowEngine: NodeOutcome {kind:'completed'}
    WorkflowEngine-->>Host: node completed event
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• HodeTech/Relavium#11: Introduced the LlmProvider multimodal seam contracts (generateMedia, pollMediaJob, outputModalities) that this PR fully implements and extends with the signal parameter and surface capability field.
• HodeTech/Relavium#17: Established the human-gate checkpoint/resume machinery in checkpoint.ts and engine.ts that this PR extends with the parallel pendingMediaJobs park/resume/cancel path.
• HodeTech/Relavium#18: Introduced the AgentRunner/agent-turn core execution path that this PR extends with the resolveMediaSurface fork, executeGenerativeMedia, and the inline media-out generateOneTurn branch.

Poem

🐇 Hoppity-hop through the media lane,
A generate() call, no streaming refrain.
Jobs park and poll till the pixels arrive,
content_filter blocked? Fatal — don't retry!
Resume, re-attach, the checkpoint holds tight,
Base64 de-inlined to a media:// bright. 🖼️

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: introducing 1.AG media output generation (Phase D) governed by ADR-0045/0046, implementing async media-job and inline media-out capabilities. It directly matches the scope and main objective of this comprehensive changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 93.65% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch development

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request implements Phase 1.AG (Output Generation) of the multimodal sub-spine, introducing support for both inline media-out (via a single-shot generate() call) and separate-endpoint generative media (via generateMedia and an engine-owned async poll/checkpoint/resume/cancel loop). It updates the database schema, SSE event schema, and workflow specs to support these new capabilities, alongside comprehensive end-to-end and unit tests. The review feedback correctly identifies a critical issue in the OpenAI adapter's generateMedia implementation, where the images.generate call incorrectly passes an unsupported output_format parameter and fails to specify response_format: 'b64_json', which is required to retrieve the expected base64 image data.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

There are two critical issues with this images.generate call against the official OpenAI API:

1. OpenAI's images.generate endpoint does not support an output_format parameter. Passing it will result in a 400 Bad Request error.
2. The default response_format for OpenAI's image generation is 'url'. Since the code expects base64 data (response.data?.[0]?.b64_json), you must explicitly request response_format: 'b64_json'. Otherwise, the call will always fail to retrieve the base64 image data.

        response = await createClient(key).images.generate(
          {
            model: req.model,
            prompt: req.prompt,
            response_format: 'b64_json',
          },
          isAbortSignal(req.signal) ? { signal: req.signal } : {},
        );

[coderabbitai]

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/reference/shared-core/agent-runner.md (1)

23-34: ⚠️ Potential issue | 🟡 Minor

The pre-egress budget gate statement is correct but should link to the canonical gate definition.

Line 34's claim that "a pre-egress budget gate runs first (gate-only, maxTokens: 0)" is accurate (confirmed in agent-runner.ts lines 456–460). However, per the documentation guideline ("link, don't restate"), this spec should provide a link to the gate's canonical definition (e.g., BudgetGovernor, or the ADR covering pre-egress gating) rather than inline the mechanism (maxTokens: 0). The rationale for the zero-token estimate (generative calls emit no tokens) belongs in implementation comments, not the spec. Add a link to clarify where readers can find the full gate contract and cost-accounting behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/reference/shared-core/agent-runner.md` around lines 23 - 34, In the
Generative fork subsection describing the dispatch behavior for `'generative'`
models, the statement about the pre-egress budget gate currently inlines the
mechanism detail `maxTokens: 0` in the spec. Remove the inline mechanism
explanation and replace it with a link to the canonical gate definition (such as
BudgetGovernor or the relevant ADR covering pre-egress gating). Keep the
high-level claim that "a pre-egress budget gate runs first" but delegate the
implementation rationale (why it uses zero tokens) to implementation comments
rather than the specification.

Source: Coding guidelines

🧹 Nitpick comments (3)

packages/llm/src/conformance/generative-seam.conformance.test.ts (1)

48-51: ⚡ Quick win

Prefer interface for GenerativeProvider object shape.

Use an interface here to align with the TypeScript style standard used in this repo.

As per coding guidelines, “Prefer interface for defining object shapes in TypeScript (per docs/standards/code-style-typescript.md)”.

Proposed refactor

-type GenerativeProvider = LlmProvider & {
+interface GenerativeProvider extends LlmProvider {
   generateMedia: NonNullable<LlmProvider['generateMedia']>;
   pollMediaJob: NonNullable<LlmProvider['pollMediaJob']>;
-};
+}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/llm/src/conformance/generative-seam.conformance.test.ts` around
lines 48 - 51, The GenerativeProvider type alias should be converted to an
interface to align with the repository's TypeScript style standards. Replace the
type alias definition with an interface that extends LlmProvider and includes
the generateMedia and pollMediaJob properties as required (non-nullable) members
instead of using type intersection with NonNullable utility types.

Source: Coding guidelines

packages/core/src/engine/agent-runner.test.ts (1)

796-802: ⚡ Quick win

Extend the invariant test to include the “both present” invalid result.

This currently asserts only the neither media nor jobId guard. Add a sibling case for { media, jobId } so the full XOR invariant is regression-protected.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/engine/agent-runner.test.ts` around lines 796 - 802, The
current test case only verifies the invariant guard for when neither media nor
jobId are present in the result (the empty object case). Add a sibling test case
immediately after this one that checks the opposite invalid scenario where both
media and jobId are present in the result, ensuring the full XOR invariant is
regression-protected. Both test cases should use createAgentNodeExecutor with a
generativeProvider configured with the respective invalid result objects and
verify that the executor correctly fails with an internal error in both cases.

packages/core/src/validate-catalog.test.ts (1)

39-50: ⚡ Quick win

Add the negative generative-shape case in this suite.

This covers the valid 'generative' + ['image'] path, but not invalid shapes (e.g., ['text','image'] or multiple media modalities). Add one failing case so catalog validation and runtime generative-shape rules cannot drift.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/validate-catalog.test.ts` around lines 39 - 50, Add a
negative test case in the same suite to validate that invalid generative-shape
configurations are properly rejected. Create a new test using agentWorkflow with
invalid output_modalities (such as combining multiple incompatible modalities
like 'text' and 'image'), set up the generativeCaps CapabilityFlags with the
'generative' surface, and expect validateWorkflowWithCatalog to throw an error
for that invalid configuration. This ensures the catalog validation rules for
generative-surface models remain consistent and prevent invalid shapes from
being accepted.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reference/contracts/workflow-yaml-spec.md`:
- Line 228: Replace the ~100-word "Inline delivery (1.AG Section B,
[ADR-0046]...)" subsection with a condensed statement that references ADR-0046
instead of restating the behavior. The replacement should briefly note that when
output_modalities requests media, a chat-surface model issues a single-shot
generate() with no tool access, then link to ADR-0046 Section 1 for the full
details on de-inlining media to handles. Keep the remaining subsections on
vocabulary constraints and generative routing intact.

In `@packages/core/src/engine/agent-runner.ts`:
- Around line 529-555: The code at the async LRO branch (the first if statement
checking `result.jobId !== undefined`) does not verify that media is absent
before treating the result as an async job. Add an explicit guard before this
async-job branch to ensure both jobId and media are not present simultaneously,
enforcing the XOR relationship. If both jobId and media exist, return a failed
result with an appropriate error message indicating the provider returned an
invalid result with both fields populated, ensuring media is not silently
discarded.

In `@packages/core/src/engine/m2-e2e-harness.e2e.test.ts`:
- Around line 1002-1004: In the pollMediaJob method, replace the unsafe double
cast `as unknown as MediaJobStatus` with a `@ts-expect-error` suppression
comment. Add the `@ts-expect-error` comment on the line above or inline before
the return value, then remove the cast entirely so the function simply returns
`{ state: 'frozen' }` directly, allowing TypeScript to suppress the type
mismatch error while keeping the test intention clear.

In `@packages/core/src/validate-catalog.ts`:
- Around line 36-43: The unconditional `continue` statement in the generative
media surface block bypasses all catalog-time validation for the
output_modalities, allowing invalid declarations (such as multiple media
modalities or text mixed with media) to pass and only fail at runtime. Add
validation logic before the `continue` statement that enforces the same rule as
runtime dispatch: ensure the generative model's output_modalities contains
exactly one billed media modality with no text. If this validation fails, raise
an appropriate error instead of allowing the validation check to be skipped.

In `@packages/db/drizzle/0004_numerous_ultimatum.sql`:
- Line 1: The migration file 0004_numerous_ultimatum.sql and its associated meta
artifacts are out of sync with the database schema. Navigate to the `@relavium/db`
package and run the pnpm db:generate command filtered to that workspace, then
commit all regenerated migration and meta artifact files to resolve the schema
drift error reported by CI.

In `@packages/shared/src/run-event.ts`:
- Around line 279-283: The MediaJobSubmittedEventSchema allows deadlineAt to be
earlier than startedAt, which can admit malformed durable events and break
timeout semantics during resume/replay. Add a validation constraint to the
schema definition (using a method like .refine()) that enforces deadlineAt is
always greater than or equal to startedAt to ensure timestamp ordering is always
valid.

---

Outside diff comments:
In `@docs/reference/shared-core/agent-runner.md`:
- Around line 23-34: In the Generative fork subsection describing the dispatch
behavior for `'generative'` models, the statement about the pre-egress budget
gate currently inlines the mechanism detail `maxTokens: 0` in the spec. Remove
the inline mechanism explanation and replace it with a link to the canonical
gate definition (such as BudgetGovernor or the relevant ADR covering pre-egress
gating). Keep the high-level claim that "a pre-egress budget gate runs first"
but delegate the implementation rationale (why it uses zero tokens) to
implementation comments rather than the specification.

---

Nitpick comments:
In `@packages/core/src/engine/agent-runner.test.ts`:
- Around line 796-802: The current test case only verifies the invariant guard
for when neither media nor jobId are present in the result (the empty object
case). Add a sibling test case immediately after this one that checks the
opposite invalid scenario where both media and jobId are present in the result,
ensuring the full XOR invariant is regression-protected. Both test cases should
use createAgentNodeExecutor with a generativeProvider configured with the
respective invalid result objects and verify that the executor correctly fails
with an internal error in both cases.

In `@packages/core/src/validate-catalog.test.ts`:
- Around line 39-50: Add a negative test case in the same suite to validate that
invalid generative-shape configurations are properly rejected. Create a new test
using agentWorkflow with invalid output_modalities (such as combining multiple
incompatible modalities like 'text' and 'image'), set up the generativeCaps
CapabilityFlags with the 'generative' surface, and expect
validateWorkflowWithCatalog to throw an error for that invalid configuration.
This ensures the catalog validation rules for generative-surface models remain
consistent and prevent invalid shapes from being accepted.

In `@packages/llm/src/conformance/generative-seam.conformance.test.ts`:
- Around line 48-51: The GenerativeProvider type alias should be converted to an
interface to align with the repository's TypeScript style standards. Replace the
type alias definition with an interface that extends LlmProvider and includes
the generateMedia and pollMediaJob properties as required (non-nullable) members
instead of using type intersection with NonNullable utility types.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8719a371-a845-4873-ad0e-84183715136c

📥 Commits

Reviewing files that changed from the base of the PR and between 5d26e7b and 717bc97.

📒 Files selected for processing (64)

• CLAUDE.md
• README.md
• docs/decisions/0031-llm-seam-shape-amendment-multimodal-io.md
• docs/decisions/0036-run-loop-substrate-event-bus-and-execution-host.md
• docs/decisions/0038-agentrunner-llm-call-boundary.md
• docs/decisions/0040-node-retry-budget-above-the-chain.md
• docs/decisions/0045-async-media-job-loop-poll-checkpoint-resume-cancel.md
• docs/decisions/0046-inline-media-out-via-generate-streaming-triad-deferred.md
• docs/decisions/README.md
• docs/reference/contracts/config-spec.md
• docs/reference/contracts/sse-event-schema.md
• docs/reference/contracts/workflow-yaml-spec.md
• docs/reference/desktop/database-schema.md
• docs/reference/shared-core/agent-runner.md
• docs/reference/shared-core/llm-provider-seam.md
• docs/reference/shared-core/node-types.md
• docs/roadmap/current.md
• docs/roadmap/deferred-tasks.md
• docs/roadmap/phases/phase-1-engine-and-llm.md
• docs/standards/error-handling.md
• packages/core/src/engine/agent-runner.test.ts
• packages/core/src/engine/agent-runner.ts
• packages/core/src/engine/agent-turn.test.ts
• packages/core/src/engine/agent-turn.ts
• packages/core/src/engine/checkpoint.test.ts
• packages/core/src/engine/checkpoint.ts
• packages/core/src/engine/engine.test.ts
• packages/core/src/engine/engine.ts
• packages/core/src/engine/errors.ts
• packages/core/src/engine/execution-host.test.ts
• packages/core/src/engine/execution-host.ts
• packages/core/src/engine/m2-e2e-harness.e2e.test.ts
• packages/core/src/engine/node-executor.ts
• packages/core/src/engine/node-handlers/dispatcher.ts
• packages/core/src/index.ts
• packages/core/src/validate-catalog.test.ts
• packages/core/src/validate-catalog.ts
• packages/db/drizzle/0004_numerous_ultimatum.sql
• packages/db/drizzle/meta/0004_snapshot.json
• packages/db/drizzle/meta/_journal.json
• packages/db/src/schema.ts
• packages/llm/src/adapters/anthropic.test.ts
• packages/llm/src/adapters/anthropic.ts
• packages/llm/src/adapters/gemini.test.ts
• packages/llm/src/adapters/gemini.ts
• packages/llm/src/adapters/openai.test.ts
• packages/llm/src/adapters/openai.ts
• packages/llm/src/adapters/shared.ts
• packages/llm/src/budget-estimator.ts
• packages/llm/src/conformance/fixtures/openai.ts
• packages/llm/src/conformance/generative-seam.conformance.test.ts
• packages/llm/src/conformance/spec.ts
• packages/llm/src/cost-tracker.test.ts
• packages/llm/src/cost-tracker.ts
• packages/llm/src/fallback-chain.ts
• packages/llm/src/types.ts
• packages/shared/src/config.test.ts
• packages/shared/src/config.ts
• packages/shared/src/constants.test.ts
• packages/shared/src/constants.ts
• packages/shared/src/node.test.ts
• packages/shared/src/node.ts
• packages/shared/src/run-event.test.ts
• packages/shared/src/run-event.ts

[cemililik]

@coderabbitai review all

[coderabbitai]

@cemililik Sure! I'll kick off a full review of all the changes in this PR.

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 6

♻️ Duplicate comments (1)

packages/db/drizzle/0004_numerous_ultimatum.sql (1)

1-1: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Regenerate Drizzle artifacts; CI still reports schema drift.

The DB pipeline is still failing with @relavium/db migration is out of sync with src/schema.ts. Please rerun generation for @relavium/db and commit all resulting drizzle SQL/meta artifacts together.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/db/drizzle/0004_numerous_ultimatum.sql` at line 1, The migration
file for adding the `media_surface` column to the `model_catalog` table is out
of sync with the schema definition in src/schema.ts, causing CI to report schema
drift. Regenerate all Drizzle artifacts for the `@relavium/db` package by running
the appropriate Drizzle generation command, which will update both the SQL
migration files and metadata artifacts. Commit all generated Drizzle files
together to ensure the migration and schema definition are synchronized.

Source: Pipeline failures

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/engine/agent-runner.test.ts`:
- Around line 672-675: The test function starting with "gates pre-egress with
maxTokens:0 + the media estimate → budget_exceeded (no generateMedia egress)"
has a duplicate declaration of the `info` variable in the same scope, causing a
TypeScript compile error. Search through this test function and identify both
declarations of `let info`, then remove one of the duplicate declarations to
ensure only a single `info` variable declaration exists within the test scope.

In `@packages/core/src/engine/engine.ts`:
- Around line 1407-1411: The condition checking `vertex === undefined` in the
media job resume handler currently returns silently without clearing the job
from `#pendingMediaJobs`, leaving the parked media job in an inconsistent state.
Instead of returning when the vertex is missing, you should treat this as a
terminal failure by clearing the job from `#pendingMediaJobs` before returning,
ensuring the job is properly cleaned up and the run does not get stranded in a
paused state. This cleanup is particularly important in the checkpoint and
workflow-drift code paths.

In `@packages/core/src/engine/m2-e2e-harness.e2e.test.ts`:
- Around line 182-210: The pollMediaJob method in the asyncMediaProvider
function currently ignores the _jobId parameter, which means the test doesn't
validate that the correct job ID is being re-polled on resume. Add validation
logic to the pollMediaJob method to assert that the incoming _jobId matches the
expected job ID (which should be 'job-1', the jobId returned from
generateMedia). If the jobId doesn't match the expected value, have the method
reject with an error instead of silently proceeding. This ensures the test
properly covers the invariant that the persisted jobId is actually being
re-polled during checkpoint re-attachment.
- Around line 1005-1009: The `@ts-expect-error` comment in the `pollMediaJob`
function is currently three lines long, which violates the style guide
requirement for one-line justifications. Extract the detailed explanation (the
parts about out-of-union job state, closed-switch's default arm, and terminal
failure) as a separate regular comment block placed directly above the
`@ts-expect-error` directive. Then reduce the `@ts-expect-error` comment itself
to a single-line justification that briefly explains why the type error is being
suppressed.

In `@packages/core/src/validate-catalog.ts`:
- Around line 44-46: The filter operation in the billed constant uses an unsafe
type cast `as readonly string[]` on MEDIA_BILLED_MODALITIES, which weakens type
safety. Replace this unsafe cast by creating a type guard function that properly
checks if a modality is included in MEDIA_BILLED_MODALITIES without using the
`as` assertion, then use that type guard in the filter operation instead of the
cast.

In `@packages/llm/src/types.ts`:
- Around line 200-205: The comment describing the `surface` field in the
media-output routing documentation contains outdated information. The comment
claims that no Phase-1 adapter implements `generateMedia`, but the OpenAI
adapter in packages/llm/src/adapters/openai.ts actually does implement sync
`generateMedia` for image generation. Update the comment on the line that
discusses Phase-1 adapter implementations to accurately reflect that at least
the OpenAI adapter supports `generateMedia`, removing or correcting the
statement that none of them implement it.

---

Duplicate comments:
In `@packages/db/drizzle/0004_numerous_ultimatum.sql`:
- Line 1: The migration file for adding the `media_surface` column to the
`model_catalog` table is out of sync with the schema definition in
src/schema.ts, causing CI to report schema drift. Regenerate all Drizzle
artifacts for the `@relavium/db` package by running the appropriate Drizzle
generation command, which will update both the SQL migration files and metadata
artifacts. Commit all generated Drizzle files together to ensure the migration
and schema definition are synchronized.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d8f275a-7b27-4f55-817c-fa4afbbe43ad

📥 Commits

Reviewing files that changed from the base of the PR and between 5d26e7b and 123c6b9.

📒 Files selected for processing (64)

• CLAUDE.md
• README.md
• docs/decisions/0031-llm-seam-shape-amendment-multimodal-io.md
• docs/decisions/0036-run-loop-substrate-event-bus-and-execution-host.md
• docs/decisions/0038-agentrunner-llm-call-boundary.md
• docs/decisions/0040-node-retry-budget-above-the-chain.md
• docs/decisions/0045-async-media-job-loop-poll-checkpoint-resume-cancel.md
• docs/decisions/0046-inline-media-out-via-generate-streaming-triad-deferred.md
• docs/decisions/README.md
• docs/reference/contracts/config-spec.md
• docs/reference/contracts/sse-event-schema.md
• docs/reference/contracts/workflow-yaml-spec.md
• docs/reference/desktop/database-schema.md
• docs/reference/shared-core/agent-runner.md
• docs/reference/shared-core/llm-provider-seam.md
• docs/reference/shared-core/node-types.md
• docs/roadmap/current.md
• docs/roadmap/deferred-tasks.md
• docs/roadmap/phases/phase-1-engine-and-llm.md
• docs/standards/error-handling.md
• packages/core/src/engine/agent-runner.test.ts
• packages/core/src/engine/agent-runner.ts
• packages/core/src/engine/agent-turn.test.ts
• packages/core/src/engine/agent-turn.ts
• packages/core/src/engine/checkpoint.test.ts
• packages/core/src/engine/checkpoint.ts
• packages/core/src/engine/engine.test.ts
• packages/core/src/engine/engine.ts
• packages/core/src/engine/errors.ts
• packages/core/src/engine/execution-host.test.ts
• packages/core/src/engine/execution-host.ts
• packages/core/src/engine/m2-e2e-harness.e2e.test.ts
• packages/core/src/engine/node-executor.ts
• packages/core/src/engine/node-handlers/dispatcher.ts
• packages/core/src/index.ts
• packages/core/src/validate-catalog.test.ts
• packages/core/src/validate-catalog.ts
• packages/db/drizzle/0004_numerous_ultimatum.sql
• packages/db/drizzle/meta/0004_snapshot.json
• packages/db/drizzle/meta/_journal.json
• packages/db/src/schema.ts
• packages/llm/src/adapters/anthropic.test.ts
• packages/llm/src/adapters/anthropic.ts
• packages/llm/src/adapters/gemini.test.ts
• packages/llm/src/adapters/gemini.ts
• packages/llm/src/adapters/openai.test.ts
• packages/llm/src/adapters/openai.ts
• packages/llm/src/adapters/shared.ts
• packages/llm/src/budget-estimator.ts
• packages/llm/src/conformance/fixtures/openai.ts
• packages/llm/src/conformance/generative-seam.conformance.test.ts
• packages/llm/src/conformance/spec.ts
• packages/llm/src/cost-tracker.test.ts
• packages/llm/src/cost-tracker.ts
• packages/llm/src/fallback-chain.ts
• packages/llm/src/types.ts
• packages/shared/src/config.test.ts
• packages/shared/src/config.ts
• packages/shared/src/constants.test.ts
• packages/shared/src/constants.ts
• packages/shared/src/node.test.ts
• packages/shared/src/node.ts
• packages/shared/src/run-event.test.ts
• packages/shared/src/run-event.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Handle missing resume-plan vertex as a terminal failure, not a silent return.

At Line 1409, returning when vertex === undefined after timer disarm leaves the parked media job uncleared and un-rearmed. This can strand the run in a paused/inconsistent state in the checkpoint/workflow-drift path already tolerated during seeding.

💡 Suggested fix

-    if (this.#settled || job === undefined || vertex === undefined) {
-      return; // run terminal, job cleared, or vertex gone
-    }
+    if (this.#settled || job === undefined) {
+      return; // run terminal or job cleared
+    }
+    if (vertex === undefined) {
+      this.#emitMediaJobCost(nodeId, job);
+      this.#clearMediaJob(nodeId);
+      if (this.#failure === undefined && !this.#cancelling) {
+        this.#failure = {
+          nodeId,
+          error: {
+            code: 'internal',
+            message: 'checkpoint media job references a node absent from the resume plan',
+            retryable: false,
+          },
+        };
+        this.#abort.abort();
+      }
+      this.#schedule();
+      return;
+    }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const job = this.#pendingMediaJobs.get(nodeId);
	const vertex = this.#plan.vertices.get(nodeId);
	if (this.#settled || job === undefined || vertex === undefined) {
	return; // run terminal, job cleared, or vertex gone
	}
	const job = this.#pendingMediaJobs.get(nodeId);
	const vertex = this.#plan.vertices.get(nodeId);
	if (this.#settled || job === undefined) {
	return; // run terminal or job cleared
	}
	if (vertex === undefined) {
	this.#emitMediaJobCost(nodeId, job);
	this.#clearMediaJob(nodeId);
	if (this.#failure === undefined && !this.#cancelling) {
	this.#failure = {
	nodeId,
	error: {
	code: 'internal',
	message: 'checkpoint media job references a node absent from the resume plan',
	retryable: false,
	},
	};
	this.#abort.abort();
	}
	this.#schedule();
	return;
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/engine/engine.ts` around lines 1407 - 1411, The condition
checking `vertex === undefined` in the media job resume handler currently
returns silently without clearing the job from `#pendingMediaJobs`, leaving the
parked media job in an inconsistent state. Instead of returning when the vertex
is missing, you should treat this as a terminal failure by clearing the job from
`#pendingMediaJobs` before returning, ensuring the job is properly cleaned up
and the run does not get stranded in a paused state. This cleanup is
particularly important in the checkpoint and workflow-drift code paths.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud