Merge master into codex/simp-session-log-representation

packages/bash/tool-bash/tests/integration.spec.ts

@@ -102,7 +102,7 @@ describe('bash tool through the agent loop', () => {
     const handle = await ctx.agents.create({
       agentId: AgentId('session-env'),
       sessionId: SessionId('session-env-id'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const agent = handle.agent as ReactLoopAgent
     const location = ctx.sessionPersistence.locate(agent.session.header)
@@ -125,7 +125,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('The command printed integration-ok.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-fg'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('it-fg'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run echo integration-ok' }])
     await waitForIdle(ctx, agent)
@@ -157,7 +157,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('It failed with code 9.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-exit'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('it-exit'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run exit 9' }])
     await waitForIdle(ctx, agent)
@@ -177,7 +177,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('Background task finished.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-bg'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('it-bg'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
     await waitForIdle(ctx, agent)

packages/compact/compact-basic/README.md

@@ -11,12 +11,12 @@ This backend owns the compaction policy:
 - **Estimation** — a configurable characters-per-token heuristic counts the current session prefix supplied to pre-step, derived history, and system prompt, matching the next request rather than stale logged prefix state.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes; a single unit larger than the budget remains out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
-- **Summarization** — a direct `llm/stream` call uses the configured model and cap without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
+- **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
 - **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
 - **Lifecycle** — `compactRegion()` records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
 - **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. Recoverable failure records an error end and leaves the surface unchanged.
 
-`estimateContentTokens()` and `summarize()` are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the retention walk and surface plumbing. `summarize()` returns the summary blocks together with the call envelope it actually used (`{ summary, model, maxTokens? }`) — the caller logs that envelope on the `compact/summary` provenance event, so an overriding backend reports its own envelope honestly.
+`estimateContentTokens()` and `summarize()` are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the retention walk and surface plumbing. `summarize()` returns the summary blocks together with the call envelope it actually used (`{ summary, provider, model, maxTokens? }`) — the caller logs that envelope on the `compact/summary` provenance event, so an overriding backend reports its own envelope honestly.
 
 ## Config (`BasicCompactConfig`)
 
@@ -27,7 +27,8 @@ Every knob is **required** except `auto` — there is no concrete data yet to ju
 | `contextWindow` | yes | Context window size in tokens. |
 | `thresholdRatio` | yes | Compact when estimated usage exceeds this fraction of the window. |
 | `retainTokens` | yes | Tokens of recent context to keep intact. |
-| `summarizationModel` | yes | Model for summarization (`''` → use the agent's model). |
+| `summarizationProvider` | yes | Provider for summarization (`''` together with an empty model → use the latest logged request pair, then the agent pair). |
+| `summarizationModel` | yes | Model for summarization (`''` together with an empty provider → use the latest logged request pair, then the agent pair). |
 | `maxTokens` | yes | Provider generation cap for the summarization call; may include reasoning tokens. |
 | `compactionRetries` | yes | Extra compaction attempts after the first if the compacted surface remains over threshold. |
 | `auto` | no (default `true`) | Register the `agent/pre-step` auto-compaction listener. Set `false` for manual-only. |
@@ -47,6 +48,7 @@ export function apply(ctx: Context): void {
     contextWindow: 128000,
     thresholdRatio: 0.8,
     retainTokens: 20480,
+    summarizationProvider: '',
     summarizationModel: '',
     maxTokens: 8192,
     compactionRetries: 1,

packages/compact/compact-basic/src/index.ts

@@ -227,21 +227,26 @@ export class BasicCompactService extends CompactService {
   /**
    * Summarize through a direct one-shot `ctx.llm.stream()` call, not an agent
    * step or `agent/request` dispatch. Failure finishes and truncated summaries
-   * reject; the signal is forwarded and only text reaches the checkpoint.
+   * reject; the signal is forwarded, only text reaches the checkpoint, and the
+   * returned envelope identifies the provider/model actually used.
    *
    * @param text - plain-text rendering of the conversation region to condense.
-   * @param agent - supplies the fallback model and the session id stamped on
-   *   the call; throws when neither it nor the config names a model.
+   * @param agent - supplies the request-header/creation fallback target and the
+   *   session id stamped on the call; throws when no complete target exists.
    * @param signal - optional abort signal, forwarded into the model call.
    * @returns the text-only summary blocks plus the call envelope used
-   *   (`model`, and `maxTokens` when the summarizer has a cap).
+   *   (`provider`, `model`, and `maxTokens` when the summarizer has a cap).
    */
   async summarize(
     text: string, agent: Agent, signal?: AbortSignal,
-  ): Promise<{ summary: ContentBlock[]; model: string; maxTokens?: number }> {
+  ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> {
     const assembler = new BlockAssembler()
+    const logged = agent.session.requestHeader()?.config
+    const provider = this.config.summarizationProvider || logged?.provider || agent.options.provider || ''
+    const model = this.config.summarizationModel || logged?.model || agent.options.model || ''
     const options: GenerateOptions = {
-      model: this.config.summarizationModel || agent.options.model || '',
+      provider,
+      model,
       messages: [{
         role: 'user',
         content: [{ type: 'text', text: `Summarize this conversation history:\n\n${text}\n\nSummary:` }],
@@ -253,8 +258,8 @@ export class BasicCompactService extends CompactService {
     // exactOptionalPropertyTypes: only set `signal` when present — assigning
     // `undefined` to an optional `signal?: AbortSignal` is a type error.
     if (signal) options.signal = signal
-    if (!options.model) {
-      throw new Error('no model available for summarization: set BasicCompactConfig.summarizationModel or AgentOptions.model')
+    if (!options.provider || !options.model) {
+      throw new Error('no provider/model available for summarization: set both summarization fields or provide a logged/agent target')
     }
     for await (const chunk of this.ctx.llm.stream(options)) {
       assembler.push(chunk)
@@ -271,7 +276,7 @@ export class BasicCompactService extends CompactService {
     // config.maxTokens is required and validated positive, so this backend's
     // envelope always carries the cap; the return type's optionality exists
     // for overriding subclasses whose summarizer has none.
-    return { summary, model: options.model, maxTokens: this.config.maxTokens }
+    return { summary, provider: options.provider, model: options.model, maxTokens: this.config.maxTokens }
   }
 
   // ---- Core API (implements the abstract contract) ----
@@ -378,7 +383,7 @@ export class BasicCompactService extends CompactService {
     try {
       // --- Extract text and summarize ---
       const text = renderTranscript(session.events, shadowedSeqs)
-      const { summary, model, maxTokens } = await this.summarize(text, agent, signal)
+      const { summary, provider, model, maxTokens } = await this.summarize(text, agent, signal)
 
       // Estimate token count of the shadowed content for provenance.
       let shadowedTokenCount = 0
@@ -400,6 +405,7 @@ export class BasicCompactService extends CompactService {
         shadowedRange: { start, end },
         shadowedSeqs,
         shadowedTokenCount,
+        provider,
         model,
         ...maxTokens !== undefined ? { maxTokens } : {},
       })

packages/compact/compact-basic/src/types.ts

@@ -24,7 +24,9 @@ export interface BasicCompactConfig {
   thresholdRatio: number
   /** Number of tokens of recent context to retain during compaction. */
   retainTokens: number
-  /** Model to use for summarization (`''` — uses the agent's model). */
+  /** Provider to use for summarization (`''` with an empty model inherits the conversation target). */
+  summarizationProvider: string
+  /** Model to use for summarization (`''` with an empty provider inherits the conversation target). */
   summarizationModel: string
   /** Provider generation cap for the summarization call. */
   maxTokens: number
@@ -63,6 +65,12 @@ export function resolveConfig(config: BasicCompactConfig): ResolvedConfig {
   if (typeof resolved.summarizationModel !== 'string') {
     throw new Error('BasicCompactConfig: summarizationModel must be a string.')
   }
+  if (typeof resolved.summarizationProvider !== 'string') {
+    throw new Error('BasicCompactConfig: summarizationProvider must be a string.')
+  }
+  if ((resolved.summarizationProvider.length === 0) !== (resolved.summarizationModel.length === 0)) {
+    throw new Error('BasicCompactConfig: summarizationProvider and summarizationModel must both be empty or both be set.')
+  }
   if (typeof resolved.auto !== 'boolean') {
     throw new Error('BasicCompactConfig: auto must be a boolean.')
   }

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -21,6 +21,7 @@ const TEST_CONFIG: BasicCompactConfig = {
   contextWindow: 128000,
   thresholdRatio: 0.8,
   retainTokens: 20480,
+  summarizationProvider: '',
   summarizationModel: '',
   maxTokens: 8192,
   compactionRetries: 1,
@@ -58,13 +59,17 @@ class TestCompactService extends BasicCompactService {
     return blocks.length * 10
   }
 
-  override async summarize(text: string, agent: Agent): Promise<{ summary: ContentBlock[]; model: string; maxTokens?: number }> {
+  override async summarize(
+    text: string,
+    agent: Agent,
+  ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> {
+    const provider = this.config.summarizationProvider || agent.options.provider || ''
     const model = this.config.summarizationModel || agent.options.model || ''
     this.summarizeCalls.push({ text, model })
     if (this.summarizeError) throw this.summarizeError
     const summary = this.mockSummaryQueue.shift() ?? this.mockSummary
     this.summaryOutputs.add(summary)
-    return { summary, model }
+    return { summary, provider, model }
   }
 }
 
@@ -94,7 +99,7 @@ function multiTurnSession(turns: number, messagesPerTurn: number = 2, opts: { le
         content: [{ type: 'text', text: `turn ${t} user message ${m + 1}.${LONG_FIXTURE_TEXT}` }],
         source: { kind: 'user' },
       }, { surfaceOp: 'append' })
-      s.append('assistant/message', {
+      s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
         turn: t, step: 1,
         content: [{ type: 'text', text: `turn ${t} assistant response ${m + 1}.${LONG_FIXTURE_TEXT}` }],
       }, { surfaceOp: 'append' })
@@ -119,7 +124,7 @@ function sessionWithTools(): Session {
     content: [{ type: 'text', text: 'read file x' }],
     source: { kind: 'user' },
   }, { surfaceOp: 'append' })
-  s.append('assistant/message', {
+  s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
     turn: 1, step: 1,
     content: [
       { type: 'text', text: 'Let me read that file.' },
@@ -132,7 +137,7 @@ function sessionWithTools(): Session {
     content: [{ type: 'text', text: 'hello world' }],
     isError: false,
   }, { surfaceOp: 'append' })
-  s.append('assistant/message', {
+  s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
     turn: 1, step: 1,
     content: [{ type: 'text', text: 'The file contains: hello world' }],
   }, { surfaceOp: 'append' })
@@ -161,7 +166,7 @@ function toolTurnSession(turns: number): Session {
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
     s.append('step/start', { turn: t, step: 1 })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: t, step: 1,
       content: [
         { type: 'text', text: `turn ${t} calling tool` },
@@ -224,7 +229,7 @@ describe('BasicCompactService step-alignment (never split a tool-call/result pai
     const s = new Session(SessionId('one-step'))
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [{ type: 'text', text: 'calling' }, { type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
     }, { surfaceOp: 'append' })
@@ -270,7 +275,7 @@ describe('BasicCompactService step-alignment (never split a tool-call/result pai
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('user/message', { content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('step/start', { turn: 1, step: 1 })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
     }, { surfaceOp: 'append' })
@@ -332,7 +337,7 @@ describe('BasicCompactService.estimateEventTokens', () => {
     const userEvent: SessionEvent = { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } } }
     expect(svc.estimateEventTokens(userEvent)).toBe(10)
 
-    const asstEvent: SessionEvent = { type: 'assistant/message', seq: 1, time: 2, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }] } }
+    const asstEvent: SessionEvent = { type: 'assistant/message', seq: 1, time: 2, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }], provenance: { provider: 'mock', model: 'mock' } } }
     expect(svc.estimateEventTokens(asstEvent)).toBe(20)
 
     const toolEvent: SessionEvent = { type: 'tool/result', seq: 2, time: 3, data: { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'output' }], isError: false } }
@@ -606,7 +611,7 @@ describe('BasicCompactService.compactIfNeeded', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'do a big multi-step task' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     for (let step = 1; step <= 5; step++) {
       s.append('step/start', { turn: 1, step })
-      s.append('assistant/message', {
+      s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
         turn: 1, step,
         content: [{ type: 'text', text: `step ${step}` }, { type: 'tool-call', id: CallId(`c${step}`), name: 'bash', arguments: '{}' }],
       }, { surfaceOp: 'append' })
@@ -654,7 +659,7 @@ describe('BasicCompactService.compactIfNeeded', () => {
     // the fresh nodes are retained.
     s.append('step/start', { turn: 5, step: 1 })
     s.append('user/message', { content: [{ type: 'text', text: 'turn 5 work' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 5, step: 1, content: [{ type: 'text', text: 'reply 5' }] }, { surfaceOp: 'append' })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 5, step: 1, content: [{ type: 'text', text: 'reply 5' }] }, { surfaceOp: 'append' })
     s.append('step/end', { turn: 5, step: 1 })
 
     const second = await compactIfNeeded(svc, s, '', 'm', SIGNAL)
@@ -751,7 +756,7 @@ describe('BasicCompactService blocking (compaction in progress)', () => {
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
     s.append('user/message', { content: [{ type: 'text', text: 'turn 1' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply 1' }] }, { surfaceOp: 'append' })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'reply 1' }] }, { surfaceOp: 'append' })
     s.append('compact/start', { turn: 1 }) // ← orphaned: no matching compact/end
     s.append('step/end', { turn: 1, step: 1 })
     s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) // repair closed the turn
@@ -954,7 +959,7 @@ async function ctxWithFinish(reason: (StreamChunk & { type: 'finish' })['reason'
 
 /** A minimal Agent stub carrying just session + options (enough for the listeners). */
 function stubAgent(session: Session, model?: string): Agent {
-  return { session, options: { model } } as unknown as Agent
+  return { session, options: { provider: model, model } } as unknown as Agent
 }
 
 function compactIfNeeded(
@@ -1039,7 +1044,7 @@ describe('BasicCompactService.summarize (real ctx.llm.stream)', () => {
   it('throws when no model is provided', async () => {
     const { ctx } = await ctxWithModel('x')
     const svc = new BasicCompactService(ctx, cfg({ auto: false }))
-    await expect(summarize(svc, 'text', '')).rejects.toThrow(/no model available/)
+    await expect(summarize(svc, 'text', '')).rejects.toThrow(/no provider\/model available/)
   })
 
   it('rethrows when the stream ends with a finish-error chunk', async () => {
@@ -1116,7 +1121,7 @@ describe('BasicCompactService.summarize (real ctx.llm.stream)', () => {
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('step/start', { turn: 1, step: 1 })
     session.append('user/message', { content: [{ type: 'text', text: 'tiny user' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'tiny assistant' }] }, { surfaceOp: 'append' })
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'tiny assistant' }] }, { surfaceOp: 'append' })
     session.append('step/end', { turn: 1, step: 1 })
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -1225,6 +1230,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () =>
     // One-shot summaries bypass agent/request but remain mutable at llm/stream;
     // adapter selection happens after the waterfall rewrite.
     ctx.on('llm/stream', (options, next) => {
+      options.provider = 'routed-model'
       options.model = 'routed-model'
       return next()
     })
@@ -1267,7 +1273,7 @@ describe('BasicCompactService transcript rendering (delegated to dsh-compact)',
       content: [{ type: 'text', text: 'project context here' }],
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [{ type: 'reasoning', text: 'thinking hard' }, { type: 'text', text: 'answer' }],
     }, { surfaceOp: 'append' })
@@ -1295,7 +1301,7 @@ describe('BasicCompactService transcript rendering (delegated to dsh-compact)',
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
     s.append('user/message', { content: [{ type: 'text', text: 'run it' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [{ type: 'tool-call', id: CallId('c9'), name: 'bash', arguments: '{}' }],
     }, { surfaceOp: 'append' })
@@ -1324,7 +1330,7 @@ describe('BasicCompactService edge cases', () => {
     // assistant/message carrying a nested tool-result block, an unknown block,
     // and the tool-call that the following tool/result answers (so the surface
     // is tool-pairing balanced).
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [
         { type: 'tool-result', toolCallId: CallId('n1'), content: [{ type: 'chart', data: 'x' } as unknown as ContentBlock] },
@@ -1387,7 +1393,7 @@ describe('BasicCompactService edge cases', () => {
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
     s.append('user/message', { content: [{ type: 'text', text: 'orphan' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
     s.append('step/end', { turn: 1, step: 1 })
     s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     const nodes = s.surface.nodes
@@ -1479,13 +1485,13 @@ describe('BasicCompactService edge cases', () => {
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
     s.append('user/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'reasoning', text: '' }] }, { surfaceOp: 'append' })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'reasoning', text: '' }] }, { surfaceOp: 'append' })
     s.append('context/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('steering/message', { turn: 1, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('step/end', { turn: 1, step: 1 })
     // Keep the log pairing-valid while the empty result covers the final message kind.
     s.append('step/start', { turn: 1, step: 2 })
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 2,
       content: [{ type: 'tool-call', id: CallId('z1'), name: 'bash', arguments: '{}' }],
     }, { surfaceOp: 'append' })
@@ -1516,7 +1522,7 @@ describe('BasicCompactService edge cases', () => {
     s.append('user/message', { content: [chart('y')], source: { kind: 'user' } }, { surfaceOp: 'append' })
     // assistant/message with a plugin-added block AND the tool-call its
     // tool/result answers (so the surface is tool-pairing balanced).
-    s.append('assistant/message', {
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [
         chart('z'),
@@ -1641,7 +1647,7 @@ describe('BasicCompactService under the real invariants plugin', () => {
     session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('step/start', { turn, step: 1 })
     session.append('user/message', { content: [{ type: 'text', text: `turn ${turn} user.${LONG_FIXTURE_TEXT}` }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('assistant/message', { turn, step: 1, content: [{ type: 'text', text: `turn ${turn} assistant.${LONG_FIXTURE_TEXT}` }] }, { surfaceOp: 'append' })
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn, step: 1, content: [{ type: 'text', text: `turn ${turn} assistant.${LONG_FIXTURE_TEXT}` }] }, { surfaceOp: 'append' })
     session.append('step/end', { turn, step: 1 })
     session.append('turn/end', { turn, reason: { kind: 'completed' } })
   }

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -25,8 +25,8 @@ class ReproCompactService extends BasicCompactService {
     return blocks.length * TOKENS_PER_BLOCK
   }
 
-  override async summarize(): Promise<{ summary: ContentBlock[]; model: string }> {
-    return { summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], model: 'stub' }
+  override async summarize(): Promise<{ summary: ContentBlock[]; provider: string; model: string }> {
+    return { summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], provider: 'mock', model: 'stub' }
   }
 }
 
@@ -77,6 +77,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
     contextWindow: 64,
     thresholdRatio: 0.5,
     retainTokens: 20,
+    summarizationProvider: '',
     summarizationModel: '',
     maxTokens: 8192,
     compactionRetries: 1,
@@ -99,7 +100,7 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
   it('the head checkpoint the loop lands is a balanced cut on both sides', async () => {
     const { ctx } = await harness(8)
     try {
-      const agent = ctx.agentLoop.create(AgentId('repro'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('repro'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'do a long multi-step task' }])
       await waitForIdle(ctx, agent)
 

packages/compact/compact/README.md

@@ -35,7 +35,7 @@ The private per-session cache is keyed by `session.surface.replaceGeneration` an
 
 1. appends `compact/start` (log-only) — acquires the lock,
 2. summarizes the range,
-3. appends `compact/summary` (log-only) — provenance: summary, range, shadowed seqs, token count,
+3. appends `compact/summary` (log-only) — provenance: summary, range, shadowed seqs, token count, and provider/model call envelope,
 4. appends a single `user/message` with `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation**,
 5. appends `compact/end` (log-only) — releases the lock.
 

packages/compact/compact/src/types.ts

@@ -24,6 +24,8 @@ declare module '@deepseek-ai/dsh-session' {
       shadowedRange: { start: number; end: number }
       shadowedSeqs: number[]
       shadowedTokenCount: number
+      /** The provider route that wrote the summary. */
+      provider: string
       /**
        * The model that wrote the summary — the summarize call's envelope,
        * reported by the backend that made the call, logged so the one-shot

packages/compact/compact/tests/compact.spec.ts

@@ -41,6 +41,7 @@ class StubCompactService extends CompactService {
       shadowedRange: { start, end },
       shadowedSeqs: [],
       shadowedTokenCount: 0,
+      provider: 'mock',
       model: 'stub',
     })
     const endEvent = session.append('compact/end', { turn: 0 })

packages/compact/compact/tests/render.spec.ts

@@ -54,7 +54,7 @@ describe('renderTranscript', () => {
       content: [{ type: 'text', text: 'fix the bug' }],
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
-    const assistant = s.append('assistant/message', {
+    const assistant = s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 0, step: 0,
       content: [{ type: 'text', text: 'looking' }],
     }, { surfaceOp: 'append' })
@@ -111,7 +111,7 @@ describe('renderTranscript', () => {
       content: [{ type: 'text', text: '' }],
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
-    const emptyAssistant = s.append('assistant/message', {
+    const emptyAssistant = s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 0, step: 0,
       content: [{ type: 'text', text: '' }],
     }, { surfaceOp: 'append' })

packages/compact/compact/tests/tool-pairing.spec.ts

@@ -34,6 +34,7 @@ function closedToolStep(): Session {
     turn: 1,
     step: 1,
     content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
+    provenance: { provider: 'mock', model: 'mock' },
   }, SURFACE)
   session.append('tool/result', {
     turn: 1,
@@ -60,6 +61,7 @@ describe('tool-pairing boundaries', () => {
       turn: 1,
       step: 1,
       content: [{ type: 'tool-call', id: CallId('open'), name: 'bash', arguments: '{}' }],
+      provenance: { provider: 'mock', model: 'mock' },
     }, SURFACE)
     expect(toolPairingBalancedAfter(open, open.surface.nodes[0]!)).toBe(false)
   })
@@ -73,6 +75,7 @@ describe('tool-pairing boundaries', () => {
         { type: 'tool-call', id: CallId('c1'), name: 'one', arguments: '{}' },
         { type: 'tool-call', id: CallId('c2'), name: 'two', arguments: '{}' },
       ],
+      provenance: { provider: 'mock', model: 'mock' },
     }, SURFACE)
     session.append('tool/result', {
       turn: 1, step: 1, callId: CallId('c1'), content: [], isError: false,
@@ -91,6 +94,7 @@ describe('tool-pairing boundaries', () => {
       turn: 1,
       step: 1,
       content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }],
+      provenance: { provider: 'mock', model: 'mock' },
     }, SURFACE)
     midStep.append('context/message', {
       content: [{ type: 'text', text: 'background update' }],
@@ -165,7 +169,12 @@ describe('tool-pairing cache refresh', () => {
       },
       {
         type: 'assistant/message', seq: 1, time: 1,
-        data: { turn: 1, step: 1, content: [{ type: 'tool-call', id: CallId('c1'), name: 'one', arguments: '{}' }] },
+        data: {
+          turn: 1,
+          step: 1,
+          content: [{ type: 'tool-call', id: CallId('c1'), name: 'one', arguments: '{}' }],
+          provenance: { provider: 'mock', model: 'mock' },
+        },
         surfaceOp: 'append',
       },
       {
@@ -226,7 +235,12 @@ describe('tool-pairing cache refresh', () => {
     events.push(
       {
         type: 'assistant/message', seq: 5, time: 5,
-        data: { turn: 2, step: 1, content: [{ type: 'tool-call', id: CallId('c2'), name: 'two', arguments: '{}' }] },
+        data: {
+          turn: 2,
+          step: 1,
+          content: [{ type: 'tool-call', id: CallId('c2'), name: 'two', arguments: '{}' }],
+          provenance: { provider: 'mock', model: 'mock' },
+        },
         surfaceOp: 'append',
       },
       {

packages/context/time-context/tests/fixtures/cordis.yml

@@ -11,6 +11,7 @@
 - id: stdio-agent
   name: '@deepseek-ai/dsh-stdio-demo'
   config:
+    provider: mock
     model: mock-echo
     persona: 'Test the time-context plugin.'
     welcome: 'time-context e2e ready.'

packages/context/time-context/tests/time-context.spec.ts

@@ -370,7 +370,7 @@ describe('real agent-loop request history', () => {
       if (mode === 'throws') throw new Error('later pre-step failure')
       subject.cancel('later pre-step cancellation')
     })
-    const agent = ctx.agentLoop.create(AgentId(`late-${mode}`), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
@@ -396,7 +396,7 @@ describe('real agent-loop request history', () => {
         return [{ type: 'text' as const, text: 'advanced' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('loop'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('loop'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()

packages/context/workspace-context/tests/workspace-context.e2e.ts

@@ -44,12 +44,12 @@ async function harness(): Promise<{ ctx: Context; agent: Agent }> {
   await ctx.plugin(ToolFs)
   await ctx.plugin(WorkspaceContext, { maxBytes: 65536 })
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await ctx.plugin(LlmDeepSeek, { models: [{ id: 'deepseek-v4-flash' }] })
   const handle = await ctx.agents.create({
     agentId: AgentId('workspace-context-e2e'),
     sessionId: SessionId('workspace-context-e2e-session'),
     meta: { cwd: workdir },
-    agentOptions: { model: 'deepseek-v4-flash' },
+    agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
   })
   return { ctx, agent: handle.agent }
 }

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -1591,7 +1591,7 @@ describe('dynamic nested workspace context injection', () => {
       await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
       await ctx.plugin(AgentLoop, { agents: [] })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(AgentId('workspace-context-abort'), { model: 'mock' }, { cwd: root })
+      const agent = ctx.agentLoop.create(AgentId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
       ctx.tools.register(defineTool({
         name: 'abort_step',
         description: 'Abort the current test step.',

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -133,8 +133,9 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'llm',
     summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
     methods: [
-      'registerAdapter(models: string[], adapter: LlmAdapter): () => void',
-      'models(): string[]',
+      'registerAdapter(providers: string[], adapter: LlmAdapter): () => void',
+      'listProviders(): LlmProviderInfo[]',
+      'async listModels(provider: string): Promise<LlmModelInfo[]>',
       'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
     ],
   },
@@ -539,7 +540,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'AgentOptions',
-    declaration: 'export interface AgentOptions {\n    model?: string;\n}',
+    declaration: 'export interface AgentOptions {\n    provider?: string;\n    model?: string;\n}',
   },
   {
     name: 'AgentStatus',
@@ -585,6 +586,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AssembledSection',
     declaration: 'export interface AssembledSection {\n    name: string;\n    text: string;\n}',
   },
+  {
+    name: 'AssistantProvenance',
+    declaration: 'export interface AssistantProvenance {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}',
+  },
   {
     name: 'BashEnvContributor',
     declaration: 'export interface BashEnvContributor {\n    name: string;\n    variables: Readonly<Record<DshEnvironmentKey, BashEnvVariable>>;\n    resolve(execution: ToolExecution): Readonly<Partial<Record<DshEnvironmentKey, string>>>;\n}',
@@ -767,7 +772,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'GenerateOptions',
-    declaration: 'export interface GenerateOptions {\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n}',
+    declaration: 'export interface GenerateOptions {\n    provider: string;\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n}',
   },
   {
     name: 'GenericCallView',
@@ -789,9 +794,17 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'JsonValue',
     declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
   },
+  {
+    name: 'LlmModelInfo',
+    declaration: 'export interface LlmModelInfo {\n    provider: string;\n    id: string;\n    name: string;\n    description?: string;\n}',
+  },
+  {
+    name: 'LlmProviderInfo',
+    declaration: 'export interface LlmProviderInfo {\n    id: string;\n    name: string;\n}',
+  },
   {
     name: 'Message',
-    declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n}',
+    declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n    provenance?: AssistantProvenance;\n}',
   },
   {
     name: 'MessageSource',
@@ -855,7 +868,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventMap',
-    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'todo/write\': {\n        todos /* …truncated — full shape in source */',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource; /* …truncated — full shape in source */',
   },
   {
     name: 'SessionEventReadRequest',
@@ -963,7 +976,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'StreamChunk',
-    declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n};',
+    declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n    replayState?: unknown;\n};',
   },
   {
     name: 'StructuredOutputSchema',
@@ -1199,7 +1212,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'WorkflowPhase',
-    declaration: 'export interface WorkflowPhase {\n    title: string;\n    detail?: string;\n    model?: string;\n}',
+    declaration: 'export interface WorkflowPhase {\n    title: string;\n    detail?: string;\n    provider?: string;\n    model?: string;\n}',
   },
   {
     name: 'WorkflowResult',

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -44,7 +44,7 @@ describe('cordis tools through the agent loop', () => {
       textResponse('Done.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-cordis'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('it-cordis'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
     await waitForIdle(ctx, agent)

packages/core/agent-loop/README.md

@@ -31,6 +31,7 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo
 interface Config {
   agents: Array<{
     id: string                 // required
+    provider?: string
     model?: string
     resumeSessionId?: string   // load this persisted session instead of creating one
     cwd?: string               // optional workspace cwd for the fresh session
@@ -38,7 +39,7 @@ interface Config {
 }
 ```
 
-Configured agents start automatically. `cwd` applies only to fresh sessions; `resumeSessionId` retains persisted metadata. They use the deployment persona. Programmatic setup can shadow it per agent. This plugin supplies the per-agent `model` and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`.
+Configured agents start automatically. A model call requires both `provider` and `model`; `agent/request` may supply a missing pair before dispatch. `cwd` applies only to fresh sessions, while `resumeSessionId` retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent `provider`, `model`, and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`.
 
 ### Exported concrete class
 

packages/core/agent-loop/src/index.ts

@@ -339,6 +339,7 @@ export class AgentLoop extends Service implements AgentFactory {
   static Config = z.object({
     agents: z.array(z.object({
       id: z.string().required(),
+      provider: z.string(),
       model: z.string(),
       cwd: z.string(),
       resumeSessionId: z.string(),
@@ -355,6 +356,7 @@ export class AgentLoop extends Service implements AgentFactory {
     this.runtime = { ctx }
     ctx.effect(() => () => this.ownership.dispose(), 'agentLoop.transactions()')
     ctx.effect(() => ctx.agents.setFactory(this), 'agentLoop.setFactory()')
+    ctx.systemPrompt.variable('provider', context => context.agent?.options.provider)
     ctx.systemPrompt.variable('model', context => context.agent?.options.model)
     ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd)
 

packages/core/agent-loop/src/loop.ts

@@ -6,7 +6,8 @@
  */
 
 import type { Context } from 'cordis'
-import type { FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm'
+import { isDeepStrictEqual } from 'node:util'
 import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm'
 import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
@@ -482,12 +483,12 @@ async function runStep(
   const seedConfig: LlmCallConfig = deepFreeze(structuredClone(transmission.loggedHeader
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- loggedHeader ⟹ a snapshot is in the log
     ? session.requestHeader()!.config
-    : { model: options.model ?? '' }))
+    : { provider: options.provider ?? '', model: options.model ?? '' }))
 
   // Listener replacements are recorded in the request header before dispatch.
   const config = await events.waterfall('agent/request', turn, step, seedConfig, () => Promise.resolve(seedConfig))
-  if (!config.model) {
-    throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`)
+  if (!config.provider || !config.model) {
+    throw new Error(`agent "${agent.id}" has no provider/model: set AgentOptions.provider and AgentOptions.model or supply both via the agent/request waterfall`)
   }
 
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- runTurn composes the prefix before every runStep call
@@ -504,6 +505,7 @@ async function runStep(
 
   // Freeze the logged header plus boundary snapshot; the prefix precedes derived history.
   const request: GenerateOptions = deepFreeze({
+    provider: header.config.provider,
     model: header.config.model,
     messages: [...header.messagePrefix ?? [], ...boundaryMessages],
     ...header.system !== undefined ? { system: header.system } : {},
@@ -531,32 +533,23 @@ async function runStep(
   if (stepError) throw stepError
 
   if (assembler.finish.kind === 'max-tokens') {
-    let message: Message = withoutToolCalls(assembler.message())
+    const assembled = assembler.message()
+    const assembledContent = structuredClone(assembled.content)
+    let message: Message = withoutToolCalls(assembled)
     message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)))
     // Preserve usage even when max-token truncation produced no content.
-    if (message.content.length > 0 || assembler.usage) {
-      // The finish chunk guarantees non-empty provenance here.
-      session.append(
-        'assistant/message',
-        { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-        { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
-      )
-    }
+    recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
     return { hadToolCalls: false, finish: assembler.finish }
   }
 
   // Record the post-waterfall message that tool dispatch uses.
-  let message: Message = assembler.message()
+  const assembled = assembler.message()
+  const assembledContent = structuredClone(assembled.content)
+  let message: Message = assembled
   message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))
 
-  // Empty messages exist only to carry usage; omit empty provenance.
-  if (message.content.length > 0 || assembler.usage) {
-    session.append(
-      'assistant/message',
-      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-      { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) },
-    )
-  }
+  // Empty messages exist only to carry usage; the helper also omits empty chunk provenance.
+  recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
 
   // Tool execution stays sequential; recheck abort around each normalized result.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')
@@ -612,6 +605,44 @@ async function runStep(
   return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish }
 }
 
+/** Record one content-or-usage assistant message with replay-safe provenance. */
+function recordAssistantMessage(
+  session: Session,
+  turn: number,
+  step: number,
+  config: LlmCallConfig,
+  assembledContent: ContentBlock[],
+  message: Message,
+  assembler: BlockAssembler,
+  chunkSeqs: number[],
+): void {
+  if (message.content.length === 0 && assembler.usage === undefined) return
+  session.append(
+    'assistant/message',
+    {
+      turn,
+      step,
+      content: message.content,
+      provenance: assistantProvenance(
+        config,
+        assembler.replayState,
+        isDeepStrictEqual(message.content, assembledContent),
+      ),
+      ...assembler.usage === undefined ? {} : { usage: assembler.usage },
+    },
+    { surfaceOp: 'append', ...chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {} },
+  )
+}
+
+/** Build durable assistant provenance, dropping replay state after any content rewrite. */
+function assistantProvenance(config: LlmCallConfig, replayState: unknown, contentUnchanged: boolean): NonNullable<Message['provenance']> {
+  return {
+    provider: config.provider,
+    model: config.model,
+    ...contentUnchanged && replayState !== undefined ? { replayState } : {},
+  }
+}
+
 function withoutToolCalls(message: Message): Message {
   return { ...message, content: message.content.filter(block => block.type !== 'tool-call') }
 }

packages/core/agent-loop/tests/agent.spec.ts

@@ -53,10 +53,10 @@ describe('ReactLoopAgent', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('exclusive-driver'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('first-driver'), { model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(ctx, AgentId('first-driver'), { provider: 'mock', model: 'mock' }, session)
 
     expect(() => prepared.agent.ctx).toThrow('context is not bound')
-    expect(() => prepareReactLoopAgent(ctx, AgentId('second-driver'), { model: 'mock' }, session))
+    expect(() => prepareReactLoopAgent(ctx, AgentId('second-driver'), { provider: 'mock', model: 'mock' }, session))
       .toThrow('already has a concrete agent driver')
 
     await prepared.dispose()
@@ -65,7 +65,7 @@ describe('ReactLoopAgent', () => {
 
   it('borrows caller options and binds its scoped context exactly once', async () => {
     const ctx = await harness(new MockAdapter([textResponse('unused')]))
-    const options = { model: 'mock' }
+    const options = { provider: 'mock', model: 'mock' }
     const agent = ctx.agentLoop.create(AgentId('owned-bindings'), options)
 
     expect(agent.options).toBe(options)
@@ -81,7 +81,7 @@ describe('ReactLoopAgent', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -96,7 +96,7 @@ describe('ReactLoopAgent', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -111,7 +111,7 @@ describe('ReactLoopAgent', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -124,7 +124,7 @@ describe('ReactLoopAgent', () => {
   it('inject() decides enclosure from the LOG (open turn), not agent status', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Simulate an OPEN turn in the log while the agent is idle (status is not a
     // reliable open-turn signal). inject must append into that open turn, NOT
@@ -150,7 +150,7 @@ describe('ReactLoopAgent', () => {
     // A persistence-like listener whose flush rejects.
     ctx.on('session/flush', () => { throw new Error('disk gone') })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // inject() is synchronous and fires a fire-and-forget flush; a rejecting
     // flush must be contained (logged), never thrown into the caller.
@@ -163,7 +163,7 @@ describe('ReactLoopAgent', () => {
   it('idle inject() closes its one-shot turn AND still checkpoints even if the append throws', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
 
@@ -181,7 +181,7 @@ describe('ReactLoopAgent', () => {
   it('idle inject() still checkpoints when a listener throws on the synthetic turn/end', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
     // Session contains a throwing post-commit turn/end observer. The accepted
@@ -204,7 +204,7 @@ describe('ReactLoopAgent', () => {
     // A non-Error rejection exercises the String() normalization branch.
     ctx.on('session/flush', () => { throw 'disk gone' })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     const errors: { turn: number; step: number; message: string }[] = []
     ctx.on('agent/error', (_a, turn, step, error) => void errors.push({ turn, step, message: error.message }))
 
@@ -223,7 +223,7 @@ describe('ReactLoopAgent', () => {
   it('idle inject() with a non-serializable source opens no turn (nothing to close)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // A non-serializable source makes the turn/start append throw BEFORE the
     // event is pushed (Session.append validates before push), so NO turn opens.
@@ -238,7 +238,7 @@ describe('ReactLoopAgent', () => {
   it('steer() when idle falls through to send() and starts a turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // steer while idle delegates to send
     agent.steer([{ type: 'text', text: 'steer idle' }], { source: { kind: 'plugin', plugin: 'test' } })
@@ -254,7 +254,7 @@ describe('ReactLoopAgent', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('test'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session)
     const { agent } = prepared
 
     prepared.markPublished()
@@ -272,7 +272,7 @@ describe('ReactLoopAgent', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('pre-start-dispose'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('pre-start-dispose'), { model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(ctx, AgentId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session)
 
     await prepared.dispose()
     expect(prepared.agent.status).toBe('disposed')
@@ -286,7 +286,7 @@ describe('ReactLoopAgent', () => {
   it('setting the same status does not emit agent/status again', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const statuses: string[] = []
     ctx.on('agent/status', (subject, status) => {
@@ -305,7 +305,7 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() resolves immediately when the agent is not running', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Fresh agent is idle — whenIdle() takes the not-running fast path and
     // resolves without subscribing. await must not hang.
@@ -316,7 +316,7 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() waits for queued work that has not flipped status yet', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'queued')
     let settled = false
@@ -334,8 +334,8 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() awaits the running→idle transition, ignoring other subjects/running events', async () => {
     const adapter = new MockAdapter([textResponse('ok'), textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
-    const other = ctx.agentLoop.create(AgentId('a2'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const other = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
 
     // Drive `agent` into `running`, then await whenIdle() — it subscribes to
     // agent/status and resolves on the first transition out of running.
@@ -369,7 +369,7 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter(['hang'])
     ctx.llm.registerAdapter(['mock'], adapter)
     const session = ctx.sessions.create(SessionId('bare'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session)
     const { agent } = prepared
     prepared.markPublished()
     const dispose = prepared.startDriver()
@@ -391,7 +391,7 @@ describe('ReactLoopAgent', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -410,7 +410,7 @@ describe('ReactLoopAgent', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -431,7 +431,7 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/status', (_subject, status) => {
       if (status === 'running') throw new Error('bad running listener')
     })
@@ -449,7 +449,7 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/status', (_subject, status) => {
       if (status === 'idle') throw new Error('bad idle listener')
     })

packages/core/agent-loop/tests/cancel.spec.ts

@@ -54,7 +54,7 @@ describe('Agent.cancel()', () => {
   it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // The loop is parked at the idle wait with nothing queued. A cancel here must
     // NOT arm the marker — otherwise the next legitimate prompt would be dropped.
@@ -71,7 +71,7 @@ describe('Agent.cancel()', () => {
   it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // send() queues synchronously (status still idle, loop microtask not yet
     // resumed). Cancel in that pre-step window: the queued turn must not run.
@@ -90,7 +90,7 @@ describe('Agent.cancel()', () => {
   it('a whenIdle() waiter registered BEFORE a pre-step cancel resolves (F1 hang guard)', async () => {
     const adapter = new MockAdapter([textResponse('x')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // This waiter cannot rely on a running→idle transition because cancellation
     // drops the turn before it runs; the skip path must settle it directly.
@@ -109,7 +109,7 @@ describe('Agent.cancel()', () => {
   it('cancel() mid-step aborts the in-flight model call; the turn ends aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -126,7 +126,7 @@ describe('Agent.cancel()', () => {
   it('cancel() with no reason defaults to "cancelled" when aborting an in-flight step', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -142,7 +142,7 @@ describe('Agent.cancel()', () => {
   it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => {
     const adapter = new MockAdapter(['hang', textResponse('second reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // First turn hangs; cancel it mid-step.
     send(agent, 'first')
@@ -164,7 +164,7 @@ describe('Agent.cancel()', () => {
   it('cancel from inside the agent/session-prefix waterfall drops the step (prefix-composition window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Prefix composition runs before the pre-step seam on the instance's first
     // step; a cancel landing inside it must drop the about-to-start step
@@ -200,7 +200,7 @@ describe('Agent.cancel()', () => {
     const handle = await ctx.agents.create({
       agentId: AgentId('a-dispose-prefix'),
       sessionId: SessionId('dispose-prefix-session'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const agent = handle.agent as ReactLoopAgent
 
@@ -227,7 +227,7 @@ describe('Agent.cancel()', () => {
   it('a cancel-interrupted prefix composition is discarded: the next send recomposes and ships the fresh prefix (stale-cache guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // The interrupted first composition must not cache its degraded empty value;
     // the next prompt recomposes and logs/sends the fresh prefix.
@@ -257,7 +257,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // A turn/start listener fires before a step controller exists, so the
     // turn-scoped marker—not step abort—must drop the pending step.
@@ -284,7 +284,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous step/start session-event listener drops the step (post-step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // A step/start session-event listener fires AFTER step/start is appended
     // (and after the pre-step seam), so cancelling there lands in the SECOND
@@ -325,7 +325,7 @@ describe('Agent.cancel()', () => {
     const handle = await ctx.agents.create({
       agentId: AgentId('a-dispose-step-start'),
       sessionId: SessionId('dispose-step-start-session'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const agent = handle.agent as ReactLoopAgent
 
@@ -355,7 +355,7 @@ describe('Agent.cancel()', () => {
     // `aborted` and run NO second step.
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     const reasons: TurnEndReason[] = []
@@ -387,7 +387,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // `agent/status` is synchronous, so cancellation can land after the first
     // pre-step check; the second check must drop the now-empty turn.
@@ -411,7 +411,7 @@ describe('Agent.cancel()', () => {
     // Cancellation must not settle idle while replacement work remains queued.
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let replaced = false
     const dispose = ctx.on('agent/status', (subject, status) => {
@@ -438,7 +438,7 @@ describe('Agent.cancel()', () => {
     // prompt B is queued before the loop resumes from the idle wait.
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'A')           // queues A (status still idle, loop microtask pending)
     const idle = agent.whenIdle() // registers a waiter (idle + hasQueued → no fast path)
@@ -457,7 +457,7 @@ describe('Agent.cancel()', () => {
   it("cancel clears the turn's steering — it is not re-enqueued as a fresh turn", async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -32,7 +32,7 @@ describe('config-driven session id', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     const loopFiber = await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('deferred') }],
+      agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('deferred') }],
     })
 
     const resumeEffect = loopFiber.getEffects().find(effect => effect.label === 'agentLoop.resume(main)')
@@ -53,7 +53,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SystemPrompt)
     await ctx1.plugin(ToolRegistry)
     await ctx1.plugin(AgentRegistry)
-    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
+    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
     const a1 = ctx1.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -70,7 +70,7 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
     const a2 = ctx2.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -109,7 +109,7 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('second')]))
 
@@ -137,7 +137,7 @@ describe('config-driven session id', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('does-not-exist') }] })
+    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('does-not-exist') }] })
     const warn = vi.spyOn((ctx.agentLoop as unknown as { ctx: { logger: { warn: (...a: unknown[]) => void } } }).ctx.logger, 'warn')
       .mockImplementation(() => undefined)
     await ctx.plugin(SessionPersistenceJsonl, { root })

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -41,7 +41,9 @@ function send(agent: ReactLoopAgent, text: string) {
 
 describe('session log records what agent/step-result actually produced', () => {
   it('a step-result rewrite is what the log, derived history, and tool dispatch all see', async () => {
-    const adapter = new MockAdapter([textResponse('original'), textResponse('done')])
+    const original = textResponse('original')
+    original[original.length - 1] = { type: 'finish', reason: { kind: 'stop' }, replayState: { private: 'original-state' } }
+    const adapter = new MockAdapter([original, textResponse('done')])
     const ctx = await harness(adapter)
     const executed: string[] = []
     ctx.tools.register(defineTool({
@@ -53,7 +55,7 @@ describe('session log records what agent/step-result actually produced', () => {
         return [{ type: 'text', text: 'ran' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Plugin rewrites the message: replaces the text AND adds a tool call.
     let rewritten = false
@@ -78,6 +80,7 @@ describe('session log records what agent/step-result actually produced', () => {
     const recorded = agent.session.events.find(e => e.type === 'assistant/message')!
     expect(JSON.stringify(recorded.data)).toContain('rewritten')
     expect(JSON.stringify(recorded.data)).not.toContain('original')
+    expect(recorded.type === 'assistant/message' && recorded.data.provenance.replayState).toBeUndefined()
     // tool/call + tool/result correlate with the injected call id
     const callEvent = agent.session.events.find(e => e.type === 'tool/call')!
     if (callEvent.type !== 'tool/call') throw new Error('wrong event type')
@@ -87,6 +90,46 @@ describe('session log records what agent/step-result actually produced', () => {
     expect(JSON.stringify(derived)).toContain('rewritten')
     expect(JSON.stringify(derived)).not.toContain('original')
   })
+
+  it('records adapter replay state when step-result preserves the assembled content', async () => {
+    const response = textResponse('unchanged')
+    const replayState = { private: 'state' }
+    response[response.length - 1] = { type: 'finish', reason: { kind: 'stop' }, replayState }
+    const adapter = new MockAdapter([response])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('replay-state'), { provider: 'mock', model: 'next-model' })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const recorded = agent.session.events.find(e => e.type === 'assistant/message')
+    expect(recorded?.type === 'assistant/message' && recorded.data.provenance).toEqual({
+      provider: 'mock', model: 'next-model', replayState,
+    })
+    expect(agent.session.deriveMessages().at(-1)?.provenance).toEqual({
+      provider: 'mock', model: 'next-model', replayState,
+    })
+  })
+
+  it('drops adapter replay state when step-result mutates assembled content in place', async () => {
+    const response = textResponse('original')
+    response[response.length - 1] = { type: 'finish', reason: { kind: 'stop' }, replayState: { private: 'state' } }
+    const adapter = new MockAdapter([response])
+    const ctx = await harness(adapter)
+    ctx.on('agent/step-result', async (_agent, _turn, _step, message) => {
+      const block = message.content[0]
+      if (block?.type === 'text') block.text = 'mutated'
+      return message
+    })
+    const agent = ctx.agentLoop.create(AgentId('mutated-replay-state'), { provider: 'mock', model: 'next-model' })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const recorded = agent.session.events.find(event => event.type === 'assistant/message')
+    expect(recorded?.type === 'assistant/message' && recorded.data.content).toEqual([{ type: 'text', text: 'mutated' }])
+    expect(recorded?.type === 'assistant/message' && recorded.data.provenance.replayState).toBeUndefined()
+  })
 })
 
 describe('abort during tool execution ends the turn', () => {
@@ -104,7 +147,7 @@ describe('abort during tool execution ends the turn', () => {
     ])
     const ctx = await harness(adapter)
     const executed: string[] = []
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'aborter',
       description: '',
@@ -148,7 +191,7 @@ describe('steering from late extension points is never stranded', () => {
       textResponse('continued because of steering'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let steeredOnce = false
     ctx.on('agent/turn-continuation', async (_agent, _turn, _decision, next) => {
@@ -174,7 +217,7 @@ describe('steering from late extension points is never stranded', () => {
       textResponse('after goal reminder'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let steeredOnce = false
     ctx.on('session/event', (subject, event) => {
@@ -202,7 +245,7 @@ describe('steering from late extension points is never stranded', () => {
   it('steer() from a turn/end session-event listener becomes a queued message for the next turn', async () => {
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const turns: number[] = []
     let steeredOnce = false
@@ -228,7 +271,7 @@ describe('steering from late extension points is never stranded', () => {
   it('steering queued during an aborted step is re-delivered, not silently consumed', async () => {
     const adapter = new MockAdapter(['hang', textResponse('recovered')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -251,7 +294,7 @@ describe('plugin exceptions are contained', () => {
   it('a throwing agent/turn-continuation listener ends the turn with an error, loop survives', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/turn-continuation', async (): Promise<ContinuationDecision> => {
@@ -279,7 +322,7 @@ describe('plugin exceptions are contained', () => {
   it('a rejecting session/flush listener is reported but does not kill the agent', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let rejectedOnce = false
     ctx.on('session/flush', async () => {
@@ -309,7 +352,7 @@ describe('disposed status is part of the agent/status contract', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const statuses: string[] = []
@@ -332,7 +375,7 @@ describe('disposed status is part of the agent/status contract', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     ctx.on('agent/status', (_agent, status) => {
@@ -358,7 +401,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(() => ctx.llm.registerAdapter(['m1'], new MockAdapter([])))
       .toThrow('already registered')
     // the original registration survives the failed attempt
-    expect(ctx.llm.models()).toEqual(['m1'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'm1', name: 'm1' }])
   })
 
   it('an agent without a model fails the step with a clear error (not NO_ADAPTER for "default")', async () => {
@@ -372,7 +415,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
     expect(errors).toHaveLength(1)
-    expect(errors[0]!.message).toContain('has no model')
+    expect(errors[0]!.message).toContain('has no provider/model')
     expect(errors[0]!.message).toContain('agent/request')
   })
 
@@ -382,7 +425,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     const agent = ctx.agentLoop.create(AgentId('a1'), {}) // no model — router plugin decides
 
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
-      return { ...config, model: 'mock' }
+      return { ...config, provider: 'mock', model: 'mock' }
     })
 
     send(agent, 'go')
@@ -394,7 +437,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('agent/queued carries the resolved source; steering/message records its source', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'noop',
       description: '',
@@ -422,7 +465,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('send() owns content and source before notification and delivery', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('owned-send'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('owned-send'), { provider: 'mock', model: 'mock' })
     const content = [{ type: 'text' as const, text: 'accepted-send' }]
     const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
     let notifiedContent: ContentBlock[] | undefined
@@ -458,7 +501,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('running steer() owns content and source before notification and delivery', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'gate', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('owned-steer'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('owned-steer'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
     ctx.tools.register(defineTool({
@@ -512,7 +555,7 @@ describe('turn numbering continues across seeded sessions', () => {
   it('a forked agent continues turn numbers after the seed log', async () => {
     const first = new MockAdapter([textResponse('turn one')])
     const ctx = await harness(first)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -528,7 +571,7 @@ describe('turn numbering continues across seeded sessions', () => {
     ctx2.llm.registerAdapter(['mock'], second)
 
     const seeded = ctx2.sessions.create(SessionId('forked'), { seed: [...agent.session.events] })
-    const prepared = prepareReactLoopAgent(ctx2, AgentId('forked-agent'), { model: 'mock' }, seeded)
+    const prepared = prepareReactLoopAgent(ctx2, AgentId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded)
     const forked = prepared.agent
     prepared.markPublished()
     ctx2.effect(() => prepared.startDriver())
@@ -572,7 +615,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-error'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-finish-error'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -597,7 +640,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([abortedStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-aborted'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-finish-aborted'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -615,7 +658,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-error-nocode'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-finish-error-nocode'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -631,7 +674,7 @@ describe('step boundary publication order', () => {
   it('the step/start event is in session.events when its session/event listener fires', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-step-order'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-step-order'), { provider: 'mock', model: 'mock' })
 
     // Append commits before observers run.
     const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
@@ -686,7 +729,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/start observer cannot change a successful turn', async () => {
     const adapter = new MockAdapter([textResponse('request completed')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepstart'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-stepstart'), { provider: 'mock', model: 'mock' })
 
     // Session owns post-commit containment. The loop sees a successful append,
     // runs the request, and balances the ordinary step and turn boundaries.
@@ -715,7 +758,7 @@ describe('turn and step boundary recovery', () => {
   it('a pre-commit step/start validation failure does not invent a step boundary', async () => {
     const adapter = new MockAdapter([textResponse('never reached')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepstart-veto'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-stepstart-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -746,7 +789,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider failed' } }]
     const adapter = new MockAdapter([errorStream])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-turnend-veto'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-turnend-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -780,7 +823,7 @@ describe('turn and step boundary recovery', () => {
   it('a one-shot step/end validation failure keeps the step open until retry succeeds', async () => {
     const adapter = new MockAdapter([textResponse('completed before close validation')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepend-veto'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-stepend-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -812,7 +855,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-errorlistener'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-errorlistener'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/error', () => { if (!threw) { threw = true; throw new Error('boom error-listener') } })
@@ -845,7 +888,7 @@ describe('turn and step boundary recovery', () => {
     const ctx = await balancedHarness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-dispose'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -872,7 +915,7 @@ describe('turn and step boundary recovery', () => {
     const ctx = await balancedHarness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-prestep-dispose-throw'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-prestep-dispose-throw'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     let threw = false
@@ -903,7 +946,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing turn/start observer cannot starve the loop or later turns', async () => {
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-preturn'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-preturn'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_session, event) => {
@@ -934,7 +977,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/end observer cannot rewrite the turn outcome', async () => {
     const adapter = new MockAdapter([textResponse('all good'), textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepend-throw'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-stepend-throw'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -973,7 +1016,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stependthrow'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-stependthrow'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1003,7 +1046,7 @@ describe('turn and step boundary recovery', () => {
     // boundary stays authoritative and the loop continues normally.
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-turnendappend'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-turnendappend'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1049,7 +1092,7 @@ describe('tool result call identity', () => {
       return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'ok' }] })
     }, { prepend: true })
 
-    const agent = ctx.agentLoop.create(AgentId('a-callid'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-callid'), { provider: 'mock', model: 'mock' })
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
 
@@ -1079,7 +1122,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
       role: 'assistant' as const,
@@ -1126,7 +1169,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-assemble'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-dispose-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1176,7 +1219,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-cancel-assemble'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-cancel-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1230,7 +1273,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-prestep'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-dispose-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1281,7 +1324,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-cancel-prestep'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-cancel-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1331,7 +1374,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-no-leak'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('a-dispose-no-leak'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     send(agent, 'go')

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -40,7 +40,7 @@ describe('inbox acceptance', () => {
   it('rejects non-serializable content or source synchronously before notification or enqueue', async () => {
     const adapter = new MockAdapter([textResponse('turn 1')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     let queued = 0
     ctx.on('agent/queued', () => { queued += 1 })
 
@@ -80,7 +80,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: typeof args === 'string' ? `raw: ${args}` : JSON.stringify(args) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -113,7 +113,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: 'ran with empty args' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -126,7 +126,7 @@ describe('toError normalization', () => {
   it('normalizes non-Error throws from pre-commit dispatch validation via the runLoop backstop', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
@@ -152,7 +152,7 @@ describe('toError normalization', () => {
   it('normalizes non-Error throws from agent/request waterfall via inline toError in runStep catch', async () => {
     const adapter = new MockAdapter([textResponse('irrelevant')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_agent, _turn, _step, _options, _next) => {
@@ -180,7 +180,7 @@ describe('coded error data emission', () => {
   it('errorData includes code when a coded error (LlmError) is thrown from a plugin', async () => {
     const adapter = new MockAdapter([textResponse('turn 1')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_agent, _turn, _step, _options, next) => {
@@ -214,7 +214,7 @@ describe('disposed vs aborted branching', () => {
     const ctx = await harness(adapter)
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -240,7 +240,7 @@ describe('structured tool error propagation (the runtime-validation RFC, part 2)
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'boom',
       description: 'always fails',

packages/core/agent-loop/tests/interception.spec.ts

@@ -57,7 +57,7 @@ describe('agent/prompt-submit', () => {
   it('allow (default via next) records the user/message unchanged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const seen: string[] = []
     ctx.on('agent/prompt-submit', async (_agent, content, _source, next) => {
@@ -76,7 +76,7 @@ describe('agent/prompt-submit', () => {
   it('allow with content REWRITES the prompt before it is recorded', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({ kind: 'allow', content: [{ type: 'text', text: 'REWRITTEN' }] }))
@@ -94,7 +94,7 @@ describe('agent/prompt-submit', () => {
   it('allow with additionalContexts injects separate context/message events into the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const meta = { kind: 'prompt-context', version: 1 }
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
@@ -129,7 +129,7 @@ describe('agent/prompt-submit', () => {
     // compaction listener measures the current surface before the single derive.
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({
@@ -159,7 +159,7 @@ describe('agent/prompt-submit', () => {
   it('block drops the (only) prompt → zero-step turn ends rejected, model never called', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({ kind: 'block', reason: 'blocked by policy' }))
@@ -195,7 +195,7 @@ describe('agent/prompt-submit', () => {
     // the allowed prompt keeps the turn from ending rejected.
     const adapter = new MockAdapter([textResponse('ran once')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (_agent, content, _source, next): Promise<PromptDecision> => {
       const text = content.map(b => (b.type === 'text' ? b.text : '')).join('')
@@ -231,7 +231,7 @@ describe('agent/prompt-submit', () => {
   it('a throwing prompt-submit listener ends the turn balanced (error), loop survives', async () => {
     const adapter = new MockAdapter([textResponse('after')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/prompt-submit', async () => {
@@ -264,7 +264,7 @@ describe('agent/session-start', () => {
     const sources: SessionStartSource[] = []
     ctx.on('agent/session-start', (_agent, source) => void sources.push(source))
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     // fires synchronously at create, before any turn
     expect(sources).toEqual(['startup'])
     expect(events(agent).some(e => e.type === 'turn/start')).toBe(false)
@@ -283,7 +283,7 @@ describe('agent/session-start', () => {
       agent.inject([{ type: 'text', text: 'session preamble' }], { source: { kind: 'plugin', plugin: 'test' } })
     })
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
@@ -301,7 +301,7 @@ describe('agent/session-start', () => {
     ctx.on('agent/session-start', () => { throw new Error('session-start hook broke') })
 
     // create must not throw — the listener error is contained/logged
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     expect(agent.id).toBe(AgentId('a1'))
 
     // and the agent still runs
@@ -315,8 +315,8 @@ describe('agent/session-prefix', () => {
   it('dispatches to global and matching agent-scope listeners only', async () => {
     const adapter = new MockAdapter([textResponse('a done'), textResponse('b done')])
     const ctx = await harness(adapter)
-    const agentA = ctx.agentLoop.create(AgentId('prefix-a'), { model: 'mock' })
-    const agentB = ctx.agentLoop.create(AgentId('prefix-b'), { model: 'mock' })
+    const agentA = ctx.agentLoop.create(AgentId('prefix-a'), { provider: 'mock', model: 'mock' })
+    const agentB = ctx.agentLoop.create(AgentId('prefix-b'), { provider: 'mock', model: 'mock' })
     const seen: string[] = []
     ctx.on('agent/session-prefix', async (agent, _prefix, _signal, next) => {
       seen.push(`global:${agent.id}`)
@@ -353,7 +353,7 @@ describe('agent/session-prefix', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reminder: Message = { role: 'user', content: [{ type: 'text', text: '<system-reminder>catalog</system-reminder>' }] }
     let composed = 0
@@ -386,7 +386,7 @@ describe('agent/session-prefix', () => {
   it('composes before the first pre-step and hands the prefix to the seam (pressure gates see the real value)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'opener' }] }
     const order: string[] = []
@@ -413,7 +413,7 @@ describe('agent/session-prefix', () => {
   it('the canonical prepend pattern composes contributions in registration order', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Both listeners use the canonical `[mine, ...await next()]` prepend: the
     // waterfall unwinds innermost-first (the second listener's array is built
@@ -435,7 +435,7 @@ describe('agent/session-prefix', () => {
   it('with no contributions the header omits messagePrefix and the request is the bare derivation', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // A listener that delegates without contributing — the canonical no-op.
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => next())
@@ -451,7 +451,7 @@ describe('agent/session-prefix', () => {
   it('the frozen seed rejects in-place mutation — a contribution is a returned extension', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let mutationError: unknown
     ctx.on('agent/session-prefix', async (_agent, prefix, _signal, next): Promise<Message[]> => {
@@ -480,7 +480,7 @@ describe('agent/session-prefix', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const held: Message = { role: 'user', content: [{ type: 'text', text: 'v1' }] }
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => [...await next(), held])
@@ -501,7 +501,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
   it('a continue decision with a reason records next-step steering in the same turn', async () => {
     const adapter = new MockAdapter([textResponse('step 1 no tools'), textResponse('step 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let forced = false
     ctx.on('agent/turn-continuation', async (_agent, _turn, _default, next): Promise<ContinuationDecision> => {
@@ -533,7 +533,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/turn-continuation', async (): Promise<ContinuationDecision> => ({ action: 'stop' }))
 
@@ -563,7 +563,7 @@ describe('tool additionalContexts buffering across a step', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // Each call attaches one context naming itself.
     ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
@@ -611,7 +611,7 @@ describe('tool additionalContexts buffering across a step', () => {
         return [{ type: 'text', text: 'outer result' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -638,7 +638,7 @@ describe('tools/pre-execute gate (native-plugin permission pattern, end-to-end t
       name: 'danger', description: 'danger', parameters: {},
       async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
       if (exec.name === 'danger') return { kind: 'deny', reason: 'blocked dangerous tool' }
@@ -700,7 +700,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'please echo hi')
     await waitForIdle(ctx, agent)
@@ -723,7 +723,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
     await ctx.plugin(NativeGuard)
-    const agent = ctx.agentLoop.create(AgentId('a2'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -742,7 +742,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     await fiber.dispose()
 
     // After disposal, a destructive prompt is NOT blocked (the listener is gone).
-    const agent = ctx.agentLoop.create(AgentId('a3'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a3'), { provider: 'mock', model: 'mock' })
     send(agent, 'run rm -rf /')
     await waitForIdle(ctx, agent)
     // the prompt ran (not rejected) — proving the prompt-submit listener was disposed

packages/core/agent-loop/tests/loop.spec.ts

@@ -44,7 +44,7 @@ describe('agent loop', () => {
   it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
     const adapter = new MockAdapter([textResponse('hello there')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     // All boundaries — turn and step — are durable session events on the
     // session/event feed (no agent/* mirror). Record them in fire order to
@@ -92,7 +92,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: `echo: ${args.text}` }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -131,7 +131,7 @@ describe('agent loop', () => {
         return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] } }
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -155,7 +155,7 @@ describe('agent loop', () => {
         return []
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -172,7 +172,7 @@ describe('agent loop', () => {
       agentId: AgentId('a-cwd'),
       sessionId: SessionId('s-cwd'),
       meta: { cwd: '/work/space' },
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
 
     const agent = handle.agent as ReactLoopAgent
@@ -188,7 +188,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter, 'In {{cwd}}.')
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -223,11 +223,12 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter, 'You run on {{model}}.')
     ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      assembly.variables['provider'] = 'mock'
       assembly.variables['model'] = 'mock'
       return next()
     })
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
-      return { ...config, model: 'mock' }
+      return { ...config, provider: 'mock', model: 'mock' }
     })
     const agent = ctx.agentLoop.create(AgentId('a-late-model'), {})
 
@@ -255,7 +256,7 @@ describe('agent loop', () => {
       parameters: {},
       execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
     }))
-    const agent = ctx.agentLoop.create(AgentId('bad-meta-agent'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('bad-meta-agent'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -284,7 +285,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     ctx.on('system-prompt/assemble', async () => ({ sections: [], tools: [], variables: {} }))
-    const agent = ctx.agentLoop.create(AgentId('a-no-system'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a-no-system'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -296,7 +297,7 @@ describe('agent loop', () => {
   it('records raw chunks for replay as assistant/chunk session events', async () => {
     const adapter = new MockAdapter([textResponse('abc')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -320,7 +321,7 @@ describe('agent loop', () => {
     ])
     const ctx = await harness(adapter)
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'slow',
       description: '',
@@ -352,7 +353,7 @@ describe('agent loop', () => {
   it('steering while idle behaves like send (starts a turn)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.steer([{ type: 'text', text: 'hello' }])
     await waitForIdle(ctx, agent)
@@ -362,7 +363,7 @@ describe('agent loop', () => {
   it('inject() while idle wraps context in a one-shot turn, visible to the next request', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject([{ type: 'text', text: 'file changed: a.ts' }], { source: { kind: 'plugin', plugin: 'watcher' } })
     // The idle inject records a self-contained turn (turn/start → context/message
@@ -386,7 +387,7 @@ describe('agent loop', () => {
   it('inject() can persist raw structured context without the generic context envelope', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('raw-context'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('raw-context'), { provider: 'mock', model: 'mock' })
     const text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
     const meta = {
       kind: 'workspace-instructions',
@@ -415,7 +416,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     // A tool that injects mid-execution: at this point the agent is running, so
     // inject must append the context/message into the ALREADY-open turn rather
     // than wrap it in its own one-shot turn.
@@ -449,7 +450,7 @@ describe('agent loop', () => {
       textResponse('step 3'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -475,7 +476,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/turn-continuation', async () => ({ action: 'stop' }) as const)
 
@@ -490,8 +491,7 @@ describe('agent loop', () => {
   it('agent/request waterfall switches models by returning a replacement config; the switch is logged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    ctx.llm.registerAdapter(['other-model'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
       // The seed is frozen — config is not a mutable per-call knob; a switch
@@ -524,7 +524,7 @@ describe('agent loop', () => {
       name: 'echo', description: 'echo', parameters: {},
       async execute() { return [{ type: 'text', text: 'echoed' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const fires: { turn: number; step: number; fullSystemPrompt: string }[] = []
     ctx.on('agent/pre-step', (subject, turn, step, fullSystemPrompt) => {
@@ -548,7 +548,7 @@ describe('agent loop', () => {
     // same step's request must include it.
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
     ctx.on('agent/pre-step', (subject) => {
@@ -582,7 +582,7 @@ describe('agent loop', () => {
     // closing, the turn records error, and the loop remains available.
     const adapter = new MockAdapter([textResponse('second turn ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let throwOnce = true
     ctx.on('agent/pre-step', () => {
@@ -616,7 +616,7 @@ describe('agent loop', () => {
   it('cancel() mid-stream ends the turn with reason aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -636,7 +636,7 @@ describe('agent loop', () => {
     // turn stops by default and ends max-tokens, not completed.
     const adapter = new MockAdapter([maxTokensResponse('truncat')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -659,7 +659,7 @@ describe('agent loop', () => {
       textResponse('second half'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -680,7 +680,7 @@ describe('agent loop', () => {
     expect(adapter.requests).toHaveLength(2)
     expect(adapter.requests[1]!.messages).toEqual([
       { role: 'user', content: [{ type: 'text', text: 'go' }] },
-      { role: 'assistant', content: [{ type: 'text', text: 'first half' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'first half' }], provenance: { provider: 'mock', model: 'mock' } },
     ])
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
   })
@@ -690,7 +690,7 @@ describe('agent loop', () => {
     // stop. The per-turn reason must be independent — turn 2 ends completed.
     const adapter = new MockAdapter([maxTokensResponse('cut'), textResponse('clean')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -723,7 +723,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: 'should not run' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -739,7 +739,7 @@ describe('agent loop', () => {
     // skips that host so it does not create a spurious assistant turn.
     const assistantMessage = agent.session.events.find(e => e.type === 'assistant/message')
     expect(assistantMessage?.type === 'assistant/message' && assistantMessage.data).toEqual({
-      turn: 1, step: 1, content: [], usage: { inputTokens: 10, outputTokens: 5 },
+      turn: 1, step: 1, content: [], provenance: { provider: 'mock', model: 'mock' }, usage: { inputTokens: 10, outputTokens: 5 },
     })
   })
 
@@ -761,7 +761,7 @@ describe('agent loop', () => {
       parameters: { text: { type: 'string' } },
       async execute() { return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -780,7 +780,7 @@ describe('agent loop', () => {
     // on the normal step path suppresses a pure trace-only empty assistant/message.
     const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -810,7 +810,7 @@ describe('agent loop', () => {
       expect(message.content).toEqual([{ type: 'text', text: 'partial text' }])
       return next()
     })
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -819,7 +819,7 @@ describe('agent loop', () => {
     expect(agent.session.events.some(e => e.type === 'tool/call')).toBe(false)
     expect(agent.session.deriveMessages()).toEqual([
       { role: 'user', content: [{ type: 'text', text: 'go' }] },
-      { role: 'assistant', content: [{ type: 'text', text: 'partial text' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'partial text' }], provenance: { provider: 'mock', model: 'mock' } },
     ])
   })
 
@@ -837,7 +837,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     let threw = false
     // Post-commit session observers cannot control the loop. The tool call still
     // drives the second model request, and the turn completes normally.
@@ -856,7 +856,7 @@ describe('agent loop', () => {
   it('chains queued messages into consecutive turns', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const turns: number[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -881,7 +881,7 @@ describe('agent loop', () => {
   it('awaits session/flush at turn end (persistence checkpoint)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let flushed = 0
     let flushedBeforeIdle = false
@@ -901,7 +901,7 @@ describe('agent loop', () => {
   it('errors from the model surface as agent/error and end the turn', async () => {
     const adapter = new MockAdapter([]) // script exhausted → throws
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const errors: Error[] = []
     const reasons: TurnEndReason[] = []
@@ -926,7 +926,7 @@ describe('agent loop', () => {
 
     let agent!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { model: 'mock' })
+      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     expect(ctx.agents.get(AgentId('scoped'))).toBe(agent)
@@ -951,7 +951,7 @@ describe('agent loop', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), model: 'mock' }],
+      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock' }],
     })
     ctx.llm.registerAdapter(['mock'], adapter)
 
@@ -974,7 +974,7 @@ describe('agent loop', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), model: 'mock', cwd: '/work/project' }],
+      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock', cwd: '/work/project' }],
     })
 
     const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
@@ -995,7 +995,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'run')
     await waitForIdle(ctx, agent)
 

packages/core/agent-loop/tests/properties.spec.ts

@@ -90,7 +90,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
+          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
           const { seen: trace } = recordStatus(ctx, agent)
           const idle = nextIdle(ctx, agent)
           // Send all in one synchronous tick: they queue before the loop wakes.
@@ -115,7 +115,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
+          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
           for (const text of texts) {
             const idle = nextIdle(ctx, agent)
             agent.send([{ type: 'text', text }])
@@ -140,7 +140,7 @@ describe('agent loop scheduling properties', () => {
       async (steps) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
+          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
           // Capture before each send; the last waiter covers the final turn, and
           // awaiting an already-settled earlier waiter is harmless.
           let lastIdle: Promise<void> | undefined

packages/core/agent-loop/tests/request-cache.e2e.ts

@@ -43,7 +43,7 @@ async function loopHarness(): Promise<Context> {
   await created.plugin(ToolRegistry)
   await created.plugin(AgentRegistry)
   await created.plugin(AgentLoop, { agents: [] })
-  await created.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await created.plugin(LlmDeepSeek)
   created.tools.register(defineTool({
     name: 'lookup',
     description: 'Look up the stored value for a key.',
@@ -69,7 +69,7 @@ function waitForIdle(context: Context, agent: Agent): Promise<void> {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('log-derived request cache hits (real API)', () => {
   it('every request after the first hits the provider prefix cache', async () => {
     ctx = await loopHarness()
-    const agent = ctx.agentLoop.create(AgentId('cache-e2e'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('cache-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     // Turn 1: forces a tool call → at least two steps (two model requests).
     agent.send([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])

packages/core/agent-loop/tests/request-log.spec.ts

@@ -29,7 +29,7 @@ describe('recordRequestHeader', () => {
   it("anchors a new conversation with an 'initial' snapshot, then logs nothing while unchanged", () => {
     const session = openSession('rl-initial')
     const state = createTransmissionLog()
-    const header = canonicalHeader({ config: { model: 'm' }, system: 's', tools: [tool('t')] })
+    const header = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 's', tools: [tool('t')] })
 
     recordRequestHeader(session, state, header)
     const [first] = headerEvents(session)
@@ -41,7 +41,7 @@ describe('recordRequestHeader', () => {
 
   it("anchors a fresh loop instance over an anchored log with a 'resume' snapshot, even unchanged", () => {
     const session = openSession('rl-resume')
-    const header = canonicalHeader({ config: { model: 'm' }, system: 's' })
+    const header = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 's' })
     recordRequestHeader(session, createTransmissionLog(), header)
 
     // A second instance (process restart / fork): the boundary itself is a
@@ -55,10 +55,10 @@ describe('recordRequestHeader', () => {
   it("logs a full 'change' snapshot for a mid-run change, and the fold reproduces the header", () => {
     const session = openSession('rl-change')
     const state = createTransmissionLog()
-    const first = canonicalHeader({ config: { model: 'm' }, system: 'a\nb', tools: [tool('t')] })
+    const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] })
     recordRequestHeader(session, state, first)
 
-    const second = canonicalHeader({ config: { model: 'm' }, system: 'a\nc', tools: [tool('t'), tool('u')] })
+    const second = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nc', tools: [tool('t'), tool('u')] })
     recordRequestHeader(session, state, second)
     const events = headerEvents(session)
     expect(events).toHaveLength(2)
@@ -69,10 +69,10 @@ describe('recordRequestHeader', () => {
   it("records a pure tool reordering as a 'change' snapshot", () => {
     const session = openSession('rl-reorder')
     const state = createTransmissionLog()
-    const first = canonicalHeader({ config: { model: 'm' }, tools: [tool('a'), tool('b')] })
+    const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, tools: [tool('a'), tool('b')] })
     recordRequestHeader(session, state, first)
 
-    const reordered = canonicalHeader({ config: { model: 'm' }, tools: [tool('b'), tool('a')] })
+    const reordered = canonicalHeader({ config: { provider: 'mock', model: 'm' }, tools: [tool('b'), tool('a')] })
     recordRequestHeader(session, state, reordered)
     const events = headerEvents(session)
     expect(events).toHaveLength(2)

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -71,7 +71,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -92,7 +92,7 @@ describe('request stability across the loop', () => {
   it('a later turn append-extends the previous turn (one conversation, one log)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -106,7 +106,7 @@ describe('request stability across the loop', () => {
   it('a compaction replace rewrites the resend, and the log explains it', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -139,7 +139,7 @@ describe('request stability across the loop', () => {
   it('a real system-prompt change is a full changed-header snapshot; a stable prompt logs nothing', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -163,7 +163,7 @@ describe('request stability across the loop', () => {
   it('an inject() during the agent/request waterfall joins the NEXT request (the step/start boundary)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
     ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => {
@@ -191,7 +191,7 @@ describe('request stability across the loop', () => {
   it('a mutation attempt on the frozen request content throws into the step (loud, not silent)', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
@@ -212,7 +212,7 @@ describe('request stability across the loop', () => {
   it('a fresh loop instance over a seeded log anchors with a resume snapshot and stays cache-aligned', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('gen1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('gen1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -224,7 +224,7 @@ describe('request stability across the loop', () => {
       agentId: AgentId('gen2'),
       sessionId: SessionId('gen2-session'),
       seed: [...agent.session.events],
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const agent2 = handle.agent as ReactLoopAgent
     send(agent2, 'second')
@@ -241,7 +241,7 @@ describe('request stability across the loop', () => {
   it('a delegating listener cannot mutate the seed through next() — the fold stays log-true', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => {
       const config = await next()
@@ -275,7 +275,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)

packages/core/agent-loop/tests/resume.spec.ts

@@ -201,7 +201,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const resuming = ctx.agents.resume({
       agentId: AgentId('resumed-atomic'),
       resumeSessionId: sessionId,
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: async (agentCtx) => {
         expect(agentCtx.agent?.id).toBe(AgentId('resumed-atomic'))
         expect(agentCtx.agent?.session.events).toHaveLength(2)
@@ -242,7 +242,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const handle = await ctx.agents.resume({
       agentId,
       resumeSessionId: sessionId,
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const transactionLabels = [
       `agentLoop.owner(${agentId})`,
@@ -267,7 +267,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await expect(ctx.agents.resume({
       agentId: AgentId('resume-reject'),
       resumeSessionId: sessionId,
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
         await Promise.resolve()
         throw new Error('resume setup failed')
@@ -280,7 +280,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const retry = await ctx.agents.resume({
       agentId: AgentId('resume-reject'),
       resumeSessionId: sessionId,
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     await retry.dispose()
     await ctx.fiber.dispose()
@@ -301,7 +301,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
       resuming = inner.agents.resume({
         agentId: AgentId('resume-owner-race'),
         resumeSessionId: sessionId,
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
           setupStarted.resolve(undefined)
           await gate.promise
@@ -348,7 +348,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
     let resuming!: ReturnType<typeof ctx.agents.resume>
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
-      resuming = inner.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } })
+      resuming = inner.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
     await loadStarted.promise
 
@@ -360,7 +360,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
     // owner.dispose() awaited transaction settlement, so the same identities
     // can be reused before awaiting the public rejection.
-    const retry = await promptly(ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } }))
+    const retry = await promptly(ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } }))
     await rejection
     expect(loads).toBe(2)
     expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
@@ -404,7 +404,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ctx.on('session/created', () => void published.push('session/created'))
     ctx.on('agent/created', () => void published.push('agent/created'))
 
-    const resuming = ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } })
+    const resuming = ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     await loadStarted.promise
     const rejection = expect(promptly(resuming)).rejects.toThrow(/agent loop is not active/)
     await promptly(loopFiber.dispose())

packages/core/agent-loop/tests/scope-lifecycle.spec.ts

@@ -144,7 +144,7 @@ describe('agent scope lifecycle', () => {
 
   it('wires agent.ctx: tagged with the agent, DX field set, ctx.agent safe elsewhere', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     expect(scopeOf(agent.ctx)).toBe(agent)
     expect(agent.ctx.agent).toBe(agent)
     // The root accessor default: a plain context answers undefined, not a throw.
@@ -154,7 +154,7 @@ describe('agent scope lifecycle', () => {
 
   it('scoped registrations live in the agent world and die with the agent', async () => {
     const ctx = await harness()
-    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { model: 'mock' } })
+    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
     const { agent } = handle
     agent.ctx.systemPrompt.section({ name: 'deployment:persona', order: 0, text: 'You run tests.' })
     agent.ctx.tools.register({
@@ -179,8 +179,8 @@ describe('agent scope lifecycle', () => {
 
   it('agent.ctx listeners hear only their own agent (scoped dispatch end to end)', async () => {
     const ctx = await harness(new MockAdapter([textResponse('one'), textResponse('two')]))
-    const a = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
-    const b = ctx.agentLoop.create(AgentId('b'), { model: 'mock' })
+    const a = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
+    const b = ctx.agentLoop.create(AgentId('b'), { provider: 'mock', model: 'mock' })
 
     const heard: string[] = []
     a.ctx.on('agent/status', (subject, status) => void heard.push(`a-sees:${subject.id}:${status}`))
@@ -212,7 +212,7 @@ describe('agent scope lifecycle', () => {
     const handle = await ctx.agents.create({
       agentId: AgentId('child'),
       sessionId: SessionId('child-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: async (agentCtx) => {
         order.push('setup')
         await Promise.resolve()
@@ -236,7 +236,7 @@ describe('agent scope lifecycle', () => {
     })
     ctx.on('agent/created', () => void order.push('agent/created'))
     ctx.on('agent/session-start', () => void order.push('agent/session-start'))
-    const acceptedOptions = { model: 'mock' }
+    const acceptedOptions = { provider: 'mock', model: 'mock' }
 
     const creating = ctx.agents.create({
       agentId: AgentId('atomic'),
@@ -285,13 +285,13 @@ describe('agent scope lifecycle', () => {
     const first = ctx.agents.create({
       agentId,
       sessionId: SessionId('concurrent-final-enter-a'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup,
     })
     const second = ctx.agents.create({
       agentId,
       sessionId: SessionId('concurrent-final-enter-b'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup,
     })
     await bothStarted.promise
@@ -320,7 +320,7 @@ describe('agent scope lifecycle', () => {
     const pending = ctx.agents.create({
       agentId: AgentId('signal-pending'),
       sessionId: SessionId('signal-pending-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       signal: pendingController.signal,
       setup: async () => {
         setupStarted.resolve(undefined)
@@ -337,7 +337,7 @@ describe('agent scope lifecycle', () => {
     const live = await ctx.agents.create({
       agentId: AgentId('signal-live'),
       sessionId: SessionId('signal-live-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       signal: liveController.signal,
     })
     liveController.abort(new Error('too late'))
@@ -360,7 +360,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('owner-race'),
         sessionId: SessionId('owner-race-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
           setupStarted.resolve(undefined)
           await gate.promise
@@ -388,7 +388,7 @@ describe('agent scope lifecycle', () => {
       creating2 = inner.agents.create({
         agentId: AgentId('owner-race-2'),
         sessionId: SessionId('owner-race-s-2'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
           setupStarted2.resolve(undefined)
           await gate2.promise
@@ -415,7 +415,7 @@ describe('agent scope lifecycle', () => {
     const creating = ctx.agents.create({
       agentId: AgentId('factory-setup-race'),
       sessionId: SessionId('factory-setup-race-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
         setupStarted.resolve(undefined)
         await gate.promise
@@ -446,7 +446,7 @@ describe('agent scope lifecycle', () => {
     const creating = ctx.agents.create({
       agentId: AgentId('factory-scope-race'),
       sessionId: SessionId('factory-scope-race-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: () => { setupCalls += 1 },
     })
     await expect(creating).rejects.toThrow(/agent loop is not active/)
@@ -481,7 +481,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('caller-scope-race'),
         sessionId: SessionId('caller-scope-race-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
     }, { inject: ['agents'] }))
 
@@ -511,7 +511,7 @@ describe('agent scope lifecycle', () => {
       void loopFiber.dispose()
     })
 
-    expect(() => ctx.agentLoop.create(AgentId('config-scope-race'), { model: 'mock' }))
+    expect(() => ctx.agentLoop.create(AgentId('config-scope-race'), { provider: 'mock', model: 'mock' }))
       .toThrow(/agent loop is not active/)
     await loopFiber.dispose()
     expect(ctx.agents.get(AgentId('config-scope-race'))).toBeUndefined()
@@ -523,9 +523,9 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     const id = AgentId('config-prepare-failure')
 
-    expect(() => ctx.agentLoop.create(id, { model: 'mock' }, { cwd: 'relative' }))
+    expect(() => ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: 'relative' }))
       .toThrow(/absolute path/)
-    const replacement = ctx.agentLoop.create(id, { model: 'mock' }, { cwd: '/recovered' })
+    const replacement = ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: '/recovered' })
     expect(ctx.agents.get(id)).toBe(replacement)
     await replacement.whenIdle()
     await ctx.fiber.dispose()
@@ -544,7 +544,7 @@ describe('agent scope lifecycle', () => {
     await expect(ctx.agents.create({
       agentId: AgentId('factory-scope-throw'),
       sessionId: SessionId('factory-scope-throw-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('scope preparation failed')
     await loopFiber.dispose()
     expect(ctx.agents.get(AgentId('factory-scope-throw'))).toBeUndefined()
@@ -560,7 +560,7 @@ describe('agent scope lifecycle', () => {
     const handle = await ctx.agents.create({
       agentId,
       sessionId: SessionId('factory-live-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
 
     await loopFiber.dispose()
@@ -585,7 +585,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('dependency-origin'),
         sessionId: SessionId('dependency-origin-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
         setup: (agentCtx) => {
           agentCtx.tools.register({
             name: 'dependency-origin-tool',
@@ -640,7 +640,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('session-created-barrier'),
         sessionId: SessionId('session-created-barrier-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
     }, { inject: ['agents'] }))
 
@@ -689,7 +689,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('agent-created-barrier'),
         sessionId: SessionId('agent-created-barrier-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
     }, { inject: ['agents'] }))
 
@@ -723,7 +723,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('listener-dispose'),
         sessionId: SessionId('listener-dispose-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
     }, { inject: ['agents'] }))
 
@@ -764,7 +764,7 @@ describe('agent scope lifecycle', () => {
       creating = inner.agents.create({
         agentId: AgentId('session-start-dispose'),
         sessionId: SessionId('session-start-dispose-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
     }, { inject: ['agents'] }))
 
@@ -789,7 +789,7 @@ describe('agent scope lifecycle', () => {
     await expect(ctx.agents.create({
       agentId: AgentId('bad'),
       sessionId: SessionId('bad-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
         await Promise.resolve()
         throw new Error('boom setup')
@@ -800,7 +800,7 @@ describe('agent scope lifecycle', () => {
     expect(published).toEqual([])
     expect(ctx.agents.get(AgentId('bad'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('bad-s'))).toBeUndefined()
-    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { model: 'mock' } })
+    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     await retry.dispose()
   })
 
@@ -819,7 +819,7 @@ describe('agent scope lifecycle', () => {
     await expect(ctx.agents.create({
       agentId: AgentId('exotic-seed'),
       sessionId: SessionId('exotic-seed-session'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       seed,
     })).rejects.toThrow(/seed event at index 0 is not losslessly JSON-serializable/)
 
@@ -829,7 +829,7 @@ describe('agent scope lifecycle', () => {
     const retry = await ctx.agents.create({
       agentId: AgentId('exotic-seed'),
       sessionId: SessionId('exotic-seed-session'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     await retry.dispose()
   })
@@ -843,13 +843,13 @@ describe('agent scope lifecycle', () => {
       if (boom) { boom = false; throw new Error('boom created') }
     })
     await expect(ctx.agents.create({
-      agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { model: 'mock' },
+      agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('boom created')
     expect(ctx.agents.get(AgentId('bad'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('bad-s'))).toBeUndefined()
     expect(disposed).toEqual([]) // inserted but never announced: no impossible disposed edge
     // The rollback also disposed the scope fiber: re-creating works cleanly.
-    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { model: 'mock' } })
+    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     expect(scopeOf(retry.agent.ctx)).toBe(retry.agent)
     await retry.dispose()
   })
@@ -868,7 +868,7 @@ describe('agent scope lifecycle', () => {
     await expect(ctx.agents.create({
       agentId: AgentId('partial-agent'),
       sessionId: SessionId('partial-session'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('agent observer failed')
 
     expect(lifecycle).toEqual([
@@ -892,7 +892,7 @@ describe('agent scope lifecycle', () => {
       }
     })
 
-    expect(() => ctx.agentLoop.create(AgentId('config-bad'), { model: 'mock' }))
+    expect(() => ctx.agentLoop.create(AgentId('config-bad'), { provider: 'mock', model: 'mock' }))
       .toThrow('config publish failed')
     expect(ctx.agents.get(AgentId('config-bad'))).toBeUndefined()
     expect(ctx.sessions.list()).toHaveLength(sessionsBefore)
@@ -900,15 +900,15 @@ describe('agent scope lifecycle', () => {
 
   it('registrations through a disposed agent ctx throw INACTIVE_EFFECT', async () => {
     const ctx = await harness()
-    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { model: 'mock' } })
+    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
     await handle.dispose()
     expect(() => handle.agent.ctx.on('agent/status', () => {})).toThrow(/inactive context/)
   })
 
   it('agentEvents fuses carrier and subject for custom drivers', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
-    const other = ctx.agentLoop.create(AgentId('a2'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const other = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
     const heard: string[] = []
     agent.ctx.on('agent/error', (subject: Agent, turn: number) => void heard.push(`${subject.id}:${turn}`))
 
@@ -921,7 +921,7 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let handle!: Awaited<ReturnType<typeof ctx.agents.create>>
     const owner = await ctx.plugin(Object.assign(async (inner: Context) => {
-      handle = await inner.agents.create({ agentId: AgentId('o1'), sessionId: SessionId('o1-s'), agentOptions: { model: 'mock' } })
+      handle = await inner.agents.create({ agentId: AgentId('o1'), sessionId: SessionId('o1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
     const { agent } = handle
 
@@ -953,7 +953,7 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let handle!: Awaited<ReturnType<typeof ctx.agents.create>>
     const owner = await ctx.plugin(Object.assign(async (inner: Context) => {
-      handle = await inner.agents.create({ agentId: AgentId('h1'), sessionId: SessionId('h1-s'), agentOptions: { model: 'mock' } })
+      handle = await inner.agents.create({ agentId: AgentId('h1'), sessionId: SessionId('h1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
 
     const teardownDone: string[] = []
@@ -976,7 +976,7 @@ describe('agent scope lifecycle', () => {
     const handle = await ctx.agents.create({
       agentId,
       sessionId: SessionId('retired-owner-effect-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
 
     expect(ctx.fiber.getEffects().map(effect => effect.label)).toContain(`agentLoop.owner(${agentId})`)
@@ -994,7 +994,7 @@ describe('agent scope lifecycle', () => {
       handle = await inner.agents.create({
         agentId: AgentId('manual-first'),
         sessionId: SessionId('manual-first-s'),
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
         setup(agentCtx) {
           agentCtx.effect(() => async () => {
             cleanupStarted.resolve(undefined)
@@ -1030,7 +1030,7 @@ describe('agent scope lifecycle', () => {
     const first = await ctx.agents.create({
       agentId,
       sessionId,
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
       setup(agentCtx) {
         agentCtx.effect(() => async () => {
           cleanupStarted.resolve(undefined)
@@ -1043,7 +1043,7 @@ describe('agent scope lifecycle', () => {
     await Promise.all([sessionDisposed.promise, cleanupStarted.promise])
     expect(ctx.agents.get(agentId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
-    const replacement = await ctx.agents.create({ agentId, sessionId, agentOptions: { model: 'mock' } })
+    const replacement = await ctx.agents.create({ agentId, sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     expect(ctx.agents.get(agentId)).toBe(replacement.agent)
     expect(ctx.sessions.get(sessionId)).toBe(replacement.agent.session)
 
@@ -1058,7 +1058,7 @@ describe('agent scope lifecycle', () => {
     const handle = await ctx.agents.create({
       agentId: AgentId('idle-flush'),
       sessionId: SessionId('idle-flush-s'),
-      agentOptions: { model: 'mock' },
+      agentOptions: { provider: 'mock', model: 'mock' },
     })
     const gate = Promise.withResolvers<undefined>()
     let flushStarted = false

packages/core/agent-loop/tests/tool-order.spec.ts

@@ -56,7 +56,7 @@ async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConf
   const adapter = new MockAdapter([textResponse('done')])
   const ctx = await harness(adapter, toolOrder)
   for (const name of registrationOrder) registerNamed(ctx, name)
-  const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+  const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
   agent.send([{ type: 'text', text: 'go' }])
   await waitForIdle(ctx, agent)
   return { ctx, agent, adapter }
@@ -98,7 +98,7 @@ describe('loop-level canonical tool order', () => {
     registerNamed(ctx, 'alpha')
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(0)

packages/core/agent-loop/tests/turn-stop.spec.ts

@@ -45,7 +45,7 @@ describe('agent/turn-stop', () => {
       textResponse('must not be requested'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-steering'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('terminal-steering'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let steered = false
@@ -72,7 +72,7 @@ describe('agent/turn-stop', () => {
       textResponse('must not become a late-steering turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-flush-steering'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('terminal-flush-steering'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let injected = false
@@ -98,7 +98,7 @@ describe('agent/turn-stop', () => {
       textResponse('queued follow-up answer'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-flush-send'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('terminal-flush-send'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let queued = false
@@ -124,8 +124,8 @@ describe('agent/turn-stop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const stopped = ctx.agentLoop.create(AgentId('stopped'), { model: 'mock' })
-    const ordinary = ctx.agentLoop.create(AgentId('ordinary'), { model: 'mock' })
+    const stopped = ctx.agentLoop.create(AgentId('stopped'), { provider: 'mock', model: 'mock' })
+    const ordinary = ctx.agentLoop.create(AgentId('ordinary'), { provider: 'mock', model: 'mock' })
     stopped.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     await send(stopped)
@@ -145,7 +145,7 @@ describe('agent/turn-stop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('owned-listener'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('owned-listener'), { provider: 'mock', model: 'mock' })
     const disposeStop = agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     await send(agent, 'first turn')
@@ -162,7 +162,7 @@ describe('agent/turn-stop', () => {
       textResponse('healthy later turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('bad-policy'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('bad-policy'), { provider: 'mock', model: 'mock' })
     const reasons: TurnEndReason[] = []
     const errors: string[] = []
     ctx.on('session/event', (session, event) => {

packages/core/agent/src/types.ts

@@ -33,7 +33,9 @@ declare module '@deepseek-ai/dsh-system-prompt' {
 
 /** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
 export interface AgentOptions {
-  /** Model name (must have a registered adapter at call time). */
+  /** Provider route (must have a registered adapter at call time). */
+  provider?: string
+  /** Model id interpreted by the selected provider adapter. */
   model?: string
 }
 

packages/core/session/README.md

@@ -33,7 +33,7 @@ The store pairs announced creation with disposal, publishes post-commit append n
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
-- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. A surface rewrite rebuilds the projection; there is no raw-log fallback.
+- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
 - `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
@@ -59,7 +59,7 @@ Durable values need one accepted representation, not a check followed by a secon
 
 ### Session event vocabulary (`types.ts`)
 
-The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
+The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token usage and provider/model/replay provenance ride on `assistant/message`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
 
 Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own types (the compaction seam's `compact/*`, the hook bridges' `hook/*`); merged members appear in the same catalog.
 
@@ -77,7 +77,7 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `create(id, { seed })` validates and freezes a contiguous log and rebuilds its surface. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
+- Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model and assistant messages require provider/model provenance. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
 - Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface entries behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership and `replaceGeneration`.
 
 ## Model Experience

packages/core/session/src/index.ts

@@ -146,6 +146,30 @@ function assertSessionEventEnvelope(value: Record<string, unknown>, index: numbe
     || !Object.hasOwn(event, 'data')) {
     throw new Error(`seed event at index ${index} has an invalid event envelope`)
   }
+  assertCurrentLlmShape(event, index)
+}
+
+/** Reject pre-provider request headers and assistant messages at the seed/load boundary. */
+function assertCurrentLlmShape(event: Record<string, unknown>, index: number): void {
+  const data = event['data']
+  if (typeof data !== 'object' || data === null) return
+  const record = data as Record<string, unknown>
+  if (event['type'] === 'request/header') {
+    const header = record['header']
+    const config = typeof header === 'object' && header !== null ? (header as Record<string, unknown>)['config'] : undefined
+    if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`)
+  }
+  if (event['type'] === 'assistant/message' && !hasProviderModel(record['provenance'])) {
+    throw new Error(`seed assistant/message at index ${index} lacks provider/model provenance`)
+  }
+}
+
+/** Whether an unknown value carries the current provider/model pair. */
+function hasProviderModel(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false
+  const pair = value as Record<string, unknown>
+  return typeof pair['provider'] === 'string' && pair['provider'].length > 0
+    && typeof pair['model'] === 'string' && pair['model'].length > 0
 }
 
 /** Reject request-header vocabulary removed with the legacy delta codec. */
@@ -496,7 +520,7 @@ export class Session {
         // max-tokens step's usage and must not inject a content-less assistant
         // turn into the provider transcript.
         if (event.data.content.length === 0) return null
-        return { role: 'assistant', content: event.data.content }
+        return { role: 'assistant', content: event.data.content, provenance: event.data.provenance }
       }
       case 'tool/result': {
         const { callId, content, isError } = event.data

packages/core/session/src/types.ts

@@ -1,5 +1,5 @@
 import type { Branded } from '@deepseek-ai/dsh-brand'
-import type { CallId, ContentBlock, LlmCallConfig, Message, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { AssistantProvenance, CallId, ContentBlock, LlmCallConfig, Message, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
 import type { JsonValue } from './json.ts'
 
 /** Canonical context-tag framing, or caller-owned framing rendered verbatim. */
@@ -147,7 +147,7 @@ export interface TodoItem {
  * canonical empty optional fields are absent.
  */
 export interface EpochHeader {
-  /** The conversation's call configuration (model + sampling scalars). */
+  /** The conversation's call configuration (provider, model, and sampling scalars). */
   config: LlmCallConfig
   /** Rendered system prompt text; absent for a system-less request. */
   system?: string
@@ -223,7 +223,7 @@ export interface SessionEventMap {
    * the model output and its accounting travel together (there is no separate
    * usage record). `usage` is absent when the adapter reported none.
    */
-  'assistant/message': { turn: number; step: number; content: ContentBlock[]; usage?: TokenUsage }
+  'assistant/message': { turn: number; step: number; content: ContentBlock[]; provenance: AssistantProvenance; usage?: TokenUsage }
   /**
    * The model requested one tool invocation: `name` with the raw `arguments`
    * JSON string exactly as the model produced it (unparsed). `callId` pairs the

packages/core/session/tests/derived-cache.spec.ts

@@ -23,9 +23,9 @@ describe('derived-message cache', () => {
     userText(session, 'one')
     expect(session.deriveMessages()).toEqual(scratch(session))
     userText(session, 'two')
-    session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
     expect(session.deriveMessages()).toEqual(scratch(session))
-    session.append('assistant/message', { turn: 1, step: 2, content: [], usage: { inputTokens: 1, outputTokens: 0 } }, { surfaceOp: 'append' })
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 2, content: [], usage: { inputTokens: 1, outputTokens: 0 } }, { surfaceOp: 'append' })
     expect(session.deriveMessages()).toEqual(scratch(session))
   })
 
@@ -89,7 +89,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => {
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     const boundary = session.append('step/start', { turn: 1, step: 1 })
     expect(session.deriveEventMessage(boundary)).toBeNull()
-    const empty = session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    const empty = session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
     expect(session.deriveEventMessage(empty)).toBeNull()
   })
 })

packages/core/session/tests/fork.spec.ts

@@ -195,14 +195,14 @@ describe('SessionStore.fork', () => {
       ['assistant/message', (session) => {
         session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
         session.append('step/start', { turn: 1, step: 1 })
-        session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'partial' }] }, { surfaceOp: 'append' })
+        session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'partial' }] }, { surfaceOp: 'append' })
         return lastSeq(session)
       }],
       ['tool/call', (session) => {
         const callId = CallId('call-open')
         session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
         session.append('step/start', { turn: 1, step: 1 })
-        session.append('assistant/message', {
+        session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
           turn: 1,
           step: 1,
           content: [{ type: 'tool-call', id: callId, name: 'bash', arguments: '{}' }],

packages/core/session/tests/properties.spec.ts

@@ -28,8 +28,8 @@ const textContentArb = fc.array(
 // explicit `surfaceOp: 'append'` intent — the marker the real loop passes.
 const messageEventArb: fc.Arbitrary<Appendable> = fc.oneof(
   textContentArb.map((content): Appendable => ({ type: 'user/message', data: { content, source: { kind: 'user' } }, intent: { surfaceOp: 'append' } })),
-  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content }, intent: { surfaceOp: 'append' } })),
-  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content, usage: { inputTokens: 1, outputTokens: 1 } }, intent: { surfaceOp: 'append' } })),
+  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content, provenance: { provider: 'mock', model: 'mock' } }, intent: { surfaceOp: 'append' } })),
+  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content, provenance: { provider: 'mock', model: 'mock' }, usage: { inputTokens: 1, outputTokens: 1 } }, intent: { surfaceOp: 'append' } })),
   fc.record({ id: fc.string({ minLength: 1 }), content: textContentArb, isError: fc.boolean() })
     .map((r): Appendable => ({ type: 'tool/result', data: { turn: 1, step: 1, callId: CallId(r.id), content: r.content, isError: r.isError }, intent: { surfaceOp: 'append' } })),
 )

packages/core/session/tests/repair.spec.ts

@@ -56,7 +56,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 2, step: 1, content: [
         { type: 'text', text: 'calling a tool' },
         { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
     ]
     const closers = interruptedTurnClosers(events)
     // tool/result (for the orphaned call) → step/end → turn/end, contiguous seqs.
@@ -74,7 +74,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'step/start', seq: 1, time: 1, data: { turn: 2, step: 1 } },
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 2, step: 1, content: [
         { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
       { type: 'tool/result', seq: 3, time: 3, data: { turn: 2, step: 1, callId: CallId('call-1'), content: [{ type: 'text', text: 'ok' }], isError: false } },
     ]
     // The call is answered, so only the open step + turn need closing.
@@ -88,7 +88,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'step/start', seq: 1, time: 1, data: { turn: 2, step: 1 } },
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 2, step: 1, content: [
         { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
       { type: 'step/end', seq: 3, time: 3, data: { turn: 2, step: 1 } },
     ]
 
@@ -105,7 +105,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 1, step: 1, content: [
         { type: 'tool-call', id: CallId('old-call'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
       { type: 'tool/result', seq: 3, time: 3, data: { turn: 1, step: 1, callId: CallId('old-call'), content: [], isError: false } },
       { type: 'step/end', seq: 4, time: 4, data: { turn: 1, step: 1 } },
       { type: 'turn/end', seq: 5, time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
@@ -113,7 +113,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'step/start', seq: 7, time: 7, data: { turn: 2, step: 1 } },
       { type: 'assistant/message', seq: 8, time: 8, data: { turn: 2, step: 1, content: [
         { type: 'tool-call', id: CallId('new-call'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
     ]
     const closers = interruptedTurnClosers(events)
     expect(closers.map(e => e.type)).toEqual(['tool/result', 'step/end', 'turn/end'])
@@ -128,7 +128,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 1, step: 1, content: [
         { type: 'tool-call', id: CallId('call-a'), name: 'bash', arguments: '{}' },
         { type: 'tool-call', id: CallId('call-b'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
       // call-a got answered before the crash; call-b did not.
       { type: 'tool/result', seq: 3, time: 3, data: { turn: 1, step: 1, callId: CallId('call-a'), content: [], isError: false } },
     ]
@@ -144,7 +144,7 @@ describe('interruptedTurnClosers', () => {
       { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
       { type: 'assistant/message', seq: 2, time: 2, data: { turn: 1, step: 1, content: [
         { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
-      ] } },
+      ], provenance: { provider: 'mock', model: 'mock' } } },
       { type: 'tool/call', seq: 3, time: 3, data: { turn: 1, step: 1, callId: CallId('call-1'), name: 'bash', arguments: '{}' } },
     ]
     const closers = interruptedTurnClosers(events)

packages/core/session/tests/request-header.spec.ts

@@ -5,7 +5,7 @@ import { Session, SessionId, canonicalHeader, foldRequestHeader, headerEquals }
 import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 
-const CONFIG = { model: 'm' }
+const CONFIG = { provider: 'mock', model: 'm' }
 
 function tool(name: string, description = 'd'): ToolSchema {
   return { name, description, parameters: { type: 'object' } }
@@ -28,7 +28,7 @@ describe('headerEquals', () => {
 
   it('compares every canonical field and preserves tool order', () => {
     expect(headerEquals(base, structuredClone(base))).toBe(true)
-    expect(headerEquals(base, { ...base, config: { model: 'other' } })).toBe(false)
+    expect(headerEquals(base, { ...base, config: { provider: 'mock', model: 'other' } })).toBe(false)
     expect(headerEquals(base, { ...base, system: 'other' })).toBe(false)
     expect(headerEquals(base, { ...base, messagePrefix: [msg('other')] })).toBe(false)
     expect(headerEquals(base, { ...base, tools: [] })).toBe(false)
@@ -56,8 +56,8 @@ describe('foldRequestHeader', () => {
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' })
     session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('request/header', { header: { config: { model: 'other' }, tools: [] }, reason: 'change' })
-    expect(foldRequestHeader(session.events)).toEqual({ config: { model: 'other' } })
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'other' }, tools: [] }, reason: 'change' })
+    expect(foldRequestHeader(session.events)).toEqual({ config: { provider: 'mock', model: 'other' } })
   })
 })
 

packages/core/session/tests/session.spec.ts

@@ -10,7 +10,7 @@ describe('Session', () => {
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } })
-    session.append('assistant/message', {
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' },
       turn: 1, step: 1,
       content: [
         { type: 'text', text: 'let me check' },
@@ -85,7 +85,7 @@ describe('Session', () => {
     const original = new Session(SessionId('s3'))
     original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     original.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    original.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] }, { surfaceOp: 'append' })
+    original.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] }, { surfaceOp: 'append' })
     original.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
 
     const replayed = new Session(SessionId('s3-replay'), [...original.events])
@@ -93,6 +93,36 @@ describe('Session', () => {
     expect(replayed.seq).toBe(original.seq)
   })
 
+  it('rejects pre-provider request headers and assistant messages on seed/load', () => {
+    const requestHeader = {
+      type: 'request/header', seq: 0, time: 1,
+      data: { header: { config: { model: 'old-model' } }, reason: 'initial' },
+    } as unknown as SessionEvent
+    expect(() => new Session(SessionId('old-header'), [requestHeader]))
+      .toThrow('seed request/header at index 0 lacks provider/model')
+
+    const assistantMessage = {
+      type: 'assistant/message', seq: 0, time: 1,
+      data: { turn: 1, step: 1, content: [{ type: 'text', text: 'old' }] },
+      surfaceOp: 'append',
+    } as unknown as SessionEvent
+    expect(() => new Session(SessionId('old-assistant'), [assistantMessage]))
+      .toThrow('seed assistant/message at index 0 lacks provider/model provenance')
+
+    const malformedHeader = {
+      type: 'request/header', seq: 0, time: 1,
+      data: { header: 'old-header' },
+    } as unknown as SessionEvent
+    expect(() => new Session(SessionId('malformed-header'), [malformedHeader]))
+      .toThrow('seed request/header at index 0 lacks provider/model')
+
+    const unrelatedPrimitiveData = {
+      type: 'plugin/event', seq: 0, time: 1, data: null,
+    } as unknown as SessionEvent
+    expect(new Session(SessionId('primitive-plugin-data'), [unrelatedPrimitiveData]).events)
+      .toEqual([unrelatedPrimitiveData])
+  })
+
   it('isolates the log from mutation through a derived message (append-only contract)', () => {
     const session = new Session(SessionId('s4'))
     session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })

packages/core/session/tests/surface.spec.ts

@@ -14,7 +14,7 @@ function surfaceSession(): Session {
   const s = new Session(SessionId('ss'))
   s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
   s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-  s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+  s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
   s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
   return s
 }
@@ -82,8 +82,8 @@ describe('SurfaceManager', () => {
     const s = new Session(SessionId('shared-fold'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
-    s.append('assistant/message', { turn: 1, step: 2, content: [{ type: 'text', text: 'summary 2' }] }, { surfaceOp: { op: 'replace', start: 2, end: 1 }, sourceEventSeqs: [2, 1] })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 2, content: [{ type: 'text', text: 'summary 2' }] }, { surfaceOp: { op: 'replace', start: 2, end: 1 }, sourceEventSeqs: [2, 1] })
 
     const folded = foldSurface(s.events)
     expect(folded.nodes).toEqual(s.surface.nodes)
@@ -101,7 +101,7 @@ describe('SurfaceManager', () => {
   it('does not retain fold-only replacement history in incremental state', () => {
     const s = new Session(SessionId('incremental-state'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'b' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'b' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
 
     expect(s.surface.nodes).toEqual([1])
     const manager = s.surface as unknown as { _state: object }
@@ -128,7 +128,7 @@ describe('SurfaceManager', () => {
 
     expect(() => s.append(
       'assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'invalid' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'invalid' }] },
       { surfaceOp: { op: 'replace', start: 0, end: 0 } },
     )).toThrow(/missing 0/)
 
@@ -203,7 +203,7 @@ describe('SurfaceManager', () => {
   it('rebuild with replace operation splices out shadowed nodes', () => {
     const s = surfaceSession()
     s.append('assistant/message',
-      { turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
     )
     expect(s.surface.nodes).toEqual([4])
@@ -216,7 +216,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
     // Replace seq 0 through 1 inclusive: shadow a and b, keep c.
     s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
     ) // seq 3
     expect(s.surface.nodes).toEqual([3, 2])
@@ -228,7 +228,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
     // Replace only seq 1 (single node).
     s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 2
     expect(s.surface.nodes).toEqual([0, 2])
@@ -238,7 +238,7 @@ describe('SurfaceManager', () => {
     const s = new Session(SessionId('bad-start'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
     expect(() => s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
       { surfaceOp: { op: 'replace', start: 5, end: 0 }, sourceEventSeqs: [0] },
     )).toThrow(/surface replace: start seq 5 not found/)
   })
@@ -247,7 +247,7 @@ describe('SurfaceManager', () => {
     const s = new Session(SessionId('bad-end'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
     expect(() => s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
       { surfaceOp: { op: 'replace', start: 0, end: 99 }, sourceEventSeqs: [0] },
     )).toThrow(/surface replace: end seq 99 not found/)
   })
@@ -258,7 +258,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
     // start=1, end=0 would be reversed order.
     expect(() => s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 0 }, sourceEventSeqs: [1, 0] },
     )).toThrow(/start seq 1.*after end seq 0/)
   })
@@ -267,7 +267,7 @@ describe('SurfaceManager', () => {
     const s = new Session(SessionId('immutable'))
     s.append('user/message', { content: [{ type: 'text', text: 'source' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     const sources = [0]
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] }, { surfaceOp: 'append', sourceEventSeqs: sources })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] }, { surfaceOp: 'append', sourceEventSeqs: sources })
     // Mutate caller's array after append.
     sources.push(1)
     sources[0] = 99
@@ -282,7 +282,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
     // Replace the middle node (seq 1) only, keeping seq 0 and seq 2.
     s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 3
     expect(s.surface.nodes).toEqual([0, 3, 2])
@@ -292,7 +292,7 @@ describe('SurfaceManager', () => {
     const s = new Session(SessionId('immutable-op'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     const op = { op: 'replace' as const, start: 0, end: 0 }
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: op, sourceEventSeqs: [0] })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: op, sourceEventSeqs: [0] })
     // Mutate caller's object after append.
     op.start = 99
     const logged = s.events[1]! as SurfaceEvent
@@ -317,7 +317,7 @@ describe('deriveMessages with surface', () => {
     s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
     s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 1, text: 'i' } })
     s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
     s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     // Chunks and boundaries are NOT in the surface, so only 2 messages.
     expect(s.deriveMessages()).toHaveLength(2)
@@ -326,7 +326,7 @@ describe('deriveMessages with surface', () => {
   it('deriveMessages via surface respects replace (shadowed nodes are excluded)', () => {
     const s = new Session(SessionId('compacted'))
     s.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'compacted' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'compacted' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
     // Only the compaction node is visible.
     const messages = s.deriveMessages()
     expect(messages).toHaveLength(1)
@@ -350,7 +350,7 @@ describe('Session.append surface opts', () => {
     s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     s.append('step/start', { turn: 1, step: 1 })
     const event = s.append('assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] },
       { surfaceOp: 'append', sourceEventSeqs: [0, 1] },
     )
     expect(event.sourceEventSeqs).toEqual([0, 1])
@@ -367,7 +367,7 @@ describe('Session.append surface opts', () => {
     const seed: SessionEvent[] = [
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
       { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
-      { type: 'assistant/message', seq: 2, time: 3, data: { turn: 1, step: 1, content: [] }, surfaceOp: 'append' },
+      { type: 'assistant/message', seq: 2, time: 3, data: { turn: 1, step: 1, content: [], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: 'append' },
       { type: 'step/end', seq: 3, time: 4, data: { turn: 1, step: 1 } },
       { type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
     ]
@@ -385,7 +385,7 @@ describe('Session.append surface opts', () => {
 
   it('surfaceOp primitives are not cloned (they are immutable)', () => {
     const s = new Session(SessionId('prim'))
-    const event = s.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    const event = s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
     // The string 'append' is a primitive — identity-preserving is fine.
     expect(event.surfaceOp).toBe('append')
   })

packages/examples/acp-demo/README.md

@@ -25,8 +25,9 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 
 | Key | Default | Routed to |
 |---|---|---|
-| `model` | (required) | the per-session agent template the bridge creates agents from |
-| `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
+| `provider` | (required) | the initial provider route for each per-session agent the bridge creates; ACP model selection may replace it per session |
+| `model` | (required) | the initial model for each per-session agent; ACP clients may switch among adapter-advertised models |
+| `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
 | `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |

packages/examples/acp-demo/src/index.ts

@@ -21,7 +21,7 @@ import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 export const name = 'acp-demo'
 
 /**
- * App config: the swappable per-deployment values. `model` configures the
+ * App config: the swappable per-deployment values. `provider` and `model` configure the
  * agent template the ACP bridge creates each session's agent from (NOT a
  * pre-created agent — ACP creates agents at `session/new`); `persona` is the
  * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
@@ -30,6 +30,8 @@ export const name = 'acp-demo'
  * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
  */
 export interface Config {
+  /** Provider route for ACP-created agents. */
+  provider: string
   /** Model name for ACP-created agents (must have a registered adapter). */
   model: string
   /** Deployment persona (the system-prompt plugin's `persona` config). */
@@ -56,6 +58,7 @@ export interface Config {
 // the common fields would make two small app contracts depend on a new facade.
 /* jscpd:ignore-start */
 export const Config: z<Config> = z.object({
+  provider: z.string().required(),
   model: z.string().required(),
   persona: z.string(),
   // The array default is forced to undefined: ABSENT means "lexicographic
@@ -79,11 +82,11 @@ export const Config: z<Config> = z.object({
  * NO agents (its `agents` list defaults to `[]`) and carries the deployment
  * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
  * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
- * from `model`. No logger, no `hmr` — stdout stays pure.
+ * from the provider/model pair. No logger, no `hmr` — stdout stays pure.
  */
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(agentCore, agentCore.pickSpineConfig(config))
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
-  ctx.plugin(acp, { model: config.model })
+  ctx.plugin(acp, { provider: config.provider, model: config.model })
 }

packages/examples/acp-demo/tests/acp-agent.spec.ts

@@ -70,7 +70,7 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 
 describe('dsh-acp-demo composition', () => {
   it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig(), workspaceContext: false })
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -89,7 +89,7 @@ describe('dsh-acp-demo composition', () => {
     // persistenceRoot, so the runtime fallback is the one that fires.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    acpAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    acpAgent.apply(ctx, { provider: 'mock', model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     await ctx.fiber.dispose()
@@ -97,6 +97,7 @@ describe('dsh-acp-demo composition', () => {
 
   it('forwards explicit project-instruction controls to the bundled spine', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-acp-demo-workspace-context',
@@ -110,7 +111,7 @@ describe('dsh-acp-demo composition', () => {
   it('uses default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
-      acpAgent.apply(ctx, { model: 'mock', workspaceContext: false })
+      acpAgent.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
       await new Promise(resolve => setTimeout(resolve, 50))
       expect(ctx.skills).toBeDefined()
       expect(await ctx.skills.list()).toEqual([])
@@ -120,7 +121,7 @@ describe('dsh-acp-demo composition', () => {
 
   it('forwards skill config and dshHome into agent-spine-demo', async () => {
     const skills = await isolatedSkillsConfig(6)
-    const ctx = await mount({ model: 'mock', persona: 'hi', dshHome: skills.local!.dshHome!, skills, workspaceContext: false })
+    const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', dshHome: skills.local!.dshHome!, skills, workspaceContext: false })
     ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' })
     expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...')
     await ctx.fiber.dispose()
@@ -128,6 +129,7 @@ describe('dsh-acp-demo composition', () => {
 
   it('forwards bundled tool config into agent-core', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       workspaceContext: false,
       toolBash: { enableRunInBackground: false },
@@ -147,6 +149,7 @@ describe('dsh-acp-demo composition', () => {
 
   it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       toolOrder: ['zulu', TOOL_ORDER_REST],
       persistenceRoot: '/tmp/dsh-acp-demo-test-tool-order',

packages/examples/acp-demo/tests/built-bin.e2e.ts

@@ -78,12 +78,12 @@ async function makeConsumer(): Promise<string> {
     '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
     '  config:',
     '    apiKey: !!js process.env.DEEPSEEK_API_KEY',
-    '    models: [deepseek-v4-flash]',
     '- id: bash',
     '  name: \'@deepseek-ai/dsh-bash-local\'',
     '- id: acp-agent',
     '  name: \'@deepseek-ai/dsh-acp-demo\'',
     '  config:',
+    '    provider: deepseek',
     '    model: deepseek-v4-flash',
     '    persona: \'test agent\'',
     '    workspaceContext: false',

packages/examples/acp-demo/tests/load-path.e2e.ts

@@ -36,12 +36,12 @@ const CORDIS_YML = `
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
     apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models: [deepseek-v4-flash]
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
 - id: acp-agent
   name: '@deepseek-ai/dsh-acp-demo'
   config:
+    provider: deepseek
     model: deepseek-v4-flash
     persona: 'You are a test agent.'
     workspaceContext: false

packages/examples/agent-spine-demo/tests/agent-core.spec.ts

@@ -135,7 +135,7 @@ describe('dsh-agent-spine-demo bundle', () => {
 
   it('forwards a pre-created agent to the loop and the persona to system-prompt', async () => {
     const ctx = await mount({
-      agents: [{ id: AgentId('main'), model: 'mock' }],
+      agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock' }],
       persona: 'You are main.',
       workspaceContext: false,
     })
@@ -171,7 +171,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         agentId: AgentId('main'),
         sessionId: SessionId('main-session'),
         meta: { cwd: root },
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
       const agent = handle.agent
 
@@ -202,7 +202,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         agentId: AgentId('main'),
         sessionId: SessionId('main-disabled-session'),
         meta: { cwd: root },
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
 
       handle.agent.send([{ type: 'text', text: 'hi' }])
@@ -292,7 +292,7 @@ describe('dsh-agent-spine-demo bundle', () => {
         agentId: AgentId('main'),
         sessionId: SessionId('prefix-order-session'),
         meta: { cwd: root },
-        agentOptions: { model: 'mock' },
+        agentOptions: { provider: 'mock', model: 'mock' },
       })
 
       handle.agent.send([{ type: 'text', text: 'hi' }])

packages/examples/stdio-demo/README.md

@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's provider/model pair with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
@@ -25,8 +25,9 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 
 | Key | Default | Routed to |
 |---|---|---|
+| `provider` | (required) | the pre-created `main` agent's registered provider route |
 | `model` | (required) | the pre-created `main` agent's model |
-| `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
+| `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
 | `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
@@ -55,7 +56,6 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
     apiKey: !!js process.env.DEEPSEEK_API_KEY
-    models: [deepseek-v4-flash]
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
@@ -63,6 +63,7 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
 - id: stdio-agent
   name: '@deepseek-ai/dsh-stdio-demo'
   config:
+    provider: deepseek
     model: deepseek-v4-flash
     persona: 'You are a coding assistant powered by the {{model}} model.'
 ```

packages/examples/stdio-demo/src/index.ts

@@ -26,7 +26,7 @@ export const name = 'stdio-demo'
 
 /**
  * App config: the swappable per-demo values, each routed to where the app wires
- * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
+ * it. `provider`/`model`/`resumeSessionId` configure the pre-created `main` agent (through
  * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is
  * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
  * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
@@ -35,6 +35,8 @@ export const name = 'stdio-demo'
  * `welcome` is the UI banner.
  */
 export interface Config {
+  /** Provider route for the `main` agent. */
+  provider: string
   /** Model name for the `main` agent (must have a registered adapter). */
   model: string
   /** Deployment persona (the system-prompt plugin's `persona` config). */
@@ -66,6 +68,7 @@ export interface Config {
 }
 
 export const Config: z<Config> = z.object({
+  provider: z.string().required(),
   model: z.string().required(),
   persona: z.string(),
   // The array default is forced to undefined: ABSENT means "lexicographic
@@ -98,6 +101,7 @@ export function apply(ctx: Context, config: Config): void {
     ...agentCore.pickSpineConfig(config),
     agents: [{
       id: AgentId('main'),
+      provider: config.provider,
       model: config.model,
       cwd: process.cwd(),
       ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},

packages/examples/stdio-demo/tests/built-bin.e2e.ts

@@ -90,6 +90,7 @@ async function makeConsumer(
     '- id: stdio-agent',
     '  name: \'@deepseek-ai/dsh-stdio-demo\'',
     '  config:',
+    '    provider: mock',
     '    model: mock-echo',
     '    persona: \'demo\'',
     '    workspaceContext: false',

packages/examples/stdio-demo/tests/stdio-agent.spec.ts

@@ -66,7 +66,7 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 
 describe('dsh-stdio-demo app', () => {
   it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
     // The spine services (brought up by the agent-spine-demo bundle) are all present.
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('agentLoop')).toBeDefined()
@@ -87,7 +87,7 @@ describe('dsh-stdio-demo app', () => {
     // schema-bypassing direct-mount caller.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    stdioAgent.apply(ctx, { provider: 'mock', model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
     await new Promise(resolve => setTimeout(resolve, 80))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
@@ -96,6 +96,7 @@ describe('dsh-stdio-demo app', () => {
 
   it('forwards explicit project-instruction controls to the bundled spine', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-stdio-demo-spec-workspace-context',
@@ -108,7 +109,7 @@ describe('dsh-stdio-demo app', () => {
   it('uses default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
-      stdioAgent.apply(ctx, { model: 'mock', workspaceContext: false })
+      stdioAgent.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
       await new Promise(resolve => setTimeout(resolve, 80))
       expect(ctx.skills).toBeDefined()
       expect(await ctx.skills.list()).toEqual([])
@@ -121,6 +122,7 @@ describe('dsh-stdio-demo app', () => {
     // session the resume is contained + logged, so no `main` agent registers —
     // the branch that maps resumeSessionId through is what this covers.
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-stdio-demo-spec-resume',
@@ -134,7 +136,7 @@ describe('dsh-stdio-demo app', () => {
 
   it('forwards skill config and dshHome into agent-spine-demo', async () => {
     const skills = await isolatedSkillsConfig(6)
-    const ctx = await mount({ model: 'mock', persona: 'hi', dshHome: skills.local!.dshHome!, skills, workspaceContext: false })
+    const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', dshHome: skills.local!.dshHome!, skills, workspaceContext: false })
     ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' })
     expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...')
     await ctx.fiber.dispose()
@@ -142,6 +144,7 @@ describe('dsh-stdio-demo app', () => {
 
   it('forwards bundled tool config into agent-core', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       workspaceContext: false,
       toolBash: { enableRunInBackground: false },
@@ -161,6 +164,7 @@ describe('dsh-stdio-demo app', () => {
 
   it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
     const ctx = await mount({
+      provider: 'mock',
       model: 'mock',
       toolOrder: ['zulu', TOOL_ORDER_REST],
       persistenceRoot: '/tmp/dsh-stdio-demo-spec-tool-order',

packages/fs/tool-fs/tests/fs-tools.e2e.ts

@@ -35,7 +35,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
     ctx = await fsHarness(workdir, SYSTEM)
     // agentLoop.create prepares a session with no cwd, so the provider default
     // (config.cwd = workdir) is the workspace.
-    const agent = ctx.agentLoop.create(AgentId('fs-e2e'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('fs-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text:
       'Create a file named note.txt containing exactly the line: status: draft. '
@@ -68,7 +68,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
         agentId: AgentId('fs-e2e-cwd'),
         sessionId: SessionId(`fs-e2e-cwd-${Date.now()}`),
         meta: { cwd: sessionDir },
-        agentOptions: { model: 'deepseek-v4-flash' },
+        agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
       })
       handle.agent.send([{ type: 'text', text:
         'Use the write tool to create a file named where.txt containing exactly the line: here. Tell me when done.' }])

packages/fs/tool-fs/tests/harness.ts

@@ -16,7 +16,7 @@ export async function fsHarness(fsCwd: string, persona = ''): Promise<Context> {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx, { systemPrompt: { persona } })
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await ctx.plugin(LlmDeepSeek)
   await ctx.plugin(LocalFileSystem, { cwd: fsCwd })
   await ctx.plugin(FsPolicy)
   await ctx.plugin(ToolFs)

packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts

@@ -53,7 +53,7 @@ describe('threshold escalation', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -74,7 +74,7 @@ describe('threshold escalation', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -96,7 +96,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -120,7 +120,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -138,7 +138,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -159,7 +159,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -175,7 +175,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -191,7 +191,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -211,8 +211,8 @@ describe('chain semantics', () => {
       toolCallResponse('b3', 'probe', { q: 1 }),
       textResponse('done'),
     ]))
-    const agentA = ctx.agentLoop.create(AgentId('a'), { model: 'mock-a' })
-    const agentB = ctx.agentLoop.create(AgentId('b'), { model: 'mock-b' })
+    const agentA = ctx.agentLoop.create(AgentId('a'), { provider: 'mock-a', model: 'model-a' })
+    const agentB = ctx.agentLoop.create(AgentId('b'), { provider: 'mock-b', model: 'model-b' })
     agentA.send([{ type: 'text', text: 'go' }])
     agentB.send([{ type: 'text', text: 'go' }])
     await Promise.all([waitForIdle(ctx, agentA), waitForIdle(ctx, agentB)])
@@ -231,7 +231,7 @@ describe('chain semantics', () => {
       textResponse('turn two done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     agent.send([{ type: 'text', text: 'again' }])
@@ -252,14 +252,14 @@ describe('chain semantics', () => {
     // (the loop.spec pattern): a child plugin fiber owns `first`.
     let first!: ReactLoopAgent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      first = inner.agentLoop.create(AgentId('reused'), { model: 'mock' })
+      first = inner.agentLoop.create(AgentId('reused'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     first.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, first)
     await fiber.dispose()
     await first.done
 
-    const second = ctx.agentLoop.create(AgentId('reused'), { model: 'mock' })
+    const second = ctx.agentLoop.create(AgentId('reused'), { provider: 'mock', model: 'mock' })
     second.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, second)
 
@@ -275,7 +275,7 @@ describe('chain semantics', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -291,7 +291,7 @@ describe('chain semantics', () => {
       toolCallResponse('c1', 'probe', { q: 1 }), // if the direct call had counted, this would be #2
       textResponse('done'),
     ]))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -313,7 +313,7 @@ describe('fold onto the downstream decision', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -344,7 +344,7 @@ describe('fold onto the downstream decision', () => {
       textResponse('done'),
     ])
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 

packages/hooks/hooks-claude/tests/bridge.spec.ts

@@ -87,7 +87,7 @@ describe('hooks-claude bridge — UserPromptSubmit', () => {
 
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'do something' }])
     await waitForIdle(ctx, agent)
 
@@ -110,7 +110,7 @@ describe('hooks-claude bridge — UserPromptSubmit', () => {
 
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -135,7 +135,7 @@ describe('hooks-claude bridge — PreToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineTool({ name: 'danger', description: 'd', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'use danger' }])
     await waitForIdle(ctx, agent)
 
@@ -158,7 +158,7 @@ describe('hooks-claude bridge — PreToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineTool({ name: 'safe', description: 's', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ran ok' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'use safe' }])
     await waitForIdle(ctx, agent)
 
@@ -180,7 +180,7 @@ describe('hooks-claude bridge — PostToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'raw output' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -200,7 +200,7 @@ describe('hooks-claude bridge — PostToolUse', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
     const ctx = await harness(dir, adapter)
     ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -224,7 +224,7 @@ describe('hooks-claude bridge — PostToolUse', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -248,7 +248,7 @@ describe('hooks-claude bridge — SessionStart', () => {
 
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     // session-start fires async (detached .then → agent.inject); wait for the
     // injected context/message to actually land before sending, rather than a
     // fixed sleep that flakes under load.
@@ -337,7 +337,7 @@ describe('hooks-claude bridge — load resilience', () => {
     await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
     await ctx.plugin(HooksClaude, { configPath: '/nonexistent/hooks.json' })
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     // The turn ran normally — no hooks, no crash.
@@ -356,7 +356,7 @@ describe('hooks-claude bridge — load resilience', () => {
     const fiber = await ctx.plugin(HooksClaude, { configPath: join(dir, 'hooks.json') })
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone

packages/hooks/hooks-claude/tests/coverage-cases.ts

@@ -65,7 +65,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
         const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
         const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
         ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-        const agent = ctx.agentLoop.create(AgentId('transcript'), { model: 'mock' })
+        const agent = ctx.agentLoop.create(AgentId('transcript'), { provider: 'mock', model: 'mock' })
         agent.send([{ type: 'text', text: 'go' }])
         await waitForIdle(ctx, agent)
         return {
@@ -95,7 +95,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter, { pluginRoot: d, projectDir: d })
       ctx.logger.warn = warn as never
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true) // substituted command ran
@@ -111,7 +111,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       ctx.logger.warn = warn as never
       let sawArgs: unknown
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: { command: { type: 'string' } }, async execute(args) { sawArgs = args; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // updatedInput is NOT honored — the tool ran with the ORIGINAL args.
@@ -127,7 +127,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ran')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // The prompt proceeded unchanged; no context/message injected.
@@ -157,7 +157,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -182,7 +182,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter, { stderrSummaryMaxChars: 40 })
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -198,7 +198,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2)
@@ -214,7 +214,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { Stop: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // A second model request ran → the empty-reason block forced continuation.
@@ -262,7 +262,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'x' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -276,7 +276,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -305,7 +305,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const turnEnd = events(agent).findLast(e => e.type === 'turn/end')
@@ -320,7 +320,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'x' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // ask (no reason) → degrades to deny with the registry's generic message.
@@ -335,7 +335,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -360,7 +360,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // the protocol lib's reference default, not a config knob).
       HooksClaude.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
@@ -375,7 +375,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
@@ -390,7 +390,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -409,7 +409,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -426,7 +426,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -446,7 +446,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // the mismatched deny was discarded → the tool ran
@@ -464,7 +464,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter) // NB: no projectDir
       // The factory create() path honors meta.cwd (the plain agentLoop.create() does not).
       const { SessionId } = await import('@deepseek-ai/dsh-session')
-      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: workspace }, agentOptions: { model: 'mock' } })
+      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: workspace }, agentOptions: { provider: 'mock', model: 'mock' } })
       handle.agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent as ReactLoopAgent)
       expect(events(handle.agent as ReactLoopAgent).some(e => e.type === 'context/message'
@@ -483,7 +483,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       // A later listener that blocks every prompt (registered AFTER the bridge).
       const { AgentId: AId } = await import('@deepseek-ai/dsh-agent')
       ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' }))
-      const agent = ctx.agentLoop.create(AId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       // the downstream block won: the model was never called, no user/message was
@@ -512,7 +512,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
           meta: { owner: 'policy' },
         }],
       }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
@@ -541,7 +541,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, content: [{ type: 'text' as const, text: 'rewritten-result' }] }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -565,7 +565,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
           meta: { owner: 'policy' },
         }],
       }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
 
@@ -589,7 +589,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const ctx = await harness(path, adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
@@ -613,7 +613,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const bash = ctx.bash
       bash.run = (() => Promise.reject(new Error('executor down')))
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
@@ -629,7 +629,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       // Make inject throw, forcing the SessionStart .catch path.
       const original = agent.inject.bind(agent)
       let threw = false
@@ -663,7 +663,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
 
       const { SessionId } = await import('@deepseek-ai/dsh-session')
-      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { model: 'mock' } })
+      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { provider: 'mock', model: 'mock' } })
       handle.agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent as ReactLoopAgent)
 
@@ -692,7 +692,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
 
       // Register a live child on its own session cwd; emit subagent/end with its id.
       const { SessionId } = await import('@deepseek-ai/dsh-session')
-      const childHandle = await ctx.agents.create({ agentId: AgentId('child-stop'), sessionId: SessionId('child-stop-session'), meta: { cwd: childDir }, agentOptions: { model: 'mock' } })
+      const childHandle = await ctx.agents.create({ agentId: AgentId('child-stop'), sessionId: SessionId('child-stop-session'), meta: { cwd: childDir }, agentOptions: { provider: 'mock', model: 'mock' } })
       ctx.emit('subagent/end', { provider: 'inproc', id: childHandle.agent.id, stopReason: 'completed' })
 
       await waitFor(() => existsSync(marker))
@@ -713,7 +713,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
@@ -731,7 +731,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
       const path = hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: s }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(path, adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       // Send immediately — do NOT wait for the session-start inject.
       agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, agent)

packages/hooks/hooks-codex/tests/bridge.spec.ts

@@ -76,7 +76,7 @@ describe('hooks-codex bridge', () => {
     const ctx = await harness(dir, adapter)
     let ran = false
     ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'no' }] } }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'run ls' }])
     await waitForIdle(ctx, agent)
 
@@ -97,7 +97,7 @@ describe('hooks-codex bridge', () => {
 
     const adapter = new MockAdapter([textResponse('first answer'), textResponse('second answer after goal')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
 
@@ -112,7 +112,7 @@ describe('hooks-codex bridge', () => {
 
     const adapter = new MockAdapter([textResponse('fine')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -122,7 +122,7 @@ describe('hooks-codex bridge', () => {
     const dir = configDir() // no hooks.json written
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(dir, adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1)
@@ -142,7 +142,7 @@ describe('hooks-codex bridge', () => {
     const fiber = await ctx.plugin(HooksCodex, { configPath: join(dir, 'hooks.json'), model: 'm' })
     await fiber.dispose()
     ctx.llm.registerAdapter(['mock'], adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(1) // not blocked → the listener is gone
@@ -165,7 +165,7 @@ describe('hooks-codex bridge', () => {
     ctx.llm.registerAdapter(['mock'], new MockAdapter([]))
     const warn = vi.fn()
     ctx.logger.warn = warn as never
-    ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) // fires agent/session-start
+    ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) // fires agent/session-start
     await waitFor(() => existsSync(marker))
     const pid = Number(readFileSync(pidFile, 'utf8').trim())
     await fiber.dispose()

packages/hooks/hooks-codex/tests/coverage-cases.ts

@@ -62,7 +62,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
         const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
         const ctx = await harness(path, adapter, { ...sessionRoot !== undefined ? { sessionRoot } : {} })
         ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-        const agent = ctx.agentLoop.create(AgentId('transcript'), { model: 'mock' })
+        const agent = ctx.agentLoop.create(AgentId('transcript'), { provider: 'mock', model: 'mock' })
         agent.send([{ type: 'text', text: 'go' }])
         await waitForIdle(ctx, agent)
         return {
@@ -81,7 +81,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', '#!/usr/bin/env bash\nexit 2\n') }] }] })
       const adapter = new MockAdapter([textResponse('no')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       const te = events(agent).findLast(e => e.type === 'turn/end')
@@ -93,7 +93,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"ctx-x"}}\'\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('ctx-x')
     })
@@ -106,7 +106,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('should not run')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy veto' }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(0)
       expect(events(agent).some(e => e.type === 'user/message')).toBe(false)
@@ -129,7 +129,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
           meta: { owner: 'policy' },
         }],
       }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const req = JSON.stringify(adapter.requests[0]!.messages)
       expect(req).toContain('from-bridge')
@@ -153,7 +153,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'accept' as const, content: [{ type: 'text' as const, text: 'rewritten-result' }] }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.content.some(b => b.type === 'text' && b.text === 'rewritten-result')).toBe(true)
@@ -175,7 +175,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
           meta: { owner: 'policy' },
         }],
       }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
 
       const contexts = events(agent).filter(event => event.type === 'context/message')
@@ -194,7 +194,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       ctx.on('tools/post-execute', async () => ({ kind: 'block' as const, feedback: [{ type: 'text' as const, text: 'downstream-block' }] }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const result = events(agent).find(e => e.type === 'tool/result')
       expect(result?.type === 'tool/result' && result.data.isError).toBe(true)
@@ -207,7 +207,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"start-ctx"}}\'\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => events(agent).some(e => e.type === 'context/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('start-ctx'))))
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
@@ -220,7 +220,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
@@ -233,7 +233,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('post-ctx')))).toBe(true)
     })
@@ -247,7 +247,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: {}, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // clean-exit hook allows; commandOf returned ''
     })
@@ -258,7 +258,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.exitCode).toBe(0)
@@ -271,7 +271,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary?.endsWith('…')).toBe(true)
@@ -294,7 +294,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter, { stderrSummaryMaxChars: 40 })
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.stderrSummary).toBe('x'.repeat(40) + '…')
@@ -317,7 +317,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       // Direct apply (schema bypass) → the `model ?? ''` fallback is exercised.
       HooksCodex.apply(ctx, { configPath: join(d, 'hooks.json') })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(existsSync(marker)).toBe(true)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('async hook'))
@@ -330,7 +330,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
@@ -344,7 +344,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', `#!/usr/bin/env bash\ntouch "${marker}"\nexit 0\n`) }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the clean no-output hook has finished
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(events(agent).some(e => e.type === 'context/message')).toBe(false)
@@ -356,7 +356,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.inject = (() => { throw new Error('inject boom') })
       await waitFor(() => warn.mock.calls.some(c => String(c[0]).includes('SessionStart hook failed')))
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('SessionStart hook failed'))
@@ -371,7 +371,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true)
     })
@@ -384,7 +384,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(true) // matcher didn't match → no hook ran → tool proceeded
       expect(events(agent).some(e => e.type === 'hook/invoked')).toBe(false)
@@ -400,7 +400,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && res.data.decision).toBe('stop') // recorded
@@ -413,7 +413,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.content.some(b => b.type === 'text' && b.text.includes('blocked by PreToolUse hook'))).toBe(true)
@@ -425,7 +425,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 'x' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const r = events(agent).find(e => e.type === 'tool/result')
       expect(r?.type === 'tool/result' && r.data.isError).toBe(true)
@@ -442,7 +442,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'Bash', { command: 7 }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'number' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_input: { command: string } }
       expect(payload.tool_input.command).toBe('')
@@ -478,7 +478,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.bash.run = (() => Promise.reject(new Error('executor down')))
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const res = events(agent).find(e => e.type === 'hook/result')
       expect(res?.type === 'hook/result' && 'exitCode' in res.data).toBe(false)
@@ -494,7 +494,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { Stop: [{ hooks: [{ type: 'command', command: sh(d, 's.sh', `#!/usr/bin/env bash\nif [ -e "${marker}" ]; then exit 0; fi\ntouch "${marker}"\nexit 2\n`) }] }] })
       const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(2) // empty-reason block forced continuation
       expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('blocked by Stop hook')
@@ -507,7 +507,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho "extra guidance from a plain hook"\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).toContain('extra guidance from a plain hook')
     })
@@ -521,7 +521,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 'b.sh', `#!/usr/bin/env bash\ntouch "${marker}"\necho "stale"\nexit 2\n`) }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => existsSync(marker)) // the exit-2 hook has finished
       expect(events(agent).some(e => e.type === 'context/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('stale')))).toBe(false)
@@ -535,7 +535,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'e.sh', '#!/usr/bin/env bash\necho "stale"\nexit 1\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(adapter.requests).toHaveLength(1) // exit 1 is non-blocking → the turn ran
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('stale')
@@ -546,7 +546,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { SessionStart: [{ hooks: [{ type: 'command', command: sh(d, 'ss.sh', '#!/usr/bin/env bash\necho "session preamble"\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       await waitFor(() => events(agent).some(e => e.type === 'context/message'
       && e.data.content.some(b => b.type === 'text' && b.text.includes('session preamble'))))
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
@@ -560,7 +560,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'j.sh', '#!/usr/bin/env bash\necho \'{"unrelated":"json"}\'\nexit 0\n') }] }] })
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('unrelated')
     })
@@ -575,7 +575,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([toolCallResponse('c1', 'shell', { command: 'ls' }), textResponse('done')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       ctx.tools.register(defineTool({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       const payload = JSON.parse(readFileSync(cap, 'utf8')) as { tool_name: string; tool_input: { command: string } }
       expect(payload.tool_name).toBe('shell')
@@ -591,7 +591,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       let ran = false
       ctx.tools.register(defineTool({ name: 'shell', description: 'b', parameters: { command: { type: 'string' } }, async execute() { ran = true; return [{ type: 'text', text: 'ok' }] } }))
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(ran).toBe(false) // the matcher fired → the hook denied the tool
       expect(events(agent).some(e => e.type === 'hook/invoked' && e.data.point === 'PreToolUse')).toBe(true)
@@ -603,7 +603,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       const adapter = new MockAdapter([textResponse('ok')])
       const ctx = await harness(join(d, 'hooks.json'), adapter)
       const warn = vi.fn(); ctx.logger.warn = warn as never
-      const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+      const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
       expect(warn).toHaveBeenCalledWith(expect.stringContaining('systemMessage'))
       expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('heads up')
@@ -626,7 +626,7 @@ export function defineCoverageCases(groups: CoverageGroup | readonly CoverageGro
       ctx.llm.registerAdapter(['mock'], adapter)
       ctx.tools.register(defineTool({ name: 'Bash', description: 'b', parameters: { command: { type: 'string' } }, async execute() { return [{ type: 'text', text: 'ok' }] } }))
       const { SessionId } = await import('@deepseek-ai/dsh-session')
-      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { model: 'mock' } })
+      const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), meta: { cwd: sessionDir }, agentOptions: { provider: 'mock', model: 'mock' } })
       handle.agent.send([{ type: 'text', text: 'go' }])
       await waitForIdle(ctx, handle.agent as ReactLoopAgent)
       expect(existsSync(marker)).toBe(true)

packages/llm/README.md

@@ -6,6 +6,6 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 |---|---|---|
 | `llm/` | Abstract LLM service + content-block vocabulary + chunk assembler | `ctx.llm` |
 | `llm-deepseek/` | DeepSeek API adapter (hand-rolled fetch/SSE) | (registers on `ctx.llm`) |
-| `llm-pi-ai/` | DeepSeek adapter via `@earendil-works/pi-ai` (design twin) | (registers on `ctx.llm`) |
+| `llm-pi-ai/` | Multi-provider adapter via `@earendil-works/pi-ai` | (registers on `ctx.llm`) |
 
-The interface lives at `llm/llm/`; adapters are flat siblings under the group. A new provider adapter joins here and registers on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for why two adapters exist.
+The interface lives at `llm/llm/`; adapters are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. A new provider adapter joins here and registers one or more provider routes on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations.

packages/llm/llm-deepseek/README.md

@@ -2,7 +2,7 @@
 
 DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch` + SSE translation from the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.
 
-A second, independent implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai` (library-backed). Same Config shape — pick one per context (registering both for the same model names throws by design).
+A second, library-backed implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai`. This package always owns the `deepseek` provider route; mounting a pi-ai profile with `provider: deepseek` in the same context throws `LlmError('DUPLICATE_ADAPTER')` by design.
 
 ## Config
 
@@ -12,12 +12,16 @@ A second, independent implementation of the same seam exists in `@deepseek-ai/ds
   config:
     apiKey: !!js process.env.DEEPSEEK_API_KEY    # or rely on the env fallback
     baseURL: !!js process.env.DEEPSEEK_BASE_URL  # default: https://api.deepseek.com
-    models: [deepseek-v4-flash, deepseek-v4-pro] # one adapter, registered for each name
     thinking: enabled        # optional; provider default is enabled
     reasoningEffort: high    # optional; high | max — omitted ⇒ not sent
+    models:                  # optional; defaults to V4 Flash and V4 Pro
+      - id: deepseek-v4-flash
+        name: DeepSeek V4 Flash
+      - id: private-reasoner
+        description: Company-hosted reasoning model
 ```
 
-`models` lists every model name this one adapter instance serves: the adapter registers itself for each (the harness model name IS the wire `model` string), so a `generate`/`stream` call routes to it whenever `options.model` is any of them. Registering a second adapter for a name already taken throws `LlmError('DUPLICATE_ADAPTER')` (the LLM service enforces one adapter per model, all-or-nothing).
+The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
 
 `reasoningEffort` is **omitted by default** — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).
 

packages/llm/llm-deepseek/src/adapter.ts

@@ -6,13 +6,23 @@
  */
 
 import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { serializeRequest } from './serialize.ts'
 import type { RequestDefaults } from './serialize.ts'
 import { parseSse } from './sse.ts'
 import { translate } from './translate.ts'
 import type { WireError } from './types.ts'
 
+/** One optional model entry advertised by the hand-written adapter. */
+export interface DeepSeekCatalogModel {
+  /** Wire model id accepted by the configured endpoint. */
+  id: string
+  /** Selector label; defaults to {@link id}. */
+  name?: string
+  /** Optional selector detail for deployments with similar model variants. */
+  description?: string
+}
+
 /** Constructor options for {@link DeepSeekAdapter}; the plugin's `apply` resolves them from Config + environment. */
 export interface DeepSeekAdapterOptions {
   /** Bearer token sent in the `authorization` header on every request. */
@@ -21,6 +31,8 @@ export interface DeepSeekAdapterOptions {
   baseURL: string
   /** Request defaults applied to every call (thinking mode, effort). */
   defaults?: RequestDefaults
+  /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
+  models?: readonly DeepSeekCatalogModel[]
 }
 
 /**
@@ -49,6 +61,19 @@ export class DeepSeekAdapter extends LlmAdapter {
     super()
   }
 
+  override providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: 'DeepSeek' }
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve((this.options.models ?? []).map(model => ({
+      provider,
+      id: model.id,
+      name: model.name ?? model.id,
+      ...model.description === undefined ? {} : { description: model.description },
+    })))
+  }
+
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     const body = serializeRequest(options, this.options.defaults ?? {})
 

packages/llm/llm-deepseek/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * Register a {@link DeepSeekAdapter} for configured model names on `ctx.llm`. Configuration uses
+ * Register a {@link DeepSeekAdapter} for the `deepseek` provider route on `ctx.llm`. Configuration uses
  * Cordis schemastery; pass secrets from environment variables through `cordis.yml` with `!!js`,
  * as shown in the package README, rather than reading ad hoc files.
  * @module @deepseek-ai/dsh-llm-deepseek
@@ -9,9 +9,10 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-llm'
 import { DeepSeekAdapter } from './adapter.ts'
+import type { DeepSeekCatalogModel } from './adapter.ts'
 
 export { DeepSeekAdapter, httpErrorCode } from './adapter.ts'
-export type { DeepSeekAdapterOptions } from './adapter.ts'
+export type { DeepSeekAdapterOptions, DeepSeekCatalogModel } from './adapter.ts'
 export { serializeMessages, serializeRequest } from './serialize.ts'
 export type { RequestDefaults } from './serialize.ts'
 export { DONE, parseSse } from './sse.ts'
@@ -21,6 +22,11 @@ export type * from './types.ts'
 export const name = 'llm-deepseek'
 export const inject = ['llm']
 
+const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
+  { id: 'deepseek-v4-flash' },
+  { id: 'deepseek-v4-pro' },
+]
+
 /**
  * Plugin config, validated by the same-named schemastery schema. Every field
  * is optional in yml: credentials/endpoint fall back to the environment (a
@@ -32,40 +38,62 @@ export interface Config {
   apiKey?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
   baseURL?: string
-  /** Model names to register (sent verbatim on the wire). */
-  models?: string[]
   /** Thinking-mode default for every request (provider default: enabled). */
   thinking?: 'enabled' | 'disabled'
   /** Thinking effort (only meaningful with thinking enabled). */
   reasoningEffort?: 'high' | 'max'
+  /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
+  models?: DeepSeekCatalogModel[]
 }
 
+const catalogModel: z<DeepSeekCatalogModel> = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  description: z.string(),
+})
+
 export const Config: z<Config> = z.object({
   apiKey: z.string(),
   baseURL: z.string(),
-  models: z.array(z.string()).default(['deepseek-v4-flash', 'deepseek-v4-pro']),
   thinking: z.union(['enabled', 'disabled']),
   reasoningEffort: z.union(['high', 'max']),
+  models: z.array(catalogModel).default(DEFAULT_MODELS),
 })
 
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
 export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
 
+/** Resolve, validate, and detach the advisory model catalog. */
+function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): DeepSeekCatalogModel[] {
+  const seen = new Set<string>()
+  return (models ?? DEFAULT_MODELS).map((model) => {
+    if (model.id.length === 0) throw new Error('llm-deepseek: catalog model ids must be non-empty')
+    if (model.name !== undefined && model.name.length === 0) {
+      throw new Error(`llm-deepseek: catalog model "${model.id}" has an empty name`)
+    }
+    if (seen.has(model.id)) throw new Error(`llm-deepseek: duplicate catalog model "${model.id}"`)
+    seen.add(model.id)
+    return {
+      id: model.id,
+      ...model.name === undefined ? {} : { name: model.name },
+      ...model.description === undefined ? {} : { description: model.description },
+    }
+  })
+}
+
 export function apply(ctx: Context, config: Config): void {
   const apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY
   if (apiKey === undefined || apiKey.length === 0) {
     throw new Error('llm-deepseek: an API key is required (Config.apiKey or $DEEPSEEK_API_KEY)')
   }
   const baseURL = config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL
-  // schemastery's .default() guarantees models is set after validation.
-  const models = config.models as string[]
-
-  ctx.llm.registerAdapter(models, new DeepSeekAdapter({
+  ctx.llm.registerAdapter(['deepseek'], new DeepSeekAdapter({
     apiKey,
     baseURL,
     defaults: {
       thinking: config.thinking,
       reasoningEffort: config.reasoningEffort,
     },
+    models: resolveModels(config.models),
   }))
 }

packages/llm/llm-deepseek/tests/adapter.e2e.ts

@@ -16,11 +16,11 @@ const FLASH = 'deepseek-v4-flash'
 const PRO = 'deepseek-v4-pro'
 const contexts: Context[] = []
 
-async function harness(model: string, config: Partial<Config> = {}) {
+async function harness(_model: string, config: Partial<Config> = {}) {
   const ctx = new Context()
   contexts.push(ctx)
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmDeepSeek, { models: [model], ...config })
+  await ctx.plugin(LlmDeepSeek, config)
   return ctx
 }
 
@@ -134,6 +134,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', ()
     const ctx = await harness(FLASH, { thinking: 'disabled' })
     const kinds: string[] = []
     for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek',
       model: FLASH,
       messages: ask('Count from 1 to 5, digits only.'),
       maxTokens: 50,

packages/llm/llm-deepseek/tests/adapter.spec.ts

@@ -86,7 +86,7 @@ const textEvents = [
 async function harness(baseURL: string, config: object = {}) {
   const ctx = new Context()
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmDeepSeek, { apiKey: 'test-key', baseURL, models: ['deepseek-v4-flash'], ...config })
+  await ctx.plugin(LlmDeepSeek, { apiKey: 'test-key', baseURL, ...config })
   return ctx
 }
 
@@ -123,6 +123,7 @@ describe('DeepSeekAdapter against a mock server', () => {
 
     const kinds: string[] = []
     for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek',
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
     })) {
@@ -198,7 +199,7 @@ describe('DeepSeekAdapter against a mock server', () => {
     )
     try {
       const iterate = async (): Promise<void> => {
-        for await (const _chunk of adapter.stream({ model: 'm', messages: [] })) { /* drain */ }
+        for await (const _chunk of adapter.stream({ provider: 'deepseek', model: 'm', messages: [] })) { /* drain */ }
       }
       await expect(iterate()).rejects.toThrow(/no response body/)
     } finally {
@@ -224,6 +225,7 @@ describe('DeepSeekAdapter against a mock server', () => {
     const pending = (async () => {
       const chunks = []
       for await (const chunk of ctx.llm.stream({
+        provider: 'deepseek',
         model: 'deepseek-v4-flash',
         messages: [],
         signal: controller.signal,
@@ -239,25 +241,81 @@ describe('DeepSeekAdapter against a mock server', () => {
 })
 
 describe('plugin registration and config', () => {
-  it('registers the configured models and unregisters on dispose (HMR safety)', async () => {
+  it('registers the deepseek provider and unregisters on dispose (HMR safety)', async () => {
     const server = await mockServer([])
     const ctx = new Context()
     await ctx.plugin(LlmService)
     const fiber = await ctx.plugin(LlmDeepSeek, {
       apiKey: 'k',
       baseURL: server.url,
-      models: ['deepseek-v4-flash', 'deepseek-v4-pro'],
     })
-    expect(ctx.llm.models().sort()).toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
     await fiber.dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
-  it('defaults the model list', async () => {
+  it('owns the deepseek provider and advertises the default models', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
-    expect(ctx.llm.models().sort()).toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+    ])
+  })
+
+  it('uses the default model catalog when apply is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    LlmDeepSeek.apply(ctx, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
+      { provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
+    ])
+  })
+
+  it('advertises configured models without restricting arbitrary request ids', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [
+        { id: 'private-fast' },
+        { id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
+      ],
+    })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
+      { provider: 'deepseek', id: 'private-fast', name: 'private-fast' },
+      { provider: 'deepseek', id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
+    ])
+  })
+
+  it('allows an explicit empty model catalog', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [],
+    })
+    await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([])
+  })
+
+  it.each([
+    [[{ id: '' }], /ids must be non-empty/],
+    [[{ id: 'm', name: '' }], /empty name/],
+    [[{ id: 'm' }, { id: 'm' }], /duplicate catalog model/],
+  ] as const)('rejects invalid advisory model config', async (models, message) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      apiKey: 'k',
+      baseURL: 'http://127.0.0.1:1',
+      models: [...models],
+    })).rejects.toThrow(message)
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
   it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
@@ -266,7 +324,7 @@ describe('plugin registration and config', () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(LlmDeepSeek, {})
-    expect(ctx.llm.models().length).toBeGreaterThan(0)
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
   })
 
   it('throws a clear error when no API key is available', async () => {
@@ -275,7 +333,7 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     await expect(ctx.plugin(LlmDeepSeek, {}))
       .rejects.toThrow(/an API key is required/)
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
   it('prefers explicit config over env for key and base URL', async () => {
@@ -292,7 +350,7 @@ describe('plugin registration and config', () => {
     vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    await ctx.plugin(LlmDeepSeek, { apiKey: 'k', models: ['deepseek-v4-flash'] })
+    await ctx.plugin(LlmDeepSeek, { apiKey: 'k' })
     await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(server.requests).toHaveLength(1)
   })
@@ -304,11 +362,12 @@ describe('plugin registration and config', () => {
     await ctx.plugin(LlmService)
     // Registration succeeds; no call is made (would hit api.deepseek.com).
     await ctx.plugin(LlmDeepSeek, {})
-    expect(ctx.llm.models().length).toBeGreaterThan(0)
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek', name: 'DeepSeek' }])
   })
 
-  it('adapter is constructible directly for embedding', () => {
+  it('adapter is constructible directly for embedding', async () => {
     const adapter = new DeepSeekAdapter({ apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
     expect(adapter).toBeInstanceOf(DeepSeekAdapter)
+    await expect(adapter.listModels('deepseek')).resolves.toEqual([])
   })
 })

packages/llm/llm-deepseek/tests/assemble.ts

@@ -15,11 +15,19 @@ export interface AssembledResult {
   finish: FinishReason
 }
 
-export async function assemble(ctx: Context, options: GenerateOptions): Promise<AssembledResult> {
+export async function assemble(ctx: Context, options: Omit<GenerateOptions, 'provider'> & { provider?: string }): Promise<AssembledResult> {
   const assembler = new BlockAssembler()
-  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  const request = { provider: 'deepseek', ...options }
+  for await (const chunk of ctx.llm.stream(request)) assembler.push(chunk)
   return {
-    message: assembler.message(),
+    message: {
+      ...assembler.message(),
+      provenance: {
+        provider: request.provider,
+        model: request.model,
+        ...assembler.replayState === undefined ? {} : { replayState: assembler.replayState },
+      },
+    },
     ...assembler.usage !== undefined ? { usage: assembler.usage } : {},
     finish: assembler.finish,
   }

packages/llm/llm-deepseek/tests/serialize.spec.ts

@@ -4,7 +4,7 @@ import type { ContentBlock, GenerateOptions, Message } from '@deepseek-ai/dsh-ll
 import { serializeMessages, serializeRequest } from '@deepseek-ai/dsh-llm-deepseek'
 
 function request(overrides: Partial<GenerateOptions> = {}): GenerateOptions {
-  return { model: 'deepseek-v4-flash', messages: [], ...overrides }
+  return { provider: 'deepseek', model: 'deepseek-v4-flash', messages: [], ...overrides }
 }
 
 describe('serializeMessages', () => {

packages/llm/llm-pi-ai/README.md

@@ -1,60 +1,79 @@
 # @deepseek-ai/dsh-llm-pi-ai
 
-DeepSeek adapter for the harness LLM seam backed by [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) (the LLM library behind the pi agent).
-
-## Why a second adapter exists
-
-`@deepseek-ai/dsh-llm-deepseek` already talks to the same endpoint. This package is its **design-verification twin**: same models, same wire protocol, completely different internals — a unified LLM library with its own event vocabulary versus hand-rolled fetch/SSE. Anything the harness `StreamChunk` protocol cannot express for BOTH implementations is a core-vocabulary bug. The differences it exercised on purpose:
-
-- pi-ai hands tool-call `arguments` around as **parsed objects**; the harness keeps raw JSON strings. The adapter patches replay payloads back to the original raw strings before sending them, and re-stringifies parsed output tool calls at `block-end`.
-- pi-ai reports failures as **in-stream error events** (it never throws mid-stream); these map to `finish {kind:'error'|'aborted'}` chunks — the protocol's other sanctioned error path besides throwing (which llm-deepseek uses).
-- pi-ai folds reasoning tokens into `usage.output`; there is no separate reasoning count to map.
-- pi-ai's options omit some DeepSeek/OpenAI-compatible details; the adapter uses its `onPayload` hook to preserve the harness contract (`stop`, scrubbing pi-ai's own per-tool `strict` default — the hand-rolled twin sends no such field — omitted reasoning effort, raw replayed tool arguments).
+Generic multi-provider adapter for the harness LLM seam backed by [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai). One plugin instance owns an explicit list of provider profiles; every request selects a profile with `GenerateOptions.provider` and resolves `GenerateOptions.model` dynamically from pi-ai's installed catalog.
 
 ## Config
 
-Same shape as llm-deepseek (one-line swap in cordis.yml), with pi-ai's thinking-level vocabulary:
+Configure credentials and deployment-specific transport settings per provider. Omitting `apiKey` delegates authentication to pi-ai's provider-native ambient discovery. `baseURL` overrides only the endpoint of the selected catalog model, preserving its API family and compatibility metadata, so private proxies such as `https://proxy.example.com:8443` remain supported.
 
 ```yaml
 - id: llm
   name: '@deepseek-ai/dsh-llm-pi-ai'
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-    models: [deepseek-v4-flash, deepseek-v4-pro]
-    reasoning: high   # off | high | xhigh (xhigh → wire 'max')
+    providers:
+      - provider: openai
+        apiKey: !!js process.env.OPENAI_API_KEY
+        baseURL: https://proxy.example.com:8443
+        reasoning: high
+      - provider: anthropic
+        apiKey: !!js process.env.ANTHROPIC_API_KEY
+        maxRetries: 2
+      - provider: openrouter
+        apiKey: !!js process.env.OPENROUTER_API_KEY
+        headers:
+          X-Deployment: production
 ```
 
+Each provider name must exist in pi-ai's installed catalog and may appear only once in this plugin instance. Registration with `ctx.llm` is atomic: a collision with any provider route already owned by another adapter fails plugin loading without registering the remaining routes. Model ids are not lifecycle config; an unknown model fails before any provider request with `LlmError('UNKNOWN_MODEL')`.
+
+The adapter exposes each configured provider's installed pi-ai models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata derived from `getModels(provider)`; request-time resolution still performs the authoritative catalog lookup, so discovery does not create a second model registry.
+
+Supported profile fields are `provider`, `apiKey`, `baseURL`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `maxRetries`, and `maxRetryDelayMs`. They map to pi-ai's common stream options. Harness app attribution wins a conflicting configured header name.
+
+## Provider/model routing and replay
+
+The selected pi-ai catalog descriptor supplies the protocol implementation. This includes native API differences such as OpenAI models whose descriptor uses the Responses API rather than Chat Completions; the harness adapter does not hardcode endpoint selection by model name.
+
+Successful assistant responses store a versioned, lossless-JSON replay state beside their durable provider/model provenance. At request time, `LlmService` passes replay state only when the historical provider route and target provider route are currently owned by this same `PiAiAdapter` instance. The adapter validates the state and restores pi-ai response ids and provider signatures even when the target provider or model changes; pi-ai then decides which metadata its target API can reuse. History without replay state is translated as foreign provider-neutral content and never impersonates a native pi-ai response.
+
+If a listener rewrites assembled assistant content, the loop drops replay state before logging the message because its provider metadata no longer describes the content. Invalid versions, malformed metadata, provenance provider/model mismatches, and content/block mismatches fail explicitly with `LlmError('INVALID_REPLAY_STATE')`.
+
+## Vocabulary differences
+
+- pi-ai tool-call arguments are parsed objects; the harness stores raw JSON strings. The adapter parses input and re-stringifies output.
+- pi-ai reports failures as in-stream error events; these map to `finish {kind:'error'|'aborted'}` chunks.
+- pi-ai folds reasoning tokens into output usage; there is no separate reasoning count to map.
+- `GenerateOptions.stop` is rejected with `UNSUPPORTED_OPTION` because pi-ai's common streaming surface cannot guarantee it across providers.
+
 ## App attribution
 
-Every request carries the shared attribution header from dsh-llm's `attributionHeaders()`, passed through pi-ai's `headers` stream option (pi-ai merges caller headers last, so it always reaches the wire - the unit suite asserts arrival on the mock server, same as llm-deepseek). OpenRouter-specific app attribution headers are intentionally not sent by this adapter contract; they are deferred to a future explicit OpenRouter adapter or mode. See [dsh-llm § App attribution](../llm/README.md#app-attribution-attributionts).
+Every request carries the shared attribution header from dsh-llm's `attributionHeaders()`, merged through pi-ai's `headers` stream option. Provider-specific app-attribution headers are not synthesized. See [dsh-llm § App attribution](../llm/README.md#app-attribution-attributionts).
 
 ## Dependency weight
 
-pi-ai declares the openai/anthropic/google/mistral/AWS SDKs as install-time dependencies. They are lazy-loaded — only the openai SDK actually loads for this adapter — but they do land in `node_modules`. Accepted for a package whose purpose is design verification.
+pi-ai installs several provider SDKs and lazy-loads the one selected by the catalog model. The dependency weight is isolated to this opt-in adapter package.
 
 ## Testing
 
-Unit suites run against a local `node:http` mock SSE server (pi-ai's openai SDK happily talks to any base URL). Real-API coverage in `tests/adapter.e2e.ts` (`pnpm run test:e2e`, key-gated): V4 Flash + V4 Pro across all exposed reasoning levels (off/high/xhigh), the thinking+tools round trip, and a cross-adapter structural-equivalence check against llm-deepseek.
+Unit tests use pi-ai catalog models redirected to local mock servers and cover provider/profile routing, native API selection, endpoint overrides, attribution, conversion, replay-state validation, and cross-provider/model replay within one adapter instance. Real-API coverage remains key-gated under `pnpm run test:e2e`.
 
 ## Model Experience
 
-### DeepSeek request through pi-ai
+### Provider request through pi-ai
 
-**What the model sees**: The selected model receives the same logical system prompt, history, tools, stop sequences, and raw replayed tool arguments as the hand-written adapter. This package adds no prompt prose and removes pi-ai's own per-tool `strict` default to preserve that contract.
+**What the model sees**: The selected catalog model receives `GenerateOptions.system`, history, tools, and sampling fields supported by pi-ai's common streaming API. This package adds no prompt prose. Provider-native replay metadata is restored only when the adapter validates it for the historical content.
 
-**Token effect**: Provider tokenization governs exact input. Reasoning level changes generated and passback content; pi-ai reports reasoning inside output usage rather than as a separate count.
+**Token effect**: Provider tokenization governs exact input. Conversion adds no model-visible text; replay metadata may let a native API reuse provider-side state.
 
-### DeepSeek response
+### Provider response
 
-**What the model sees**: pi-ai events become harness reasoning, text, tool-call, usage, and finish chunks; parsed tool arguments are restored to raw JSON strings at the harness boundary.
+**What the model sees**: pi-ai events become harness reasoning, text, tool-call, usage, and finish chunks. Parsed tool arguments cross the harness boundary as raw JSON strings.
 
-**Token effect**: Generated content affects later inputs only after the loop records it; adapter conversion adds no model-visible text.
+**Token effect**: Generated content affects later inputs only after the loop records it. pi-ai folds reasoning tokens into output usage when the provider does not report them separately.
 
 ## Known Limitations and Deferred Work
 
-- **`tool_choice` is not mapped** — same MVP contract as llm-deepseek.
-- **In-history `system`-role messages fold into `user`-role wire messages** — pi-ai exposes a single `systemPrompt` slot, diverging from the hand-rolled twin's `role: 'system'` passthrough.
-- **`LlmError.status` is never set** — pi-ai reports failures as in-stream events with no HTTP status, so error codes are regex-classified from the error text.
-- **`buildModel` hardcodes descriptor metadata** — `contextWindow: 128000`, `maxTokens: 64000`, zero cost, identically for every registered model name; not configurable.
-- **pi-ai's built-in retries are disabled (`maxRetries: 0`)** — failures surface immediately; retry policy belongs to `llm/stream` listeners.
+- **Catalog membership is required** — custom model ids that are absent from the installed pi-ai catalog fail with `UNKNOWN_MODEL`, even when a provider profile supplies a custom endpoint.
+- **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
+- **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
+- **`LlmError.status` is unavailable for in-stream failures** — pi-ai error events do not expose a stable HTTP status across providers.

packages/llm/llm-pi-ai/src/adapter.ts

@@ -1,147 +1,101 @@
 /**
- * Pi-ai-backed DeepSeek adapter and design twin of the hand-rolled adapter.
- * Both implementations must fit the same provider-neutral stream vocabulary.
+ * Generic pi-ai-backed implementation of the Harness LLM seam.
+ *
  * @module dsh-llm-pi-ai/adapter
  */
 
-import { stream as piStream } from '@earendil-works/pi-ai'
-import type { Model } from '@earendil-works/pi-ai'
-import { attributionHeaders, LlmAdapter } from '@deepseek-ai/dsh-llm'
-import { CallId } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { toPiContext, toStreamChunks } from './convert.ts'
+import {
+  getModels,
+  streamSimple,
+} from '@earendil-works/pi-ai'
+import type {
+  Api,
+  KnownProvider,
+  Model,
+  SimpleStreamOptions,
+} from '@earendil-works/pi-ai'
+import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { PiAiProviderProfile } from './config.ts'
+import { toPiContext } from './context.ts'
+import { toStreamChunks } from './stream.ts'
 
-/** Reasoning levels surfaced by this adapter (DeepSeek wire: high|max). */
-export type PiAiReasoning = 'off' | 'high' | 'xhigh'
-
-/** Constructor options for {@link PiAiAdapter}; the plugin's `apply` resolves them from Config + environment. */
+/** Constructor options for {@link PiAiAdapter}. */
 export interface PiAiAdapterOptions {
-  /** Bearer token pi-ai sends on every request. */
-  apiKey: string
-  /** Endpoint base; `/chat/completions` is appended. */
-  baseURL: string
-  /** Thinking level applied to every request ('off' disables thinking). */
-  reasoning?: PiAiReasoning | undefined
+  /** Validated provider profiles this adapter instance owns. */
+  profiles: readonly PiAiProviderProfile[]
 }
 
 /**
- * Build the inline pi-ai model descriptor for one DeepSeek model name.
- * @param modelId - harness model name; sent verbatim on the wire.
- * @param options - adapter options; only `baseURL` is read here (key and reasoning apply per request, not per descriptor).
- * @returns a descriptor with every DeepSeek compat flag explicit — pi-ai's URL-based auto-detection is never relied on.
+ * Resolve a catalog model dynamically and apply only the configured endpoint
+ * override, preserving the catalog's API/capability/compatibility metadata.
  */
-export function buildModel(modelId: string, options: PiAiAdapterOptions): Model<'openai-completions'> {
+function resolveModel(profile: PiAiProviderProfile, modelId: string): Model<Api> {
+  const model = getModels(profile.provider as KnownProvider).find(candidate => candidate.id === modelId) as Model<Api> | undefined
+  if (model === undefined) {
+    throw new LlmError(`pi-ai provider "${profile.provider}" has no catalog model "${modelId}"`, 'UNKNOWN_MODEL')
+  }
+  return profile.baseURL === undefined ? model : { ...model, baseUrl: profile.baseURL }
+}
+
+/** Copy profile stream knobs into pi-ai's common option vocabulary. */
+function profileOptions(profile: PiAiProviderProfile): SimpleStreamOptions {
   return {
-    id: modelId,
-    name: modelId,
-    api: 'openai-completions',
-    provider: 'deepseek',
-    baseUrl: options.baseURL,
-    // Keep reasoning support enabled so `off` can send DeepSeek's explicit
-    // disabled marker rather than falling back to the provider's enabled default.
-    reasoning: true,
-    // DeepSeek's official effort levels: high|max (xhigh maps to max).
-    thinkingLevelMap: { minimal: null, low: null, medium: null, high: 'high', xhigh: 'max' },
-    input: ['text'],
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 128_000,
-    maxTokens: 64_000,
-    compat: {
-      // Auto-detection only fires for *.deepseek.com base URLs; the internal
-      // endpoint (and test mocks) need these set explicitly.
-      thinkingFormat: 'deepseek',
-      requiresReasoningContentOnAssistantMessages: true,
-      supportsReasoningEffort: true,
-      // DeepSeek documents max_tokens (not OpenAI's max_completion_tokens).
-      maxTokensField: 'max_tokens',
-    },
+    ...profile.apiKey === undefined ? {} : { apiKey: profile.apiKey },
+    ...profile.reasoning === undefined ? {} : { reasoning: profile.reasoning },
+    ...profile.thinkingBudgets === undefined ? {} : { thinkingBudgets: profile.thinkingBudgets },
+    ...profile.cacheRetention === undefined ? {} : { cacheRetention: profile.cacheRetention },
+    ...profile.transport === undefined ? {} : { transport: profile.transport },
+    ...profile.timeoutMs === undefined ? {} : { timeoutMs: profile.timeoutMs },
+    ...profile.websocketConnectTimeoutMs === undefined ? {} : { websocketConnectTimeoutMs: profile.websocketConnectTimeoutMs },
+    ...profile.maxRetries === undefined ? {} : { maxRetries: profile.maxRetries },
+    ...profile.maxRetryDelayMs === undefined ? {} : { maxRetryDelayMs: profile.maxRetryDelayMs },
   }
 }
 
-type Payload = {
-  tools?: { function?: { strict?: unknown } }[]
-  messages?: {
-    role?: unknown
-    tool_calls?: { id?: unknown; function?: { arguments?: unknown } }[]
-  }[]
-  reasoning_effort?: unknown
-  stop?: unknown
-}
-
-function rawToolArguments(options: GenerateOptions): Map<CallId, string> {
-  const raw = new Map<CallId, string>()
-  for (const message of options.messages) {
-    if (message.role !== 'assistant') continue
-    for (const block of message.content) {
-      if (block.type === 'tool-call') raw.set(block.id, block.arguments)
-    }
+/** Merge deployment headers while removing case-insensitive attribution collisions. */
+function requestHeaders(headers: Readonly<Record<string, string>> | undefined): Record<string, string> {
+  const attribution = attributionHeaders()
+  const reserved = new Set(Object.keys(attribution).map(name => name.toLowerCase()))
+  return {
+    ...Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => !reserved.has(name.toLowerCase()))),
+    ...attribution,
   }
-  return raw
-}
-
-function patchPayload(payload: unknown, options: GenerateOptions, reasoning: PiAiReasoning | undefined): unknown {
-  /* v8 ignore next -- pi-ai onPayload always receives an object; tolerate unusual future hooks defensively */
-  if (typeof payload !== 'object' || payload === null) return payload
-  const body = payload as Payload
-
-  if (reasoning === undefined) {
-    delete body.reasoning_effort
-  }
-  if (options.stop !== undefined) {
-    body.stop = options.stop
-  }
-
-  // pi-ai stamps its own `strict` default on every serialized tool; the
-  // harness tool contract has no strict field and the hand-rolled twin sends
-  // none, so scrub it for wire parity.
-  for (const tool of body.tools ?? []) {
-    /* v8 ignore next -- malformed pi-ai payload guard: real tool entries always carry function */
-    if (tool.function === undefined) continue
-    delete tool.function.strict
-  }
-
-  const rawById = rawToolArguments(options)
-  /* v8 ignore next -- defensive for non-chat payloads; OpenAI chat payloads always carry messages */
-  for (const message of body.messages ?? []) {
-    if (message.role !== 'assistant') continue
-    /* v8 ignore next -- assistant messages without tool_calls need no raw-argument patch */
-    for (const call of message.tool_calls ?? []) {
-      /* v8 ignore next -- malformed pi-ai payload guard: real tool calls always carry a string id */
-      if (typeof call.id !== 'string') continue
-      const raw = rawById.get(CallId(call.id))
-      /* v8 ignore next -- pi-ai always emits a function object for assistant tool_calls; guard malformed payloads defensively */
-      if (raw !== undefined && call.function !== undefined) call.function.arguments = raw
-    }
-  }
-
-  return body
 }
 
 /**
- * pi-ai-backed adapter. One instance serves every registered model name.
- *
- * Implementation notes:
- * - `onPayload` patches provider payload details pi-ai cannot express directly:
- *   stop sequences, scrubbing pi-ai's own per-tool `strict` default (the
- *   hand-rolled twin sends no such field), omitted reasoning effort, and raw
- *   replayed tool-call arguments.
- * - pi-ai reports request failures as in-stream error events; convert.ts
- *   maps them to `finish {kind:'error'|'aborted'}` chunks rather than
- *   throwing — both are sanctioned StreamChunk error paths.
+ * pi-ai-backed multi-provider adapter. Model descriptors are resolved for each
+ * request, so models need not be registered during the Cordis lifecycle.
  */
 export class PiAiAdapter extends LlmAdapter {
-  constructor(private readonly options: PiAiAdapterOptions) {
+  private readonly profiles: ReadonlyMap<string, PiAiProviderProfile>
+
+  constructor(options: PiAiAdapterOptions) {
     super()
+    this.profiles = new Map(options.profiles.map(profile => [profile.provider, profile]))
+  }
+
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    const profile = this.profiles.get(provider)
+    if (profile === undefined) {
+      return Promise.reject(new LlmError(`pi-ai adapter does not own provider "${provider}"`, 'NO_ADAPTER'))
+    }
+    return Promise.resolve(getModels(profile.provider as KnownProvider).map(model => ({
+      provider,
+      id: model.id,
+      name: model.name,
+    })))
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const model = buildModel(options.model, this.options)
-    // Undefined config means "provider default" (DeepSeek: thinking ENABLED),
-    // matching llm-deepseek's omission semantics. pi-ai derives the wire
-    // thinking toggle from whether reasoningEffort is passed, so undefined maps
-    // internally to 'high' to get `thinking: enabled`; patchPayload then removes
-    // `reasoning_effort` so the provider chooses its default effort.
-    const reasoning = this.options.reasoning ?? 'high'
+    if (options.stop !== undefined) {
+      throw new LlmError('llm-pi-ai does not support GenerateOptions.stop', 'UNSUPPORTED_OPTION')
+    }
+    const profile = this.profiles.get(options.provider)
+    if (profile === undefined) {
+      throw new LlmError(`pi-ai adapter does not own provider "${options.provider}"`, 'NO_ADAPTER')
+    }
+    const model = resolveModel(profile, options.model)
 
     // Pi-ai has no iterator-return cancellation hook. Chain an internal signal
     // and abort it when this generator exits so early consumers stop the HTTP stream.
@@ -151,19 +105,16 @@ export class PiAiAdapter extends LlmAdapter {
     else options.signal?.addEventListener('abort', onCallerAbort, { once: true })
 
     try {
-      const events = piStream(model, toPiContext(options), {
-        apiKey: this.options.apiKey,
-        // pi-ai merges caller headers last over its provider defaults, so the
-        // harness attribution always reaches the wire.
-        headers: attributionHeaders(),
-        ...options.temperature !== undefined ? { temperature: options.temperature } : {},
-        ...options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {},
+      const events = streamSimple(model, toPiContext(options), {
+        ...profileOptions(profile),
+        ...options.temperature === undefined ? {} : { temperature: options.temperature },
+        ...options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens },
+        ...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },
         signal: controller.signal,
-        ...reasoning !== 'off' ? { reasoningEffort: reasoning } : {},
-        onPayload: payload => patchPayload(payload, options, this.options.reasoning),
-        maxRetries: 0,
+        // Profile headers are deployment-owned; attribution names are
+        // Harness-owned and therefore win collisions.
+        headers: requestHeaders(profile.headers),
       })
-
       yield* toStreamChunks(events)
     } finally {
       options.signal?.removeEventListener('abort', onCallerAbort)

packages/llm/llm-pi-ai/src/config.ts

@@ -0,0 +1,99 @@
+/**
+ * Configuration schema and provider-profile validation for the pi-ai adapter.
+ *
+ * @module dsh-llm-pi-ai/config
+ */
+
+import { getProviders } from '@earendil-works/pi-ai'
+import type { CacheRetention, ThinkingBudgets, ThinkingLevel, Transport } from '@earendil-works/pi-ai'
+import z from 'schemastery'
+
+/** Configuration for one pi-ai provider route. */
+export interface PiAiProviderProfile {
+  /** pi-ai provider catalog name and Harness route key. */
+  provider: string
+  /** Provider credential; when absent pi-ai uses its provider-native ambient discovery. */
+  apiKey?: string
+  /** Override the selected catalog model's endpoint without changing its protocol metadata. */
+  baseURL?: string
+  /** Provider request headers; Harness attribution wins reserved names. */
+  headers?: Record<string, string>
+  /** Provider-neutral pi-ai reasoning level. */
+  reasoning?: ThinkingLevel
+  /** Token budgets used by reasoning providers that support them. */
+  thinkingBudgets?: ThinkingBudgets
+  /** Prompt-cache retention preference. */
+  cacheRetention?: CacheRetention
+  /** Streaming transport preference. */
+  transport?: Transport
+  /** HTTP/provider SDK timeout in milliseconds. */
+  timeoutMs?: number
+  /** WebSocket connection timeout in milliseconds. */
+  websocketConnectTimeoutMs?: number
+  /** Provider SDK retry count. */
+  maxRetries?: number
+  /** Maximum provider-requested retry delay in milliseconds. */
+  maxRetryDelayMs?: number
+}
+
+/** Plugin configuration: the non-empty provider profiles this instance owns. */
+export interface Config {
+  /** Non-empty set of pi-ai provider routes this adapter instance owns. */
+  providers: PiAiProviderProfile[]
+}
+
+const thinkingBudgets = z.object({
+  minimal: z.number(),
+  low: z.number(),
+  medium: z.number(),
+  high: z.number(),
+})
+
+const profile = z.object({
+  provider: z.string().required(),
+  apiKey: z.string(),
+  baseURL: z.string(),
+  headers: z.dict(z.string()),
+  reasoning: z.union(['minimal', 'low', 'medium', 'high', 'xhigh']),
+  thinkingBudgets,
+  cacheRetention: z.union(['none', 'short', 'long']),
+  transport: z.union(['sse', 'websocket', 'websocket-cached', 'auto']),
+  timeoutMs: z.natural(),
+  websocketConnectTimeoutMs: z.natural(),
+  maxRetries: z.natural(),
+  maxRetryDelayMs: z.natural(),
+})
+
+/** Runtime schema for {@link Config}. */
+export const Config: z<Config> = z.object({
+  providers: z.array(profile).required(),
+})
+
+/**
+ * Validate profiles against the installed pi-ai catalog and return a detached
+ * shallow copy suitable for adapter construction.
+ * @param profiles - configured provider profiles.
+ * @returns validated profiles in configuration order.
+ */
+export function resolveProfiles(profiles: readonly PiAiProviderProfile[]): PiAiProviderProfile[] {
+  if (profiles.length === 0) throw new Error('llm-pi-ai: providers must contain at least one profile')
+  const supported = new Set<string>(getProviders())
+  const seen = new Set<string>()
+  return profiles.map((source) => {
+    if (source.provider.length === 0) throw new Error('llm-pi-ai: provider names must be non-empty')
+    if (!supported.has(source.provider)) throw new Error(`llm-pi-ai: unknown pi-ai provider "${source.provider}"`)
+    if (seen.has(source.provider)) throw new Error(`llm-pi-ai: duplicate provider profile "${source.provider}"`)
+    if (source.apiKey !== undefined && source.apiKey.trim().length === 0) {
+      throw new Error(`llm-pi-ai: provider "${source.provider}" has an empty apiKey; omit it to use ambient authentication`)
+    }
+    if (source.baseURL !== undefined && source.baseURL.length === 0) {
+      throw new Error(`llm-pi-ai: provider "${source.provider}" has an empty baseURL`)
+    }
+    seen.add(source.provider)
+    return {
+      ...source,
+      ...source.headers === undefined ? {} : { headers: { ...source.headers } },
+      ...source.thinkingBudgets === undefined ? {} : { thinkingBudgets: { ...source.thinkingBudgets } },
+    }
+  })
+}

packages/llm/llm-pi-ai/src/context.ts

@@ -0,0 +1,85 @@
+/**
+ * Harness request-history conversion into pi-ai's Context vocabulary.
+ *
+ * @module dsh-llm-pi-ai/context
+ */
+
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
+import type { Context as PiContext, Message as PiMessage, Tool as PiTool } from '@earendil-works/pi-ai'
+import { toPiAssistant } from './replay.ts'
+
+/** Join the text blocks of a harness message. */
+function flattenText(message: Message): string {
+  return message.content
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+/**
+ * Convert harness history to a pi-ai Context. Tool results need the tool
+ * NAME (pi-ai's `toolName`), which the harness doesn't carry on the result
+ * block — it is recovered from the preceding assistant tool-call with the
+ * same id.
+ * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+ * @returns the pi-ai context; `tools` is omitted entirely when the request declares none.
+ */
+export function toPiContext(options: GenerateOptions): PiContext {
+  const toolNames = new Map<CallId, string>()
+  const messages: PiMessage[] = []
+
+  for (const message of options.messages) {
+    if (message.role === 'system') {
+      // pi-ai has a single systemPrompt slot; in-history system messages are
+      // folded into user messages to preserve order (rare in practice — the
+      // harness sends the system prompt via options.system).
+      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
+      continue
+    }
+    if (message.role === 'assistant') {
+      const assistant = toPiAssistant(message)
+      for (const block of assistant.content) {
+        if (block.type === 'toolCall') toolNames.set(CallId(block.id), block.name)
+      }
+      messages.push(assistant)
+      continue
+    }
+    // user role: text + tool results (each result becomes its own message).
+    const text = flattenText(message)
+    const results = message.content.filter(block => block.type === 'tool-result')
+    if (text.length > 0 || results.length === 0) {
+      messages.push({ role: 'user', content: text, timestamp: 0 })
+    }
+    for (const result of results) {
+      messages.push({
+        role: 'toolResult',
+        toolCallId: result.toolCallId,
+        toolName: toolNames.get(result.toolCallId) ?? 'unknown',
+        content: [{
+          type: 'text',
+          text: result.content
+            .filter(block => block.type === 'text')
+            .map(block => block.text)
+            .join('') || '(no output)',
+        }],
+        isError: result.isError ?? false,
+        timestamp: 0,
+      })
+    }
+  }
+
+  const tools: PiTool[] | undefined = options.tools?.map(tool => ({
+    name: tool.name,
+    description: tool.description,
+    // ToolSchema.parameters is a JSON Schema object; pi-ai's TSchema
+    // (TypeBox) is structurally JSON Schema, so it assigns directly.
+    parameters: tool.parameters,
+  }))
+
+  return {
+    ...options.system !== undefined ? { systemPrompt: options.system } : {},
+    messages,
+    ...tools !== undefined && tools.length > 0 ? { tools } : {},
+  }
+}

packages/llm/llm-pi-ai/src/index.ts

@@ -1,76 +1,45 @@
 /**
- * pi-ai-backed DeepSeek adapter plugin. Same Config shape as
- * `@deepseek-ai/dsh-llm-deepseek` (one-line swap in cordis.yml), different
- * implementation underneath — see `./adapter.ts` for why both exist.
+ * Generic pi-ai-backed LLM adapter plugin. One plugin instance registers an
+ * explicit set of provider profiles; requests select a profile by provider and
+ * resolve the model dynamically from pi-ai's installed catalog.
  *
  * ```yaml
  * - id: llm
  *   name: '@deepseek-ai/dsh-llm-pi-ai'
  *   config:
- *     apiKey: !!js process.env.DEEPSEEK_API_KEY
- *     baseURL: !!js process.env.DEEPSEEK_BASE_URL
- *     models: [deepseek-v4-flash, deepseek-v4-pro]
- *     reasoning: high
+ *     providers:
+ *       - provider: openai
+ *         apiKey: !!js process.env.OPENAI_API_KEY
+ *       - provider: anthropic
+ *         apiKey: !!js process.env.ANTHROPIC_API_KEY
+ *       - provider: openrouter
+ *         apiKey: !!js process.env.OPENROUTER_API_KEY
+ *         baseURL: https://proxy.example.com/v1
  * ```
  *
  * @module @deepseek-ai/dsh-llm-pi-ai
  */
 
 import type { Context } from 'cordis'
-import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-llm'
 import { PiAiAdapter } from './adapter.ts'
-import type { PiAiReasoning } from './adapter.ts'
+import { Config, resolveProfiles } from './config.ts'
 
-export { buildModel, PiAiAdapter } from './adapter.ts'
-export type { PiAiAdapterOptions, PiAiReasoning } from './adapter.ts'
-export { mapStopReason, mapUsage, toPiContext, toStreamChunks } from './convert.ts'
+export { PiAiAdapter } from './adapter.ts'
+export type { PiAiAdapterOptions } from './adapter.ts'
+export { Config, resolveProfiles } from './config.ts'
+export type { PiAiProviderProfile } from './config.ts'
+export { toPiContext } from './context.ts'
+export { toPiReplayState } from './replay.ts'
+export type { PiAiReplayState } from './replay.ts'
+export { mapStopReason, mapUsage, toStreamChunks } from './stream.ts'
 
 export const name = 'llm-pi-ai'
 export const inject = ['llm']
 
-/**
- * Plugin config, validated by the same-named schemastery schema. Every field
- * is optional in yml: credentials/endpoint fall back to the environment (a
- * missing API key fails plugin load, not the first call).
- */
-export interface Config {
-  /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
-  apiKey?: string
-  /** Endpoint base; falls back to $DEEPSEEK_BASE_URL, then the public API. */
-  baseURL?: string
-  /** Model names to register (sent verbatim on the wire). */
-  models?: string[]
-  /**
-   * Thinking level for every request: 'off' disables thinking mode; 'high'
-   * and 'xhigh' (wire 'max') set the effort. Omitted = provider default
-   * (thinking enabled), matching llm-deepseek's omission semantics.
-   */
-  reasoning?: PiAiReasoning
-}
-
-export const Config: z<Config> = z.object({
-  apiKey: z.string(),
-  baseURL: z.string(),
-  models: z.array(z.string()).default(['deepseek-v4-flash', 'deepseek-v4-pro']),
-  reasoning: z.union(['off', 'high', 'xhigh']),
-})
-
-/** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
-export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
-
+/** Register one generic pi-ai adapter for all configured provider routes. */
 export function apply(ctx: Context, config: Config): void {
-  const apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY
-  if (apiKey === undefined || apiKey.length === 0) {
-    throw new Error('llm-pi-ai: an API key is required (Config.apiKey or $DEEPSEEK_API_KEY)')
-  }
-  const baseURL = config.baseURL ?? process.env.DEEPSEEK_BASE_URL ?? PUBLIC_BASE_URL
-  // schemastery's .default() guarantees models is set after validation.
-  const models = config.models as string[]
-
-  ctx.llm.registerAdapter(models, new PiAiAdapter({
-    apiKey,
-    baseURL,
-    reasoning: config.reasoning,
-  }))
+  const profiles = resolveProfiles(config.providers)
+  const adapter = new PiAiAdapter({ profiles })
+  ctx.llm.registerAdapter(profiles.map(entry => entry.provider), adapter)
 }

packages/llm/llm-pi-ai/src/replay.ts

@@ -0,0 +1,211 @@
+/**
+ * Durable pi-ai replay metadata and assistant-history reconstruction.
+ *
+ * Harness content remains the durable source for text and tool calls. This
+ * module stores only the provider-native metadata needed to reconstruct a
+ * pi-ai assistant message on a later request.
+ *
+ * @module dsh-llm-pi-ai/replay
+ */
+
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import type { Api, AssistantMessage, Usage as PiUsage } from '@earendil-works/pi-ai'
+
+type PiAiReplayBlock =
+  | { type: 'text'; textSignature?: string }
+  | { type: 'reasoning'; thinkingSignature?: string; redacted?: boolean }
+  | { type: 'tool-call'; thoughtSignature?: string }
+
+/** Versioned adapter-private projection required to replay a pi-ai response. */
+export interface PiAiReplayState {
+  kind: 'pi-ai'
+  version: 1
+  api: Api
+  provider: string
+  model: string
+  responseModel?: string
+  responseId?: string
+  stopReason: AssistantMessage['stopReason']
+  blocks: PiAiReplayBlock[]
+}
+
+/** Parse tool-call argument JSON; tolerate model malformations with {}. */
+function parseArguments(raw: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    // fall through
+  }
+  return {}
+}
+
+/** Construct the zero usage value required by historical pi-ai messages. */
+function emptyPiUsage(): PiUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  }
+}
+
+/**
+ * Project a successful pi-ai response into the minimal durable replay state.
+ * @param message - completed native pi-ai assistant response.
+ * @returns the versioned lossless-JSON replay projection.
+ */
+export function toPiReplayState(message: AssistantMessage): PiAiReplayState {
+  return {
+    kind: 'pi-ai',
+    version: 1,
+    api: message.api,
+    provider: message.provider,
+    model: message.model,
+    ...message.responseModel === undefined ? {} : { responseModel: message.responseModel },
+    ...message.responseId === undefined ? {} : { responseId: message.responseId },
+    stopReason: message.stopReason,
+    blocks: message.content.map((block): PiAiReplayBlock => {
+      switch (block.type) {
+        case 'text': return {
+          type: 'text',
+          ...block.textSignature === undefined ? {} : { textSignature: block.textSignature },
+        }
+        case 'thinking': return {
+          type: 'reasoning',
+          ...block.thinkingSignature === undefined ? {} : { thinkingSignature: block.thinkingSignature },
+          ...block.redacted === undefined ? {} : { redacted: block.redacted },
+        }
+        case 'toolCall': return {
+          type: 'tool-call',
+          ...block.thoughtSignature === undefined ? {} : { thoughtSignature: block.thoughtSignature },
+        }
+      }
+    }),
+  }
+}
+
+function invalidReplay(message: string): never {
+  throw new LlmError(`invalid pi-ai replay state: ${message}`, 'INVALID_REPLAY_STATE')
+}
+
+/** Validate the adapter-private state before it reaches pi-ai. */
+function readReplayState(value: unknown): PiAiReplayState {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidReplay('expected an object')
+  const state = value as Record<string, unknown>
+  if (state['kind'] !== 'pi-ai') return invalidReplay('unknown state kind')
+  if (state['version'] !== 1) return invalidReplay(`unsupported version ${String(state['version'])}`)
+  for (const key of ['api', 'provider', 'model'] as const) {
+    if (typeof state[key] !== 'string' || state[key].length === 0) return invalidReplay(`${key} must be a non-empty string`)
+  }
+  if (!['stop', 'length', 'toolUse', 'error', 'aborted'].includes(String(state['stopReason']))) {
+    return invalidReplay('unknown stopReason')
+  }
+  if (state['responseModel'] !== undefined && typeof state['responseModel'] !== 'string') return invalidReplay('responseModel must be a string')
+  if (state['responseId'] !== undefined && typeof state['responseId'] !== 'string') return invalidReplay('responseId must be a string')
+  if (!Array.isArray(state['blocks'])) return invalidReplay('blocks must be an array')
+  for (const [index, value] of state['blocks'].entries()) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidReplay(`block ${index} must be an object`)
+    const block = value as Record<string, unknown>
+    if (!['text', 'reasoning', 'tool-call'].includes(String(block['type']))) return invalidReplay(`block ${index} has an unknown type`)
+    for (const signature of ['textSignature', 'thinkingSignature', 'thoughtSignature'] as const) {
+      if (block[signature] !== undefined && typeof block[signature] !== 'string') return invalidReplay(`block ${index} ${signature} must be a string`)
+    }
+    if (block['redacted'] !== undefined && typeof block['redacted'] !== 'boolean') return invalidReplay(`block ${index} redacted must be boolean`)
+  }
+  return state as unknown as PiAiReplayState
+}
+
+/** Convert provider-neutral blocks without trusting them as same-model replay. */
+function foreignAssistant(message: Message): AssistantMessage {
+  const content: AssistantMessage['content'] = []
+  for (const block of message.content) {
+    switch (block.type) {
+      case 'text': content.push({ type: 'text', text: block.text }); break
+      case 'reasoning': content.push({ type: 'thinking', thinking: block.text }); break
+      case 'tool-call': content.push({
+        type: 'toolCall',
+        id: block.id,
+        name: block.name,
+        arguments: parseArguments(block.arguments),
+      }); break
+      default:
+        // plugin-added block types are not representable in pi-ai.
+        break
+    }
+  }
+  return {
+    role: 'assistant',
+    content,
+    // Deliberately never equals a catalog API: absent replay state is foreign
+    // even if provenance names the same provider/model as this request.
+    api: 'dsh-foreign',
+    provider: message.provenance?.provider ?? 'dsh-foreign',
+    model: message.provenance?.model ?? 'dsh-foreign',
+    usage: emptyPiUsage(),
+    stopReason: content.some(piece => piece.type === 'toolCall') ? 'toolUse' : 'stop',
+    timestamp: 0,
+  }
+}
+
+/** Recombine durable Harness content with validated pi-ai replay metadata. */
+function replayedAssistant(message: Message, rawState: unknown): AssistantMessage {
+  const state = readReplayState(rawState)
+  const provenance = message.provenance
+  if (state.provider !== provenance?.provider) return invalidReplay('provider does not match assistant provenance')
+  if (state.model !== provenance.model) return invalidReplay('model does not match assistant provenance')
+  if (state.blocks.length !== message.content.length) return invalidReplay('block count does not match assistant content')
+  const content: AssistantMessage['content'] = message.content.map((block, index) => {
+    const replay = state.blocks[index]
+    if (replay === undefined || replay.type !== block.type) return invalidReplay(`block ${index} does not match assistant content`)
+    switch (block.type) {
+      case 'text': return {
+        type: 'text',
+        text: block.text,
+        ...replay.type === 'text' && replay.textSignature !== undefined ? { textSignature: replay.textSignature } : {},
+      }
+      case 'reasoning': return {
+        type: 'thinking',
+        thinking: block.text,
+        ...replay.type === 'reasoning' && replay.thinkingSignature !== undefined ? { thinkingSignature: replay.thinkingSignature } : {},
+        ...replay.type === 'reasoning' && replay.redacted !== undefined ? { redacted: replay.redacted } : {},
+      }
+      case 'tool-call': return {
+        type: 'toolCall',
+        id: block.id,
+        name: block.name,
+        arguments: parseArguments(block.arguments),
+        ...replay.type === 'tool-call' && replay.thoughtSignature !== undefined ? { thoughtSignature: replay.thoughtSignature } : {},
+      }
+      /* v8 ignore next -- readReplayState rejects unknown replay tags, so an equal plugin-added Harness tag cannot reach this switch */
+      default: return invalidReplay(`block ${index} has an unsupported Harness type`)
+    }
+  })
+  return {
+    role: 'assistant',
+    content,
+    api: state.api,
+    provider: state.provider,
+    model: state.model,
+    ...state.responseModel === undefined ? {} : { responseModel: state.responseModel },
+    ...state.responseId === undefined ? {} : { responseId: state.responseId },
+    usage: emptyPiUsage(),
+    stopReason: state.stopReason,
+    timestamp: 0,
+  }
+}
+
+/**
+ * Convert one durable Harness assistant message into pi-ai history.
+ * @param message - assistant content with optional adapter-owned replay metadata.
+ * @returns a native pi-ai assistant message reconstructed from durable content.
+ */
+export function toPiAssistant(message: Message): AssistantMessage {
+  const replayState = message.provenance?.replayState
+  return replayState === undefined ? foreignAssistant(message) : replayedAssistant(message, replayState)
+}

packages/llm/llm-pi-ai/src/stream.ts

@@ -1,152 +1,17 @@
 /**
- * Bidirectional mapping between the harness vocabulary and pi-ai's:
- * Convert harness requests to pi-ai context and pi-ai assistant events to harness stream chunks.
- * pi-ai parses tool arguments while the harness preserves raw JSON, so conversion parses inbound
- * arguments and re-stringifies outbound values while the adapter restores provider payloads.
- * In-stream pi-ai errors become harness error/aborted finishes, and its reasoning tokens remain
- * folded into output usage because it reports no separate count.
- * @module dsh-llm-pi-ai/convert
+ * pi-ai assistant event translation into the Harness streaming protocol.
+ *
+ * pi-ai tool-call arguments are parsed objects while the Harness keeps their
+ * raw JSON representation. pi-ai also reports failures as terminal stream
+ * events, which this module maps into Harness finish chunks.
+ *
+ * @module dsh-llm-pi-ai/stream
  */
 
 import { CallId, LlmError } from '@deepseek-ai/dsh-llm'
-import type { FinishReason, GenerateOptions, Message, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
-import type {
-  AssistantMessage,
-  AssistantMessageEvent,
-  Context as PiContext,
-  Message as PiMessage,
-  Tool as PiTool,
-  Usage as PiUsage,
-} from '@earendil-works/pi-ai'
-
-/** Join the text blocks of a harness message. */
-function flattenText(message: Message): string {
-  return message.content
-    .filter(block => block.type === 'text')
-    .map(block => block.text)
-    .join('')
-}
-
-/** Parse tool-call argument JSON; tolerate model malformations with {}. */
-function parseArguments(raw: string): Record<string, unknown> {
-  try {
-    const parsed: unknown = JSON.parse(raw)
-    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
-      return parsed as Record<string, unknown>
-    }
-  } catch {
-    // fall through
-  }
-  return {}
-}
-
-/**
- * Convert harness history to a pi-ai Context. Tool results need the tool
- * NAME (pi-ai's `toolName`), which the harness doesn't carry on the result
- * block — it is recovered from the preceding assistant tool-call with the
- * same id.
- * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
- * @returns the pi-ai context; `tools` is omitted entirely when the request declares none.
- */
-export function toPiContext(options: GenerateOptions): PiContext {
-  const toolNames = new Map<CallId, string>()
-  const messages: PiMessage[] = []
-
-  for (const message of options.messages) {
-    if (message.role === 'system') {
-      // pi-ai has a single systemPrompt slot; in-history system messages are
-      // folded into user messages to preserve order (rare in practice — the
-      // harness sends the system prompt via options.system).
-      messages.push({ role: 'user', content: flattenText(message), timestamp: 0 })
-      continue
-    }
-    if (message.role === 'assistant') {
-      const content: AssistantMessage['content'] = []
-      for (const block of message.content) {
-        switch (block.type) {
-          case 'text':
-            content.push({ type: 'text', text: block.text })
-            break
-          case 'reasoning':
-            // Without this wire-field name, pi-ai replays an empty `reasoning_content`, violating
-            // DeepSeek's thinking-mode passback rule on tool-call turns.
-            content.push({ type: 'thinking', thinking: block.text, thinkingSignature: 'reasoning_content' })
-            break
-          case 'tool-call':
-            toolNames.set(block.id, block.name)
-            content.push({
-              type: 'toolCall',
-              id: block.id,
-              name: block.name,
-              arguments: parseArguments(block.arguments),
-            })
-            break
-          default:
-            // plugin-added block types: not representable here.
-            break
-        }
-      }
-      messages.push({
-        role: 'assistant',
-        content,
-        api: 'openai-completions',
-        provider: 'deepseek',
-        model: options.model,
-        usage: emptyPiUsage(),
-        stopReason: content.some(piece => piece.type === 'toolCall') ? 'toolUse' : 'stop',
-        timestamp: 0,
-      })
-      continue
-    }
-    // user role: text + tool results (each result becomes its own message).
-    const text = flattenText(message)
-    const results = message.content.filter(block => block.type === 'tool-result')
-    if (text.length > 0 || results.length === 0) {
-      messages.push({ role: 'user', content: text, timestamp: 0 })
-    }
-    for (const result of results) {
-      messages.push({
-        role: 'toolResult',
-        toolCallId: result.toolCallId,
-        toolName: toolNames.get(result.toolCallId) ?? 'unknown',
-        content: [{
-          type: 'text',
-          text: result.content
-            .filter(block => block.type === 'text')
-            .map(block => block.text)
-            .join('') || '(no output)',
-        }],
-        isError: result.isError ?? false,
-        timestamp: 0,
-      })
-    }
-  }
-
-  const tools: PiTool[] | undefined = options.tools?.map(tool => ({
-    name: tool.name,
-    description: tool.description,
-    // ToolSchema.parameters is a JSON Schema object; pi-ai's TSchema
-    // (TypeBox) is structurally JSON Schema, so it assigns directly.
-    parameters: tool.parameters,
-  }))
-
-  return {
-    ...options.system !== undefined ? { systemPrompt: options.system } : {},
-    messages,
-    ...tools !== undefined && tools.length > 0 ? { tools } : {},
-  }
-}
-
-function emptyPiUsage(): PiUsage {
-  return {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    totalTokens: 0,
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-  }
-}
+import type { FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { AssistantMessage, AssistantMessageEvent, Usage as PiUsage } from '@earendil-works/pi-ai'
+import { toPiReplayState } from './replay.ts'
 
 /**
  * Map pi-ai usage (reasoning folded into output by pi-ai).
@@ -259,7 +124,7 @@ export async function* toStreamChunks(events: AsyncIterable<AssistantMessageEven
         break
       case 'done':
         yield { type: 'usage', usage: mapUsage(event.message.usage) }
-        yield { type: 'finish', reason: mapStopReason(event.message) }
+        yield { type: 'finish', reason: mapStopReason(event.message), replayState: toPiReplayState(event.message) }
         return
       case 'error':
         // In-stream error delivery (pi-ai's style) → error finish chunk

packages/llm/llm-pi-ai/tests/adapter.e2e.ts

@@ -3,26 +3,33 @@ import { Context } from 'cordis'
 import LlmService, { CallId } from '@deepseek-ai/dsh-llm'
 import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
-import type { Config } from '@deepseek-ai/dsh-llm-pi-ai'
+import type { PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { assemble, type AssembledResult } from './assemble.ts'
 
 /**
- * Real-API e2e for the pi-ai-backed adapter: V4 Flash + V4 Pro across all
- * reasoning levels the adapter exposes (off / high / xhigh→wire 'max').
- * Mirrors the llm-deepseek matrix so the two independent implementations
- * verify the same StreamChunk contract. Key-gated.
+ * Real-API e2e for the pi-ai-backed adapter: V4 Flash + V4 Pro with provider
+ * defaults and representative high/xhigh reasoning. Mirrors the native
+ * adapter's StreamChunk contract and exercises a replayed tool follow-up.
+ * Key-gated.
  */
 
 const FLASH = 'deepseek-v4-flash'
 const PRO = 'deepseek-v4-pro'
 const contexts: Context[] = []
 
-async function harness(model: string, config: Partial<Config> = {}) {
+async function harness(_model: string, config: Partial<PiAiProviderProfile> = {}) {
   const ctx = new Context()
   contexts.push(ctx)
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmPiAi, { models: [model], ...config })
+  await ctx.plugin(LlmPiAi, {
+    providers: [{
+      provider: 'deepseek',
+      ...process.env.DEEPSEEK_API_KEY === undefined ? {} : { apiKey: process.env.DEEPSEEK_API_KEY },
+      ...process.env.DEEPSEEK_BASE_URL === undefined ? {} : { baseURL: process.env.DEEPSEEK_BASE_URL },
+      ...config,
+    }],
+  })
   return ctx
 }
 
@@ -56,8 +63,8 @@ const weatherTool: ToolSchema = {
 }
 
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => {
-  it.each([FLASH, PRO])('%s + reasoning off: plain text generation', async (model) => {
-    const ctx = await harness(model, { reasoning: 'off' })
+  it.each([FLASH, PRO])('%s + provider-default reasoning: plain text generation', async (model) => {
+    const ctx = await harness(model)
     const result = await assemble(ctx,{
       model,
       messages: ask('Reply with exactly the word: pong'),
@@ -65,7 +72,6 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
     })
     expect(result.finish.kind).toBe('stop')
     expect(textOf(result).toLowerCase()).toContain('pong')
-    expect(result.message.content.some(block => block.type === 'reasoning')).toBe(false)
   })
 
   it.each([FLASH, PRO])('%s + reasoning high: reasoning blocks present', async (model) => {
@@ -99,7 +105,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
       model: PRO,
       messages: [
         ...ask('What is the weather in Paris right now? Use the get_weather tool.'),
-        { role: 'assistant', content: first.message.content },
+        first.message,
         {
           role: 'user',
           content: [{
@@ -123,9 +129,9 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
     const deepseekCtx = new Context()
     contexts.push(deepseekCtx)
     await deepseekCtx.plugin(LlmService)
-    await deepseekCtx.plugin(LlmDeepSeek, { models: [FLASH], thinking: 'disabled' })
+    await deepseekCtx.plugin(LlmDeepSeek, { thinking: 'disabled' })
 
-    const piCtx = await harness(FLASH, { reasoning: 'off' })
+    const piCtx = await harness(FLASH)
 
     const prompt = ask('Reply with exactly the word: pong')
     const [fromDeepSeek, fromPiAi] = await Promise.all([

packages/llm/llm-pi-ai/tests/adapter.spec.ts

@@ -2,34 +2,35 @@ import { createServer } from 'node:http'
 import type { IncomingMessage, Server, ServerResponse } from 'node:http'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import LlmService, { CallId, userAgent } from '@deepseek-ai/dsh-llm'
+import LlmService, { LlmError, userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
-import { buildModel, PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { PiAiAdapter, resolveProfiles } from '@deepseek-ai/dsh-llm-pi-ai'
 import { assemble } from './assemble.ts'
 
-/** Scripted SSE responses, one per request (OpenAI chat-completions shape). */
 interface MockServer {
   url: string
+  paths: string[]
   requests: unknown[]
-  /** Header bags of received requests, in order (parallel to `requests`). */
   headers: IncomingMessage['headers'][]
-  close(): Promise<void>
 }
 
 const servers: Server[] = []
 
 afterEach(async () => {
+  vi.unstubAllEnvs()
   await Promise.all(servers.splice(0).map(server => new Promise(resolve => server.close(resolve))))
 })
 
-async function mockServer(script: { status?: number; events?: string[]; body?: string }[]): Promise<MockServer> {
+async function mockServer(script: { status?: number; events?: string[]; body?: string; delayMs?: number }[]): Promise<MockServer> {
+  const paths: string[] = []
   const requests: unknown[] = []
   const headers: IncomingMessage['headers'][] = []
   const server = createServer((request: IncomingMessage, response: ServerResponse) => {
     let body = ''
     request.on('data', (chunk: Buffer) => { body += chunk.toString('utf8') })
     request.on('end', () => {
-      requests.push(JSON.parse(body))
+      paths.push(request.url ?? '')
+      requests.push(body.length === 0 ? undefined : JSON.parse(body))
       headers.push(request.headers)
       const behavior = script.shift() ?? { status: 500, body: 'script exhausted' }
       if (behavior.status !== undefined && behavior.status !== 200) {
@@ -38,20 +39,22 @@ async function mockServer(script: { status?: number; events?: string[]; body?: s
         return
       }
       response.writeHead(200, { 'content-type': 'text/event-stream' })
-      for (const event of behavior.events ?? []) response.write(`data: ${event}\n\n`)
-      response.end()
+      let index = 0
+      const writeNext = (): void => {
+        const event = behavior.events?.[index++]
+        if (event === undefined) { response.end(); return }
+        response.write(`data: ${event}\n\n`)
+        if (behavior.delayMs === undefined) writeNext()
+        else setTimeout(writeNext, behavior.delayMs)
+      }
+      writeNext()
     })
   })
   servers.push(server)
   await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
   const address = server.address()
   if (address === null || typeof address === 'string') throw new Error('no port')
-  return {
-    url: `http://127.0.0.1:${address.port}`,
-    requests,
-    headers,
-    close: () => new Promise(resolve => server.close(() => { resolve() })),
-  }
+  return { url: `http://127.0.0.1:${address.port}`, paths, requests, headers }
 }
 
 const textEvents = [
@@ -61,347 +64,231 @@ const textEvents = [
   '[DONE]',
 ]
 
-const toolEvents = [
-  '{"choices":[{"delta":{"role":"assistant","content":null},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call-1","type":"function","function":{"name":"get_weather","arguments":""}}]},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\\"city\\":\\"Paris\\"}"}}]},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{},"index":0,"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":20,"completion_tokens":6}}',
-  '[DONE]',
-]
-
-const thinkingEvents = [
-  '{"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":""},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{"reasoning_content":"pondering"},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{"content":"answer","reasoning_content":null},"index":0,"finish_reason":null}]}',
-  '{"choices":[{"delta":{},"index":0,"finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":9}}',
-  '[DONE]',
-]
-
-async function harness(baseURL: string, config: object = {}) {
+async function harness(baseURL: string, overrides: Record<string, unknown> = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
-  await ctx.plugin(LlmPiAi, { apiKey: 'test-key', baseURL, models: ['deepseek-v4-flash'], ...config })
+  await ctx.plugin(LlmPiAi, {
+    providers: [{ provider: 'deepseek', apiKey: 'test-key', baseURL, ...overrides }],
+  })
   return ctx
 }
 
-describe('PiAiAdapter against a mock server', () => {
-  it('streams a text generation through the assembler', async () => {
+describe('PiAiAdapter provider routing', () => {
+  it('resolves a catalog model dynamically and uses a private endpoint', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
-
     const result = await assemble(ctx, {
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
     })
     expect(result.message.content).toEqual([{ type: 'text', text: 'hello' }])
     expect(result.finish).toEqual({ kind: 'stop' })
-    expect(result.usage).toMatchObject({ inputTokens: 3, outputTokens: 1 })
+    expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 1 })
+    expect(server.paths).toEqual(['/chat/completions'])
+  })
 
-    // Attribution reaches the wire through pi-ai's headers hook: the exact
-    // shared User-Agent, and no provider-specific headers under the
-    // User-Agent-only contract.
+  it('merges profile headers with Harness attribution winning', async () => {
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = await harness(server.url, {
+      headers: { 'x-company': 'private', 'User-Agent': 'wrong' },
+    })
+    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(server.headers[0]?.['x-company']).toBe('private')
     expect(server.headers[0]?.['user-agent']).toBe(userAgent())
-    expect(server.headers[0]).not.toHaveProperty('http-referer')
-    expect(server.headers[0]).not.toHaveProperty('x-openrouter-title')
-    expect(server.headers[0]).not.toHaveProperty('x-openrouter-categories')
   })
 
-  it('streams tool calls with re-stringified arguments', async () => {
-    const server = await mockServer([{ events: toolEvents }])
-    const ctx = await harness(server.url)
-
-    const result = await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [{ role: 'user', content: [{ type: 'text', text: 'weather?' }] }],
-      tools: [{
-        name: 'get_weather',
-        description: 'Get weather',
-        parameters: { type: 'object', properties: { city: { type: 'string' } } },
-      }],
+  it('forwards common stream options and profile reasoning', async () => {
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = await harness(server.url, {
+      reasoning: 'xhigh',
+      cacheRetention: 'none',
+      transport: 'sse',
+      timeoutMs: 5000,
+      websocketConnectTimeoutMs: 3000,
+      maxRetries: 0,
+      maxRetryDelayMs: 10,
+      thinkingBudgets: { high: 2048 },
     })
-    expect(result.finish).toEqual({ kind: 'tool-calls' })
-    const call = result.message.content.find(block => block.type === 'tool-call')
-    expect(call).toMatchObject({ name: 'get_weather', arguments: '{"city":"Paris"}' })
-  })
-
-  it('maps reasoning_content streams to reasoning blocks', async () => {
-    const server = await mockServer([{ events: thinkingEvents }])
-    const ctx = await harness(server.url, { reasoning: 'high' })
-
-    const result = await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [{ role: 'user', content: [{ type: 'text', text: 'think' }] }],
-    })
-    expect(result.message.content).toEqual([
-      { type: 'reasoning', text: 'pondering' },
-      { type: 'text', text: 'answer' },
-    ])
-  })
-
-  it('sends DeepSeek thinking fields when reasoning is configured', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url, { reasoning: 'xhigh' })
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(server.requests[0]).toMatchObject({
-      thinking: { type: 'enabled' },
-      reasoning_effort: 'max', // xhigh maps to max via thinkingLevelMap
-    })
-  })
-
-  it('disables thinking for reasoning: off', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url, { reasoning: 'off' })
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(server.requests[0]).toMatchObject({ thinking: { type: 'disabled' } })
-  })
-
-  it('injects stop sequences through onPayload', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url)
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [], stop: ['END'] })
-    expect(server.requests[0]).toMatchObject({ stop: ['END'] })
-  })
-
-  it('scrubs pi-ai\'s own per-tool strict default through onPayload', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url)
-    await assemble(ctx,{
+    await assemble(ctx, {
       model: 'deepseek-v4-flash',
       messages: [],
-      tools: [
-        { name: 'alpha', description: 'a', parameters: {} },
-        { name: 'beta', description: 'b', parameters: {} },
-      ],
+      temperature: 0.2,
+      maxTokens: 77,
+      sessionId: 'session-for-pi' as never,
     })
-
-    // pi-ai stamps `strict` on every serialized tool function; the harness
-    // contract has none and the hand-rolled twin sends no such field, so the
-    // payload fixup must have deleted it from every tool.
-    const request = server.requests[0] as { tools: { function: { name: string; strict?: boolean } }[] }
-    expect(request.tools.map(tool => tool.function.name)).toEqual(['alpha', 'beta'])
-    for (const tool of request.tools) {
-      expect('strict' in tool.function).toBe(false)
-    }
-  })
-
-  it('preserves raw replayed tool-call arguments in the provider payload', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url)
-    await assemble(ctx,{
+    expect(server.requests[0]).toMatchObject({
       model: 'deepseek-v4-flash',
-      messages: [{
-        role: 'assistant',
-        content: [{ type: 'tool-call', id: CallId('broken'), name: 'f', arguments: '{broken' }],
-      }],
+      temperature: 0.2,
+      max_completion_tokens: 77,
+      thinking: { type: 'enabled' },
+      reasoning_effort: 'max',
     })
-
-    const request = server.requests[0] as { messages: { role: string; tool_calls?: { id: string; function: { arguments: string } }[] }[] }
-    const assistant = request.messages.find(message => message.role === 'assistant')
-    expect(assistant?.tool_calls?.[0]?.function.arguments).toBe('{broken')
   })
 
-  it('maps HTTP errors to error finish chunks (pi-ai in-stream style)', async () => {
-    const server = await mockServer([{
-      status: 401,
-      body: JSON.stringify({ error: { message: 'bad key' } }),
-    }])
+  it('preserves omitted profile options when constructing the adapter directly', async () => {
+    const server = await mockServer([{ events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['deepseek'], new PiAiAdapter({
+      profiles: [{ provider: 'deepseek', apiKey: 'test-key', baseURL: server.url }],
+    }))
+
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+
+    expect(result.message.content).toEqual([{ type: 'text', text: 'hello' }])
+  })
+
+  it('rejects stop sequences rather than silently ignoring them', async () => {
+    const server = await mockServer([])
     const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toMatchObject({ kind: 'error', code: 'AUTH' })
-    expect((result.finish as { message: string }).message).toMatch(/bad key|401/)
+    await expect(assemble(ctx, { model: 'deepseek-v4-flash', messages: [], stop: ['END'] }))
+      .rejects.toMatchObject({ code: 'UNSUPPORTED_OPTION' })
+    expect(server.requests).toEqual([])
+  })
+
+  it('rejects unknown catalog models before network I/O', async () => {
+    const server = await mockServer([])
+    const ctx = await harness(server.url)
+    await expect(assemble(ctx, { model: 'not-in-the-catalog', messages: [] }))
+      .rejects.toMatchObject({ code: 'UNKNOWN_MODEL' })
+    expect(server.requests).toEqual([])
+  })
+
+  it('uses the catalog API implementation, including OpenAI Responses', async () => {
+    const server = await mockServer([{ status: 401, body: JSON.stringify({ error: { message: 'expected mock failure' } }) }])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, {
+      providers: [{ provider: 'openai', apiKey: 'test-key', baseURL: `${server.url}/v1`, maxRetries: 0 }],
+    })
+    const result = await assemble(ctx, { provider: 'openai', model: 'gpt-4.1', messages: [] })
+    expect(result.finish.kind).toBe('error')
+    expect(server.paths).toEqual(['/v1/responses'])
   })
 
   it.each([
+    [401, 'AUTH'],
     [400, 'INVALID_REQUEST'],
     [429, 'RATE_LIMIT'],
     [500, 'SERVER'],
-  ] as const)('maps HTTP %s to stable error code %s', async (status, code) => {
+  ] as const)('maps HTTP %s failures to %s', async (status, code) => {
     const server = await mockServer([{ status, body: JSON.stringify({ error: { message: `provider ${status}` } }) }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    const ctx = await harness(server.url, { maxRetries: 0 })
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
     expect(result.finish).toMatchObject({ kind: 'error', code })
   })
+})
 
-  it('registers/unregisters models on the llm service (HMR safety)', async () => {
+describe('provider profile lifecycle', () => {
+  it('registers every profile atomically and unregisters on dispose', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    const fiber = await ctx.plugin(LlmPiAi, { apiKey: 'k', baseURL: 'http://127.0.0.1:1' })
-    expect(ctx.llm.models().sort()).toEqual(['deepseek-v4-flash', 'deepseek-v4-pro'])
+    const fiber = await ctx.plugin(LlmPiAi, {
+      providers: [{ provider: 'openai' }, { provider: 'anthropic' }],
+    })
+    expect(ctx.llm.listProviders()).toEqual([
+      { id: 'openai', name: 'openai' },
+      { id: 'anthropic', name: 'anthropic' },
+    ])
     await fiber.dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
-  it('throws a clear error when no API key is available', async () => {
-    const previous = process.env.DEEPSEEK_API_KEY
-    delete process.env.DEEPSEEK_API_KEY
-    try {
-      const ctx = new Context()
-      await ctx.plugin(LlmService)
-      await expect(ctx.plugin(LlmPiAi, {})).rejects.toThrow(/an API key is required/)
-    } finally {
-      if (previous !== undefined) process.env.DEEPSEEK_API_KEY = previous
-    }
-  })
-})
-
-describe('option spreads and env fallbacks', () => {
-  it('forwards temperature, maxTokens, and signal', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url)
-    const controller = new AbortController()
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [],
-      temperature: 0.5,
-      maxTokens: 40,
-      signal: controller.signal,
+  it('exposes the installed pi-ai model catalog through provider-neutral metadata', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(LlmPiAi, { providers: [{ provider: 'openai' }] })
+    const models = await ctx.llm.listModels('openai')
+    expect(models.find(model => model.id === 'gpt-4.1')).toEqual({
+      provider: 'openai', id: 'gpt-4.1', name: 'GPT-4.1',
     })
-    expect(server.requests[0]).toMatchObject({ temperature: 0.5, max_tokens: 40 })
+    expect(models.every(model => model.provider === 'openai')).toBe(true)
   })
 
-  it('falls back to DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL env vars', async () => {
+  it('accepts absent credentials for pi-ai ambient authentication', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', 'ambient-key')
     const server = await mockServer([{ events: textEvents }])
-    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
-    vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
-    try {
-      const ctx = new Context()
-      await ctx.plugin(LlmService)
-      await ctx.plugin(LlmPiAi, { models: ['deepseek-v4-flash'] })
-      await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-      expect(server.requests).toHaveLength(1)
-    } finally {
-      vi.unstubAllEnvs()
+    const ctx = await harness(server.url, { apiKey: undefined })
+    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(server.headers[0]?.authorization).toBe('Bearer ambient-key')
+  })
+
+  it('validates empty, duplicate, unknown, and explicitly blank profiles', () => {
+    expect(() => resolveProfiles([])).toThrow(/at least one/)
+    expect(() => resolveProfiles([{ provider: '' }])).toThrow(/non-empty/)
+    expect(() => resolveProfiles([{ provider: 'not-real' }])).toThrow(/unknown/)
+    expect(() => resolveProfiles([{ provider: 'openai' }, { provider: 'openai' }])).toThrow(/duplicate/)
+    expect(() => resolveProfiles([{ provider: 'openai', apiKey: '' }])).toThrow(/empty apiKey/)
+    expect(() => resolveProfiles([{ provider: 'openai', apiKey: '  ' }])).toThrow(/empty apiKey/)
+    expect(() => resolveProfiles([{ provider: 'openai', baseURL: '' }])).toThrow(/empty baseURL/)
+  })
+
+  it('rejects negative or fractional stream tunables at schema validation', () => {
+    const invalid = [
+      { timeoutMs: -1 },
+      { websocketConnectTimeoutMs: -1 },
+      { maxRetries: -1 },
+      { maxRetries: 0.5 },
+      { maxRetryDelayMs: -1 },
+    ]
+    for (const entry of invalid) {
+      expect(() => new LlmPiAi.Config({ providers: [{ provider: 'openai', ...entry }] })).toThrow()
     }
   })
 
-  it('defaults to the public base URL without config or env', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', 'k')
-    vi.stubEnv('DEEPSEEK_BASE_URL', undefined)
-    try {
-      const ctx = new Context()
-      await ctx.plugin(LlmService)
-      await ctx.plugin(LlmPiAi, {})
-      expect(ctx.llm.models().length).toBeGreaterThan(0)
-    } finally {
-      vi.unstubAllEnvs()
-    }
+  it('constructs the adapter directly and rejects routes it does not own', async () => {
+    const adapter = new PiAiAdapter({ profiles: [{ provider: 'openai' }] })
+    await expect(adapter.listModels('anthropic')).rejects.toMatchObject({ code: 'NO_ADAPTER' })
+    await expect((async () => {
+      for await (const _chunk of adapter.stream({ provider: 'anthropic', model: 'claude-sonnet-4', messages: [] })) { /* drain */ }
+    })()).rejects.toMatchObject({ code: 'NO_ADAPTER' })
+    expect(new LlmError('x', 'X')).toBeInstanceOf(Error)
   })
 })
 
-describe('buildModel', () => {
-  it('builds a DeepSeek-compat openai-completions model descriptor', () => {
-    const model = buildModel('deepseek-v4-pro', { apiKey: 'k', baseURL: 'http://x', reasoning: 'high' })
-    expect(model).toMatchObject({
-      id: 'deepseek-v4-pro',
-      api: 'openai-completions',
+describe('abort wiring', () => {
+  it('resolves catalog endpoints without an override before honoring pre-abort', async () => {
+    const adapter = new PiAiAdapter({ profiles: [{ provider: 'deepseek', apiKey: 'test-key', maxRetries: 0 }] })
+    const controller = new AbortController()
+    controller.abort('already stopped')
+    const chunks = []
+    for await (const chunk of adapter.stream({
       provider: 'deepseek',
-      baseUrl: 'http://x',
-      reasoning: true,
-      compat: { thinkingFormat: 'deepseek', requiresReasoningContentOnAssistantMessages: true },
-    })
-  })
-
-  it('keeps reasoning true even for off (pi-ai gates the thinking field on it)', () => {
-    // 'off' yields {thinking: {type: 'disabled'}} on the wire — pi-ai only
-    // emits the field at all when model.reasoning is true.
-    expect(buildModel('m', { apiKey: 'k', baseURL: 'http://x', reasoning: 'off' }).reasoning).toBe(true)
-  })
-
-  it('adapter is constructible directly for embedding', () => {
-    expect(new PiAiAdapter({ apiKey: 'k', baseURL: 'http://x' })).toBeInstanceOf(PiAiAdapter)
-  })
-})
-
-describe('provider reasoning, passback, and early-stream cancellation', () => {
-  it('defaults omitted reasoning config to thinking ENABLED (provider default)', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url) // no reasoning key at all
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    const request = server.requests[0] as Record<string, unknown>
-    expect(request.thinking).toEqual({ type: 'enabled' })
-    expect('reasoning_effort' in request).toBe(false)
-  })
-
-  it('replays reasoning_content on assistant tool-call turns (passback rule)', async () => {
-    const server = await mockServer([{ events: textEvents }])
-    const ctx = await harness(server.url)
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [
-        { role: 'user', content: [{ type: 'text', text: 'weather?' }] },
-        {
-          role: 'assistant',
-          content: [
-            { type: 'reasoning', text: 'I should check.' },
-            { type: 'tool-call', id: CallId('c1'), name: 'get_weather', arguments: '{"city":"Paris"}' },
-          ],
-        },
-        {
-          role: 'user',
-          content: [{ type: 'tool-result', toolCallId: CallId('c1'), content: [{ type: 'text', text: 'Sunny' }] }],
-        },
-      ],
-    })
-    const request = server.requests[0] as { messages: { role: string; reasoning_content?: string }[] }
-    const assistant = request.messages.find(message => message.role === 'assistant')
-    expect(assistant?.reasoning_content).toBe('I should check.')
-  })
-
-  it('aborts the upstream request when the consumer stops streaming early', async () => {
-    // Slow server: write one chunk, then hold the connection open and record
-    // whether the socket closes (the adapter must cancel on early break).
-    let socketClosed = false
-    const server = createServer((request: IncomingMessage, response: ServerResponse) => {
-      request.on('data', () => undefined)
-      request.on('end', () => {
-        response.writeHead(200, { 'content-type': 'text/event-stream' })
-        response.write(`data: ${textEvents[0]}\n\n`)
-        response.write(`data: ${textEvents[1]}\n\n`)
-        // never finish; rely on client abort
-        request.socket.on('close', () => { socketClosed = true })
-      })
-    })
-    servers.push(server)
-    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
-    const address = server.address()
-    if (address === null || typeof address === 'string') throw new Error('no port')
-    const ctx = await harness(`http://127.0.0.1:${address.port}`)
-
-    for await (const chunk of ctx.llm.stream({ model: 'deepseek-v4-flash', messages: [] })) {
-      if (chunk.type === 'text-delta') break // stop early mid-stream
-    }
-    // The finally-abort must reach the server as a closed socket.
-    await vi.waitFor(() => { expect(socketClosed).toBe(true) }, { timeout: 5_000 })
-  })
-})
-
-describe('caller cancellation', () => {
-  it('honors a pre-aborted caller signal', async () => {
-    const ctx = await harness('http://127.0.0.1:1')
-    const controller = new AbortController()
-    controller.abort('already cancelled')
-    // pi-ai surfaces the abort as an in-stream error event → aborted finish.
-    const result = await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       signal: controller.signal,
-    })
+    })) chunks.push(chunk)
+    expect(chunks.at(-1)).toMatchObject({ type: 'finish', reason: { kind: 'aborted' } })
+  })
+
+  it('honors a pre-aborted caller signal', async () => {
+    const server = await mockServer([{ events: textEvents, delayMs: 20 }])
+    const ctx = await harness(server.url)
+    const controller = new AbortController()
+    controller.abort('already stopped')
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], signal: controller.signal })
     expect(result.finish.kind).toBe('aborted')
   })
 
-  it('propagates a mid-stream caller abort to the upstream request', async () => {
-    const server = await mockServer([{ events: textEvents }])
+  it('forwards an abort that arrives while provider streaming is active', async () => {
+    const server = await mockServer([{ events: textEvents, delayMs: 30 }])
     const ctx = await harness(server.url)
     const controller = new AbortController()
-    const pending = assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [],
-      signal: controller.signal,
+    const resultPromise = assemble(ctx, {
+      model: 'deepseek-v4-flash', messages: [], signal: controller.signal,
     })
-    controller.abort()
-    const result = await pending
-    // Either the abort lands before any chunk (aborted) or after the tiny
-    // mock stream finished (stop) — both are valid races; never a hang.
-    expect(['aborted', 'stop']).toContain(result.finish.kind)
+    setTimeout(() => { controller.abort('stopped during stream') }, 10)
+    const result = await resultPromise
+    expect(result.finish.kind).toBe('aborted')
+  })
+
+  it('aborts upstream when a consumer stops early', async () => {
+    const server = await mockServer([{ events: textEvents, delayMs: 30 }])
+    const ctx = await harness(server.url)
+    for await (const chunk of ctx.llm.stream({ provider: 'deepseek', model: 'deepseek-v4-flash', messages: [] })) {
+      if (chunk.type === 'block-start') break
+    }
+    await new Promise(resolve => setTimeout(resolve, 20))
+    expect(server.requests).toHaveLength(1)
   })
 })

packages/llm/llm-pi-ai/tests/assemble.ts

@@ -15,11 +15,19 @@ export interface AssembledResult {
   finish: FinishReason
 }
 
-export async function assemble(ctx: Context, options: GenerateOptions): Promise<AssembledResult> {
+export async function assemble(ctx: Context, options: Omit<GenerateOptions, 'provider'> & { provider?: string }): Promise<AssembledResult> {
   const assembler = new BlockAssembler()
-  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  const request = { provider: 'deepseek', ...options }
+  for await (const chunk of ctx.llm.stream(request)) assembler.push(chunk)
   return {
-    message: assembler.message(),
+    message: {
+      ...assembler.message(),
+      provenance: {
+        provider: request.provider,
+        model: request.model,
+        ...assembler.replayState === undefined ? {} : { replayState: assembler.replayState },
+      },
+    },
     ...assembler.usage !== undefined ? { usage: assembler.usage } : {},
     finish: assembler.finish,
   }

packages/llm/llm-pi-ai/tests/convert.spec.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { CallId } from '@deepseek-ai/dsh-llm'
+import { CallId, LlmError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { AssistantMessage, AssistantMessageEvent, Usage } from '@earendil-works/pi-ai'
-import { mapStopReason, mapUsage, toPiContext, toStreamChunks } from '@deepseek-ai/dsh-llm-pi-ai'
+import { mapStopReason, mapUsage, toPiContext, toPiReplayState, toStreamChunks } from '@deepseek-ai/dsh-llm-pi-ai'
 
 function usage(input = 0, output = 0, cacheRead = 0, cacheWrite = 0): Usage {
   return {
@@ -42,6 +42,7 @@ async function collect(stream: AsyncIterable<StreamChunk>): Promise<StreamChunk[
 describe('toPiContext', () => {
   it('maps system prompt, user text, and tools', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'deepseek-v4-flash',
       system: 'be helpful',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
@@ -55,13 +56,14 @@ describe('toPiContext', () => {
   })
 
   it('omits empty tools and absent system prompt', () => {
-    const context = toPiContext({ model: 'm', messages: [], tools: [] })
+    const context = toPiContext({ provider: 'deepseek', model: 'm', messages: [], tools: [] })
     expect(context.systemPrompt).toBeUndefined()
     expect(context.tools).toBeUndefined()
   })
 
   it('maps assistant text/reasoning/tool-call blocks', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{
         role: 'assistant',
@@ -76,8 +78,7 @@ describe('toPiContext', () => {
     expect(message.role).toBe('assistant')
     expect(message.stopReason).toBe('toolUse')
     expect(message.content).toEqual([
-      // thinkingSignature names the replay field — DeepSeek's passback rule.
-      { type: 'thinking', thinking: 'hmm', thinkingSignature: 'reasoning_content' },
+      { type: 'thinking', thinking: 'hmm' },
       { type: 'text', text: 'calling' },
       { type: 'toolCall', id: 'c1', name: 'f', arguments: { a: 1 } },
     ])
@@ -85,6 +86,7 @@ describe('toPiContext', () => {
 
   it('marks tool-call-free assistant messages with stopReason stop', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{ role: 'assistant', content: [{ type: 'text', text: 'done' }] }],
     })
@@ -93,6 +95,7 @@ describe('toPiContext', () => {
 
   it('parses malformed tool-call arguments to {}', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{
         role: 'assistant',
@@ -105,6 +108,7 @@ describe('toPiContext', () => {
 
   it('parses non-object argument JSON (arrays, scalars) to {}', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{
         role: 'assistant',
@@ -116,6 +120,7 @@ describe('toPiContext', () => {
 
   it('recovers toolName for tool results from the preceding assistant call', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [
         {
@@ -140,6 +145,7 @@ describe('toPiContext', () => {
 
   it('labels unmatched tool results with toolName unknown and keeps isError', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{
         role: 'user',
@@ -156,6 +162,7 @@ describe('toPiContext', () => {
 
   it('splits mixed user text + tool results and folds history system messages', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [
         { role: 'system', content: [{ type: 'text', text: 'rule' }] },
@@ -173,6 +180,7 @@ describe('toPiContext', () => {
 
   it('skips plugin-added (unknown) blocks in assistant content', () => {
     const context = toPiContext({
+      provider: 'deepseek',
       model: 'm',
       messages: [{
         role: 'assistant',
@@ -184,6 +192,195 @@ describe('toPiContext', () => {
     })
     expect((context.messages[0] as AssistantMessage).content).toEqual([{ type: 'text', text: 'visible' }])
   })
+
+  it('recombines durable content with pi-ai replay metadata across target providers and models', () => {
+    const state = toPiReplayState(assistant({
+      api: 'openai-responses',
+      provider: 'openai',
+      model: 'gpt-5',
+      responseModel: 'gpt-5-2026-01-01',
+      responseId: 'resp_123',
+      stopReason: 'toolUse',
+      content: [
+        { type: 'thinking', thinking: 'private reasoning', thinkingSignature: 'think-sig', redacted: true },
+        { type: 'text', text: 'calling', textSignature: 'text-sig' },
+        { type: 'toolCall', id: 'c1', name: 'f', arguments: { a: 1 }, thoughtSignature: 'tool-sig' },
+      ],
+    }))
+    const context = toPiContext({
+      provider: 'anthropic',
+      model: 'claude-next',
+      messages: [{
+        role: 'assistant',
+        content: [
+          { type: 'reasoning', text: 'private reasoning' },
+          { type: 'text', text: 'calling' },
+          { type: 'tool-call', id: CallId('c1'), name: 'f', arguments: '{"a":1}' },
+        ],
+        provenance: { provider: 'openai', model: 'gpt-5', replayState: state },
+      }],
+    })
+
+    expect(context.messages[0]).toMatchObject({
+      role: 'assistant',
+      api: 'openai-responses',
+      provider: 'openai',
+      model: 'gpt-5',
+      responseModel: 'gpt-5-2026-01-01',
+      responseId: 'resp_123',
+      stopReason: 'toolUse',
+      content: [
+        { type: 'thinking', thinking: 'private reasoning', thinkingSignature: 'think-sig', redacted: true },
+        { type: 'text', text: 'calling', textSignature: 'text-sig' },
+        { type: 'toolCall', id: 'c1', name: 'f', arguments: { a: 1 }, thoughtSignature: 'tool-sig' },
+      ],
+    })
+  })
+
+  it('replays all native block kinds when optional metadata is absent', () => {
+    const state = toPiReplayState(assistant({
+      content: [
+        { type: 'thinking', thinking: 'private reasoning' },
+        { type: 'text', text: 'calling' },
+        { type: 'toolCall', id: 'c1', name: 'f', arguments: { a: 1 } },
+      ],
+    }))
+    const context = toPiContext({
+      provider: 'deepseek',
+      model: 'new-model',
+      messages: [{
+        role: 'assistant',
+        content: [
+          { type: 'reasoning', text: 'private reasoning' },
+          { type: 'text', text: 'calling' },
+          { type: 'tool-call', id: CallId('c1'), name: 'f', arguments: '{"a":1}' },
+        ],
+        provenance: { provider: 'deepseek', model: 'deepseek-v4-flash', replayState: state },
+      }],
+    })
+
+    expect(context.messages[0]).toMatchObject({
+      role: 'assistant',
+      content: [
+        { type: 'thinking', thinking: 'private reasoning' },
+        { type: 'text', text: 'calling' },
+        { type: 'toolCall', id: 'c1', name: 'f', arguments: { a: 1 } },
+      ],
+    })
+    expect(context.messages[0]).not.toHaveProperty('responseModel')
+    expect(context.messages[0]).not.toHaveProperty('responseId')
+  })
+
+  it('rejects unsupported replay-state versions with a stable error code', () => {
+    try {
+      toPiContext({
+        provider: 'deepseek',
+        model: 'm',
+        messages: [{
+          role: 'assistant',
+          content: [{ type: 'text', text: 'done' }],
+          provenance: {
+            provider: 'deepseek',
+            model: 'old',
+            replayState: { kind: 'pi-ai', version: 2 },
+          },
+        }],
+      })
+      expect.fail('expected invalid replay state')
+    } catch (error: unknown) {
+      expect(error).toBeInstanceOf(LlmError)
+      expect((error as LlmError).code).toBe('INVALID_REPLAY_STATE')
+      expect((error as Error).message).toContain('unsupported version 2')
+    }
+  })
+
+  it('rejects replay metadata whose blocks do not match the durable content', () => {
+    const state = toPiReplayState(assistant({ content: [{ type: 'text', text: 'done' }] }))
+    expect(() => toPiContext({
+      provider: 'deepseek',
+      model: 'm',
+      messages: [{
+        role: 'assistant',
+        content: [{ type: 'reasoning', text: 'done' }],
+        provenance: { provider: 'deepseek', model: 'deepseek-v4-flash', replayState: state },
+      }],
+    })).toThrow(/block 0 does not match assistant content/)
+  })
+
+  it('rejects replay metadata whose block count differs from durable content', () => {
+    const state = toPiReplayState(assistant())
+    expect(() => toPiContext({
+      provider: 'deepseek',
+      model: 'm',
+      messages: [{
+        role: 'assistant',
+        content: [{ type: 'text', text: 'done' }],
+        provenance: { provider: 'deepseek', model: 'deepseek-v4-flash', replayState: state },
+      }],
+    })).toThrow(/block count does not match assistant content/)
+  })
+
+  const validReplay = {
+    kind: 'pi-ai',
+    version: 1,
+    api: 'openai-completions',
+    provider: 'deepseek',
+    model: 'deepseek-v4-flash',
+    stopReason: 'stop',
+    blocks: [{ type: 'text' }],
+  }
+
+  it.each([
+    ['provider', { ...validReplay, provider: 'openai' }],
+    ['model', { ...validReplay, model: 'deepseek-v4-pro' }],
+  ])('rejects replay metadata whose %s differs from assistant provenance', (field, replayState) => {
+    try {
+      toPiContext({
+        provider: 'deepseek',
+        model: 'next-model',
+        messages: [{
+          role: 'assistant',
+          content: [{ type: 'text', text: 'done' }],
+          provenance: { provider: 'deepseek', model: 'deepseek-v4-flash', replayState },
+        }],
+      })
+      expect.fail('expected invalid replay state')
+    } catch (error: unknown) {
+      expect(error).toBeInstanceOf(LlmError)
+      expect((error as LlmError).code).toBe('INVALID_REPLAY_STATE')
+      expect((error as Error).message).toContain(`${field} does not match assistant provenance`)
+    }
+  })
+
+  it.each([
+    ['number state', 1, 'expected an object'],
+    ['null state', null, 'expected an object'],
+    ['array state', [], 'expected an object'],
+    ['unknown kind', { ...validReplay, kind: 'other' }, 'unknown state kind'],
+    ['non-string api', { ...validReplay, api: 1 }, 'api must be a non-empty string'],
+    ['empty provider', { ...validReplay, provider: '' }, 'provider must be a non-empty string'],
+    ['missing model', { ...validReplay, model: undefined }, 'model must be a non-empty string'],
+    ['unknown stop reason', { ...validReplay, stopReason: 'pause' }, 'unknown stopReason'],
+    ['non-string response model', { ...validReplay, responseModel: 1 }, 'responseModel must be a string'],
+    ['non-string response id', { ...validReplay, responseId: 1 }, 'responseId must be a string'],
+    ['non-array blocks', { ...validReplay, blocks: 'text' }, 'blocks must be an array'],
+    ['number block', { ...validReplay, blocks: [1] }, 'block 0 must be an object'],
+    ['null block', { ...validReplay, blocks: [null] }, 'block 0 must be an object'],
+    ['array block', { ...validReplay, blocks: [[]] }, 'block 0 must be an object'],
+    ['unknown block type', { ...validReplay, blocks: [{ type: 'audio' }] }, 'block 0 has an unknown type'],
+    ['non-string signature', { ...validReplay, blocks: [{ type: 'text', textSignature: 1 }] }, 'textSignature must be a string'],
+    ['non-boolean redaction', { ...validReplay, blocks: [{ type: 'reasoning', redacted: 'yes' }] }, 'redacted must be boolean'],
+  ])('rejects malformed replay state: %s', (_name, replayState, message) => {
+    expect(() => toPiContext({
+      provider: 'deepseek',
+      model: 'm',
+      messages: [{
+        role: 'assistant',
+        content: [{ type: 'text', text: 'done' }],
+        provenance: { provider: 'deepseek', model: 'deepseek-v4-flash', replayState },
+      }],
+    })).toThrow(message)
+  })
 })
 
 describe('toStreamChunks', () => {
@@ -205,7 +402,19 @@ describe('toStreamChunks', () => {
       { type: 'text-delta', index: 0, text: 'hi' },
       { type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } },
       { type: 'usage', usage: { inputTokens: 3, outputTokens: 2 } },
-      { type: 'finish', reason: { kind: 'stop' } },
+      {
+        type: 'finish',
+        reason: { kind: 'stop' },
+        replayState: {
+          kind: 'pi-ai',
+          version: 1,
+          api: 'openai-completions',
+          provider: 'deepseek',
+          model: 'deepseek-v4-flash',
+          stopReason: 'stop',
+          blocks: [{ type: 'text' }],
+        },
+      },
     ])
   })
 
@@ -234,7 +443,7 @@ describe('toStreamChunks', () => {
         toolCall: { type: 'toolCall', id: 'call-1', name: 'f', arguments: { a: 1 } },
         partial: partialWithToolCall,
       },
-      { type: 'done', reason: 'toolUse', message: assistant({ stopReason: 'toolUse' }) },
+      { type: 'done', reason: 'toolUse', message: assistant({ content: partialWithToolCall.content, stopReason: 'toolUse' }) },
     )))
     expect(chunks).toEqual([
       { type: 'block-start', index: 0, blockType: 'tool-call' },
@@ -242,7 +451,19 @@ describe('toStreamChunks', () => {
       { type: 'tool-call-delta', index: 0, id: 'call-1', name: 'f', argumentsDelta: ':1}' },
       { type: 'block-end', index: 0, block: { type: 'tool-call', id: 'call-1', name: 'f', arguments: '{"a":1}' } },
       { type: 'usage', usage: { inputTokens: 0, outputTokens: 0 } },
-      { type: 'finish', reason: { kind: 'tool-calls' } },
+      {
+        type: 'finish',
+        reason: { kind: 'tool-calls' },
+        replayState: {
+          kind: 'pi-ai',
+          version: 1,
+          api: 'openai-completions',
+          provider: 'deepseek',
+          model: 'deepseek-v4-flash',
+          stopReason: 'toolUse',
+          blocks: [{ type: 'tool-call' }],
+        },
+      },
     ])
   })
 

packages/llm/llm/README.md

@@ -8,10 +8,13 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 
 ### Public API
 
-- `ctx.llm.registerAdapter(models: string[], adapter: LlmAdapter): () => void` Register an adapter for the given model names. Disposed with the calling fiber.
-- `ctx.llm.models(): string[]` — model names with a registered adapter.
+- `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): () => void` Register one adapter instance for the given provider routes. Registration is all-or-nothing, and is disposed with the calling fiber.
+- `ctx.llm.listProviders(): LlmProviderInfo[]` Describe registered provider routes in registration order.
+- `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
+Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
+
 ### Events
 
 | Event | Mode | Purpose |
@@ -20,18 +23,18 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
 
 ### Extension points
 
-- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(models, adapter)` to add a new model provider.
+- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(providers, adapter)` to add one or more provider routes. `GenerateOptions.provider` selects the adapter; `GenerateOptions.model` is adapter-owned and may be resolved dynamically. Override `providerInfo()` and asynchronous `listModels()` to expose selector metadata; their defaults use the route id as its name and advertise no models.
 - Wrap `llm/stream` via `ctx.on()` waterfall listeners for caching, retry, logging, rate-limiting, etc.
 
 ### Content-block vocabulary (`types.ts`)
 
-Messages are arrays of typed content blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
+Messages are arrays of typed content blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages produced by the loop also carry provider/model provenance and optional adapter-private replay state. Before dispatch, `LlmService` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
 
 Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages.
 
 ### Call configuration (`call-config.ts`)
 
-`LlmCallConfig` is the model + sampling scalars of one conversation's requests (`model`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement and the loop logs a real change. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite).
+`LlmCallConfig` is the provider + model + sampling scalars of one conversation's requests (`provider`, `model`, `temperature`, `maxTokens`, `stop` — each mapping 1:1 onto the same-named `GenerateOptions` field). It is per-conversation state recorded in the session log as part of the request header (see the dsh-session `request/header` events), never a silently-adjustable per-call knob: the `agent/request` waterfall proposes a replacement and the loop logs a real change. `callConfigEquals(a, b)` is the field-wise real-change detector; `deepFreeze(value)` is the ownership helper the loop applies to every built request before dispatch (`llm/stream` listeners and adapters read, never rewrite).
 
 ### App attribution (`attribution.ts`)
 
@@ -46,7 +49,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 
 ### Real adapters
 
-Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses hand-rolled fetch/SSE, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) uses `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish, tool arguments remain raw strings, and errors take one of two sanctioned paths. See [the twin LLM adapters](../../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the design rationale.
+Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses hand-rolled fetch/SSE for the `deepseek` route, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) dynamically resolves configured provider/model pairs through `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish, tool arguments remain raw strings, and errors take one of two sanctioned paths. See [the twin LLM adapters](../../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the design rationale.
 
 ## Model Experience
 

packages/llm/llm/src/assembler.ts

@@ -36,6 +36,7 @@ export class BlockAssembler {
   private order: number[] = []
   private _usage: TokenUsage | undefined
   private _finish: FinishReason | undefined
+  private _replayState: unknown = undefined
 
   /**
    * Feed one chunk. Returns the completed block when the chunk closes one
@@ -85,6 +86,7 @@ export class BlockAssembler {
       }
       case 'finish': {
         this._finish = chunk.reason
+        this._replayState = chunk.replayState
         return
       }
       default: return assertNever(chunk, 'BlockAssembler.push')
@@ -142,6 +144,11 @@ export class BlockAssembler {
     return this._finish ?? { kind: 'stop' }
   }
 
+  /** Adapter-private replay state from the terminal finish chunk, if any. */
+  get replayState(): unknown {
+    return this._replayState
+  }
+
   /**
    * The assembled assistant message.
    * @returns an assistant-role message over `blocks()` (same open-block assembly rules).

packages/llm/llm/src/call-config.ts

@@ -1,17 +1,18 @@
 /**
- * Conversation call configuration and freeze utilities. Model and sampling
- * values are request-header state that can affect cache reuse; request
- * waterfalls replace them and the loop logs changed snapshots instead of
- * allowing silent per-call drift.
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, and sampling values are request-header state that can affect cache
+ * reuse; request waterfalls replace them and the loop logs changed snapshots
+ * instead of allowing silent per-call drift.
  * @module dsh-llm/call-config
  */
 
 /**
- * Model + sampling scalars of one conversation's requests. Every field maps
+ * Provider + model + sampling scalars of one conversation's requests. Every field maps
  * 1:1 onto the same-named `GenerateOptions` field; the loop builds requests
  * from the logged header rather than accepting these per call.
  */
 export interface LlmCallConfig {
+  provider: string
   model: string
   temperature?: number
   maxTokens?: number
@@ -27,7 +28,7 @@ export interface LlmCallConfig {
  * @returns whether every field (including the `stop` list, element-wise) matches.
  */
 export function callConfigEquals(a: LlmCallConfig, b: LlmCallConfig): boolean {
-  if (a.model !== b.model || a.temperature !== b.temperature || a.maxTokens !== b.maxTokens) return false
+  if (a.provider !== b.provider || a.model !== b.model || a.temperature !== b.temperature || a.maxTokens !== b.maxTokens) return false
   if (a.stop === undefined || b.stop === undefined) return a.stop === b.stop
   return a.stop.length === b.stop.length && a.stop.every((s, i) => s === b.stop?.[i])
 }

packages/llm/llm/src/index.ts

@@ -7,8 +7,9 @@
  */
 
 import { Context, Service } from 'cordis'
-import type { GenerateOptions, StreamChunk } from './types.ts'
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, Message, StreamChunk } from './types.ts'
 import { HarnessError } from './error.ts'
+import { deepFreeze } from './call-config.ts'
 
 export * from './attribution.ts'
 export * from './brand.ts'
@@ -55,11 +56,31 @@ export class LlmError extends HarnessError {
 
 /**
  * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
- * with `ctx.llm.registerAdapter(models, adapter)`. Every provider HTTP request must include
+ * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
  * `attributionHeaders()`; prove that at the wire or library header-hook boundary. The hand-rolled
  * DeepSeek and pi-ai adapters intentionally exercise this contract through different internals.
  */
 export abstract class LlmAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route passed to `registerAdapter()` for this instance.
+   * @returns detached display metadata whose id must equal `provider`.
+   */
+  providerInfo(provider: string): LlmProviderInfo {
+    return { id: provider, name: provider }
+  }
+
+  /**
+   * List models this adapter can currently advertise for one owned provider.
+   * The result is advisory: an adapter may accept unlisted model ids, and
+   * consumers must not turn absence into request rejection.
+   * @param _provider - one provider route owned by this adapter.
+   * @returns discoverable models in adapter-preferred order.
+   */
+  listModels(_provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve([])
+  }
+
   /**
    * Stream one model call as raw chunks. The only required method.
    * @param options - the fully-assembled request; implementations must honor `options.signal`.
@@ -73,30 +94,40 @@ export abstract class LlmAdapter {
  * surface, interceptable via the `llm/stream` waterfall.
  */
 export class LlmService extends Service {
-  private adapters = new Map<string, LlmAdapter>()
+  private adapters = new Map<string, { adapter: LlmAdapter; provider: LlmProviderInfo }>()
 
   constructor(ctx: Context) {
     super(ctx, 'llm')
   }
 
   /**
-   * Register an adapter for the given model names. Throws `LlmError` with code
-   * `DUPLICATE_ADAPTER` if any model already has an adapter (all-or-nothing).
+   * Register an adapter for the given provider routes. Throws `LlmError` with code
+   * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
    * Disposed with the fiber.
-   * @param models - every model name this adapter should serve.
-   * @param adapter - the adapter that streams calls for those models.
+   * @param providers - every provider route this adapter should serve.
+   * @param adapter - the adapter that streams calls for those providers.
    * @returns the disposer that unregisters all of them.
    */
-  registerAdapter(models: string[], adapter: LlmAdapter): () => void {
+  registerAdapter(providers: string[], adapter: LlmAdapter): () => void {
     const dispose = this.ctx.effect(function* (this: LlmService) {
-      for (const model of models) {
-        if (this.adapters.has(model)) {
-          throw new LlmError(`an adapter for model "${model}" is already registered`, 'DUPLICATE_ADAPTER')
+      if (providers.length === 0) throw new LlmError('an adapter must register at least one provider', 'INVALID_ADAPTER')
+      const unique = new Set<string>()
+      const registrations: { adapter: LlmAdapter; provider: LlmProviderInfo }[] = []
+      for (const provider of providers) {
+        if (provider.length === 0) throw new LlmError('adapter provider names must be non-empty', 'INVALID_ADAPTER')
+        if (unique.has(provider) || this.adapters.has(provider)) {
+          throw new LlmError(`an adapter for provider "${provider}" is already registered`, 'DUPLICATE_ADAPTER')
         }
+        const info = adapter.providerInfo(provider)
+        if (typeof info.id !== 'string' || info.id !== provider || typeof info.name !== 'string' || info.name.length === 0) {
+          throw new LlmError(`adapter metadata for provider "${provider}" must preserve its id and have a non-empty name`, 'INVALID_ADAPTER')
+        }
+        unique.add(provider)
+        registrations.push({ adapter, provider: { id: info.id, name: info.name } })
       }
-      for (const model of models) this.adapters.set(model, adapter)
+      for (const registration of registrations) this.adapters.set(registration.provider.id, registration)
       yield () => {
-        for (const model of models) this.adapters.delete(model)
+        for (const provider of providers) this.adapters.delete(provider)
       }
     }.bind(this), 'llm.registerAdapter()')
     // ctx.effect's disposer returns Promise<void>; our disposer API is
@@ -105,29 +136,81 @@ export class LlmService extends Service {
   }
 
   /**
-   * Model names with a registered adapter.
-   * @returns the registered names, in registration order.
+   * Describe provider routes with a registered adapter.
+   * @returns detached provider metadata in registration order.
    */
-  models(): string[] {
-    return [...this.adapters.keys()]
+  listProviders(): LlmProviderInfo[] {
+    return [...this.adapters.values()].map(({ provider }) => ({ ...provider }))
   }
 
-  private adapter(model: string): LlmAdapter {
-    const adapter = this.adapters.get(model)
-    if (!adapter) throw new LlmError(`no adapter registered for model "${model}"`, 'NO_ADAPTER')
-    return adapter
+  /**
+   * Discover models advertised by one registered provider. Catalog membership
+   * is advisory and never changes routing or request validation.
+   * @param provider - registered provider route to inspect.
+   * @returns detached model metadata in adapter-preferred order.
+   */
+  async listModels(provider: string): Promise<LlmModelInfo[]> {
+    const adapter = this.registration(provider).adapter
+    const models = await adapter.listModels(provider)
+    const seen = new Set<string>()
+    return models.map((model) => {
+      if (
+        typeof model.provider !== 'string'
+        || model.provider !== provider
+        || typeof model.id !== 'string'
+        || model.id.length === 0
+        || typeof model.name !== 'string'
+        || model.name.length === 0
+        || (model.description !== undefined && typeof model.description !== 'string')
+        || seen.has(model.id)
+      ) {
+        throw new LlmError(`adapter returned invalid or duplicate model metadata for provider "${provider}"`, 'INVALID_CATALOG')
+      }
+      seen.add(model.id)
+      return {
+        provider: model.provider,
+        id: model.id,
+        name: model.name,
+        ...model.description === undefined ? {} : { description: model.description },
+      }
+    })
+  }
+
+  private registration(provider: string): { adapter: LlmAdapter; provider: LlmProviderInfo } {
+    const registration = this.adapters.get(provider)
+    if (!registration) throw new LlmError(`no adapter registered for provider "${provider}"`, 'NO_ADAPTER')
+    return registration
+  }
+
+  /** Remove replay state whose historical route is owned by another adapter. */
+  private forAdapter(options: GenerateOptions, adapter: LlmAdapter): GenerateOptions {
+    const messages: Message[] = options.messages.map((message) => {
+      const provenance = message.provenance
+      if (message.role !== 'assistant' || provenance?.replayState === undefined) return message
+      if (this.adapters.get(provenance.provider)?.adapter === adapter) return message
+      return {
+        ...message,
+        provenance: { provider: provenance.provider, model: provenance.model },
+      }
+    })
+    if (messages.every((message, index) => message === options.messages[index])) return options
+    const filtered = { ...options, messages }
+    return Object.isFrozen(options) ? deepFreeze(filtered) : filtered
   }
 
   /**
    * Stream one model call as raw chunks (token-level deltas). Throws
    * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
-   * `options.model`. Dispatches through the `llm/stream` waterfall.
-   * @param options - the full request; `options.model` selects the adapter.
+   * `options.provider`. Replay state is retained only when the same adapter
+   * instance owns its historical provider and the target provider. Dispatches
+   * through the `llm/stream` waterfall.
+   * @param options - the full request; `options.provider` selects the adapter.
    * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
    */
   stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     return this.ctx.waterfall(this, 'llm/stream', options, () => {
-      return this.adapter(options.model).stream(options)
+      const adapter = this.registration(options.provider).adapter
+      return adapter.stream(this.forAdapter(options, adapter))
     })
   }
 }

packages/llm/llm/src/types.ts

@@ -53,10 +53,29 @@ export type ContentBlockType = keyof ContentBlockMap
 /** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
 export type ContentBlock = ContentBlockMap[ContentBlockType]
 
-/** A single message in a conversation history. */
+/** Provider ownership and adapter-private replay data for an assistant message. */
+export interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string
+  /** Provider model id that produced the message. */
+  model: string
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmService` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown
+}
+
+/**
+ * A single message in a conversation history. Loop-derived assistant messages
+ * always carry provenance; callers may omit it on hand-built foreign history.
+ */
 export interface Message {
   role: 'system' | 'user' | 'assistant'
   content: ContentBlock[]
+  /** Present only on assistant messages produced by a routed adapter. */
+  provenance?: AssistantProvenance
 }
 
 /**
@@ -102,6 +121,26 @@ export interface TokenUsage {
   reasoningTokens?: number
 }
 
+/** Display metadata for one registered provider route. */
+export interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string
+}
+
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+export interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string
+  /** Human-readable model name for selectors. */
+  name: string
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string
+}
+
 /**
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
@@ -116,7 +155,12 @@ export type StreamChunk =
   | { type: 'tool-call-delta'; index: number; id: CallId; name?: string; argumentsDelta: string }
   | { type: 'block-end'; index: number; block: ContentBlock }
   | { type: 'usage'; usage: TokenUsage }
-  | { type: 'finish'; reason: FinishReason }
+  | {
+    type: 'finish'
+    reason: FinishReason
+    /** Adapter-private lossless-JSON state for replaying a successful response. */
+    replayState?: unknown
+  }
 
 /**
  * JSON-schema description of a tool, as sent to the model.
@@ -134,6 +178,8 @@ export interface ToolSchema {
 
 /** A single model request, fully assembled. */
 export interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string
   model: string
   /**
    * Ordered conversation messages, exactly as the provider sees them (after

packages/llm/llm/tests/call-config.spec.ts

@@ -9,14 +9,16 @@ import { callConfigEquals, deepFreeze } from '../src/call-config.ts'
 
 describe('callConfigEquals', () => {
   it('compares every field, including the stop list element-wise', () => {
-    expect(callConfigEquals({ model: 'm' }, { model: 'm' })).toBe(true)
-    expect(callConfigEquals({ model: 'm' }, { model: 'x' })).toBe(false)
-    expect(callConfigEquals({ model: 'm', temperature: 0.5 }, { model: 'm' })).toBe(false)
-    expect(callConfigEquals({ model: 'm', maxTokens: 1 }, { model: 'm', maxTokens: 2 })).toBe(false)
-    expect(callConfigEquals({ model: 'm', stop: ['a'] }, { model: 'm' })).toBe(false)
-    expect(callConfigEquals({ model: 'm', stop: ['a'] }, { model: 'm', stop: ['a', 'b'] })).toBe(false)
-    expect(callConfigEquals({ model: 'm', stop: ['a'] }, { model: 'm', stop: ['b'] })).toBe(false)
-    expect(callConfigEquals({ model: 'm', stop: ['a', 'b'] }, { model: 'm', stop: ['a', 'b'] })).toBe(true)
+    const base = { provider: 'p', model: 'm' }
+    expect(callConfigEquals(base, base)).toBe(true)
+    expect(callConfigEquals(base, { provider: 'x', model: 'm' })).toBe(false)
+    expect(callConfigEquals(base, { provider: 'p', model: 'x' })).toBe(false)
+    expect(callConfigEquals({ ...base, temperature: 0.5 }, base)).toBe(false)
+    expect(callConfigEquals({ ...base, maxTokens: 1 }, { ...base, maxTokens: 2 })).toBe(false)
+    expect(callConfigEquals({ ...base, stop: ['a'] }, base)).toBe(false)
+    expect(callConfigEquals({ ...base, stop: ['a'] }, { ...base, stop: ['a', 'b'] })).toBe(false)
+    expect(callConfigEquals({ ...base, stop: ['a'] }, { ...base, stop: ['b'] })).toBe(false)
+    expect(callConfigEquals({ ...base, stop: ['a', 'b'] }, { ...base, stop: ['a', 'b'] })).toBe(true)
   })
 })
 

packages/llm/llm/tests/service.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { GenerateOptions, LlmAdapter, LlmError, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
 
 class ScriptedAdapter extends LlmAdapter {
   constructor(private script: StreamChunk[]) {
@@ -12,6 +13,32 @@ class ScriptedAdapter extends LlmAdapter {
   }
 }
 
+class RecordingAdapter extends ScriptedAdapter {
+  lastOptions: GenerateOptions | undefined
+
+  override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.lastOptions = options
+    yield * super.stream(options)
+  }
+}
+
+class CatalogAdapter extends ScriptedAdapter {
+  constructor(
+    private readonly provider: LlmProviderInfo,
+    private readonly models: readonly LlmModelInfo[],
+  ) {
+    super(SCRIPT)
+  }
+
+  override providerInfo(_provider: string): LlmProviderInfo {
+    return this.provider
+  }
+
+  override listModels(_provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve(this.models)
+  }
+}
+
 const SCRIPT: StreamChunk[] = [
   { type: 'block-start', index: 0, blockType: 'text' },
   { type: 'text-delta', index: 0, text: 'hi' },
@@ -22,18 +49,18 @@ describe('LlmService', () => {
   it('routes stream() to the registered adapter', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT))
+    ctx.llm.registerAdapter(['test-provider'], new ScriptedAdapter(SCRIPT))
 
     const chunks: StreamChunk[] = []
-    for await (const chunk of ctx.llm.stream({ model: 'test-model', messages: [] })) chunks.push(chunk)
+    for await (const chunk of ctx.llm.stream({ provider: 'test-provider', model: 'test-model', messages: [] })) chunks.push(chunk)
     expect(chunks).toEqual(SCRIPT)
   })
 
-  it('throws NO_ADAPTER for unregistered models', async () => {
+  it('throws NO_ADAPTER for unregistered providers', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await expect((async () => {
-      for await (const _ of ctx.llm.stream({ model: 'nope', messages: [] })) { /* drain */ }
+      for await (const _ of ctx.llm.stream({ provider: 'nope', model: 'any-model', messages: [] })) { /* drain */ }
     })()).rejects.toThrow('no adapter registered')
   })
 
@@ -44,10 +71,80 @@ describe('LlmService', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       inner.llm.registerAdapter(['scoped-model'], new ScriptedAdapter(SCRIPT))
     }, { inject: ['llm'] }))
-    expect(ctx.llm.models()).toEqual(['scoped-model'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'scoped-model', name: 'scoped-model' }])
 
     await fiber.dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
+  it('discovers detached provider and advisory model metadata', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const provider = { id: 'catalog', name: 'Catalog Provider' }
+    const model = { provider: 'catalog', id: 'fast', name: 'Fast', description: 'Low latency' }
+    ctx.llm.registerAdapter(['catalog'], new CatalogAdapter(provider, [model]))
+
+    const providers = ctx.llm.listProviders()
+    const models = await ctx.llm.listModels('catalog')
+    expect(providers).toEqual([provider])
+    expect(models).toEqual([model])
+
+    providers[0]!.name = 'mutated'
+    models[0]!.name = 'mutated'
+    provider.name = 'source mutated'
+    model.name = 'source mutated'
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'catalog', name: 'Catalog Provider' }])
+    await expect(ctx.llm.listModels('catalog')).resolves.toEqual([{
+      provider: 'catalog', id: 'fast', name: 'source mutated', description: 'Low latency',
+    }])
+  })
+
+  it('defaults adapters to their route name and an empty advisory model list', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['plain'], new ScriptedAdapter(SCRIPT))
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'plain', name: 'plain' }])
+    await expect(ctx.llm.listModels('plain')).resolves.toEqual([])
+    await expect(ctx.llm.listModels('missing')).rejects.toMatchObject({ code: 'NO_ADAPTER' })
+  })
+
+  it.each([
+    [{ id: 1, name: 'Name' }, 'non-string id'],
+    [{ id: 'other', name: 'Name' }, 'mismatched id'],
+    [{ id: 'route', name: 1 }, 'non-string name'],
+    [{ id: 'route', name: '' }, 'empty name'],
+  ] as const)('rejects invalid provider metadata atomically (%s: %s)', async (metadata, _label) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const adapter = new CatalogAdapter(metadata as unknown as LlmProviderInfo, [])
+    expect(() => ctx.llm.registerAdapter(['route'], adapter)).toThrow(expect.objectContaining({ code: 'INVALID_ADAPTER' }))
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
+  it.each([
+    [{ provider: 1, id: 'm', name: 'M' }, 'non-string provider'],
+    [{ provider: 'other', id: 'm', name: 'M' }, 'mismatched provider'],
+    [{ provider: 'route', id: 1, name: 'M' }, 'non-string id'],
+    [{ provider: 'route', id: '', name: 'M' }, 'empty id'],
+    [{ provider: 'route', id: 'm', name: 1 }, 'non-string name'],
+    [{ provider: 'route', id: 'm', name: '' }, 'empty name'],
+    [{ provider: 'route', id: 'm', name: 'M', description: 1 }, 'non-string description'],
+  ] as const)('rejects invalid model metadata (%s: %s)', async (metadata, _label) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['route'], new CatalogAdapter(
+      { id: 'route', name: 'Route' },
+      [metadata as unknown as LlmModelInfo],
+    ))
+    await expect(ctx.llm.listModels('route')).rejects.toMatchObject({ code: 'INVALID_CATALOG' })
+  })
+
+  it('rejects duplicate model ids in one provider catalog', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const model = { provider: 'route', id: 'same', name: 'Same' }
+    ctx.llm.registerAdapter(['route'], new CatalogAdapter({ id: 'route', name: 'Route' }, [model, model]))
+    await expect(ctx.llm.listModels('route')).rejects.toMatchObject({ code: 'INVALID_CATALOG' })
   })
 
   it('lets llm/stream waterfall listeners wrap the underlying stream', async () => {
@@ -64,11 +161,90 @@ describe('LlmService', () => {
     })
 
     const chunks: StreamChunk[] = []
-    for await (const chunk of ctx.llm.stream({ model: 'test-model', messages: [] })) chunks.push(chunk)
+    for await (const chunk of ctx.llm.stream({ provider: 'test-model', model: 'dynamic-model', messages: [] })) chunks.push(chunk)
     expect(chunks).toHaveLength(4)
     expect(chunks[0]).toMatchObject({ index: 99 })
   })
 
+  it('resolves the provider after llm/stream listeners have had a chance to route it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const adapter = new RecordingAdapter(SCRIPT)
+    ctx.llm.registerAdapter(['routed'], adapter)
+    ctx.on('llm/stream', (options, next) => {
+      options.provider = 'routed'
+      return next()
+    })
+
+    for await (const _chunk of ctx.llm.stream({ provider: 'initial', model: 'm', messages: [] })) { /* drain */ }
+    expect(adapter.lastOptions?.provider).toBe('routed')
+  })
+
+  it('keeps replay state when historical and target providers belong to the same adapter instance', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const adapter = new RecordingAdapter(SCRIPT)
+    ctx.llm.registerAdapter(['historical', 'target'], adapter)
+    const replayState = { private: 'state' }
+
+    for await (const _chunk of ctx.llm.stream({
+      provider: 'target',
+      model: 'new-model',
+      messages: [{
+        role: 'assistant',
+        content: [{ type: 'text', text: 'old response' }],
+        provenance: { provider: 'historical', model: 'old-model', replayState },
+      }],
+    })) { /* drain */ }
+
+    expect(adapter.lastOptions?.messages[0]?.provenance).toEqual({
+      provider: 'historical', model: 'old-model', replayState,
+    })
+  })
+
+  it('strips replay state but preserves provenance when the target uses a different adapter instance', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['historical'], new RecordingAdapter(SCRIPT))
+    const target = new RecordingAdapter(SCRIPT)
+    ctx.llm.registerAdapter(['target'], target)
+
+    for await (const _chunk of ctx.llm.stream({
+      provider: 'target',
+      model: 'new-model',
+      messages: [{
+        role: 'assistant',
+        content: [{ type: 'text', text: 'old response' }],
+        provenance: { provider: 'historical', model: 'old-model', replayState: { private: 'state' } },
+      }],
+    })) { /* drain */ }
+
+    expect(target.lastOptions?.messages[0]?.provenance).toEqual({ provider: 'historical', model: 'old-model' })
+  })
+
+  it('preserves immutability while stripping replay state from frozen requests', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['historical'], new RecordingAdapter(SCRIPT))
+    const target = new RecordingAdapter(SCRIPT)
+    ctx.llm.registerAdapter(['target'], target)
+    const options = Object.freeze({
+      provider: 'target',
+      model: 'new-model',
+      messages: [{
+        role: 'assistant' as const,
+        content: [{ type: 'text' as const, text: 'old response' }],
+        provenance: { provider: 'historical', model: 'old-model', replayState: { private: 'state' } },
+      }],
+    })
+
+    for await (const _chunk of ctx.llm.stream(options)) { /* drain */ }
+
+    expect(target.lastOptions).not.toBe(options)
+    expect(Object.isFrozen(target.lastOptions)).toBe(true)
+    expect(target.lastOptions?.messages[0]?.provenance).toEqual({ provider: 'historical', model: 'old-model' })
+  })
+
   it('creates LlmError with a code for programmatic handling', () => {
     const err = new LlmError('something went wrong', 'CUSTOM_CODE')
     expect(err).toBeInstanceOf(Error)
@@ -104,9 +280,9 @@ describe('LlmService', () => {
     await ctx.plugin(LlmService)
 
     const dispose = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
-    expect(ctx.llm.models()).toEqual(['m1'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'm1', name: 'm1' }])
     dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 
   it('rejects duplicate adapter registration with DUPLICATE_ADAPTER code', async () => {
@@ -123,19 +299,30 @@ describe('LlmService', () => {
     }
   })
 
+  it('rejects empty and internally duplicated provider registrations atomically', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    const adapter = new ScriptedAdapter(SCRIPT)
+
+    expect(() => ctx.llm.registerAdapter([], adapter)).toThrow(expect.objectContaining({ code: 'INVALID_ADAPTER' }))
+    expect(() => ctx.llm.registerAdapter([''], adapter)).toThrow(expect.objectContaining({ code: 'INVALID_ADAPTER' }))
+    expect(() => ctx.llm.registerAdapter(['first', 'first'], adapter)).toThrow(expect.objectContaining({ code: 'DUPLICATE_ADAPTER' }))
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
   it('re-registers a model after its prior registration is disposed', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
 
     const dispose = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
-    expect(ctx.llm.models()).toEqual(['m1'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'm1', name: 'm1' }])
     dispose()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
 
     // The duplicate check is not wedged: the same model registers cleanly again.
     const disposeAgain = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
-    expect(ctx.llm.models()).toEqual(['m1'])
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'm1', name: 'm1' }])
     disposeAgain()
-    expect(ctx.llm.models()).toEqual([])
+    expect(ctx.llm.listProviders()).toEqual([])
   })
 })

packages/sdk/helper/src/features/builtin/index.ts

@@ -23,6 +23,7 @@ const compactPreset = {
   contextWindow: 128_000,
   thresholdRatio: 0.8,
   retainTokens: 20_480,
+  summarizationProvider: '',
   summarizationModel: '',
   maxTokens: 8_192,
   compactionRetries: 1,

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -184,7 +184,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
       { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
       { type: 'assistant/chunk', seq: 2, time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'he' } } },
       { type: 'assistant/chunk', seq: 3, time: 4, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'llo' } } },
-      { type: 'assistant/message', seq: 4, time: 5, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'hello' }] }, surfaceOp: 'append', sourceEventSeqs: [2, 3] },
+      { type: 'assistant/message', seq: 4, time: 5, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'hello' }], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: 'append', sourceEventSeqs: [2, 3] },
       { type: 'step/end', seq: 5, time: 6, data: { turn: 1, step: 1 } },
       { type: 'turn/end', seq: 6, time: 7, data: { turn: 1, reason: { kind: 'completed' } } },
     ]

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -513,7 +513,7 @@ describe('surface field round-trip', () => {
     const session = ctx.sessions.create(SessionId('roundtrip-surface'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [0] })
+    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [0] })
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
     await ctx.parallel('session/flush', session)
     const loaded = await ctx.sessionPersistence.load(SessionId('roundtrip-surface'))

packages/session-persistence/session-persistence/tests/contract.ts

@@ -36,7 +36,7 @@ export function oneTurnLog(): SessionEvent[] {
     { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
     { type: 'user/message', seq: 1, time: 2, data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, surfaceOp: 'append' },
     { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
-    { type: 'assistant/message', seq: 3, time: 4, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'hello' }] }, surfaceOp: 'append' },
+    { type: 'assistant/message', seq: 3, time: 4, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'hello' }], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: 'append' },
     { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
     { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
   ]
@@ -136,7 +136,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           { type: 'step/start', seq: 7, time: 8, data: { turn: 2, step: 1 } },
           { type: 'assistant/message', seq: 8, time: 9, data: { turn: 2, step: 1, content: [
             { type: 'tool-call', id: CallId('call-x'), name: 'bash', arguments: '{}' },
-          ] } },
+          ], provenance: { provider: 'mock', model: 'mock' } } },
         ])
 
         const loaded = await persistence.load(m.id)

packages/session-query/session-query/tests/session-query.spec.ts

@@ -113,7 +113,7 @@ describe('session-query exact reads', () => {
     })
     session.append(
       'assistant/message',
-      { turn: 1, step: 1, content: [{ type: 'text', text: 'replacement' }] },
+      { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'replacement' }] },
       { surfaceOp: { op: 'replace', start: first.seq, end: first.seq }, sourceEventSeqs: [first.seq] },
     )
 
@@ -235,7 +235,7 @@ describe('session-query exact reads', () => {
       type: 'assistant/message',
       seq: 0,
       time: 1,
-      data: { turn: 1, step: 1, content: [] },
+      data: { turn: 1, step: 1, content: [], provenance: { provider: 'mock', model: 'mock' } },
       surfaceOp: { op: 'replace', start: 9, end: 9 },
     })
     await expect(ctx.sessionQuery.listEvents(session.id))

packages/session-query/session-query/tests/tracing.spec.ts

@@ -101,7 +101,7 @@ function appendTraceEvents(session: Session): void {
   )
   session.append(
     'assistant/message',
-    { turn: 1, step: 1, content: [{ type: 'text', text: 'summary one' }] },
+    { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary one' }] },
     { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1, 0] },
   )
   session.append(
@@ -111,7 +111,7 @@ function appendTraceEvents(session: Session): void {
   )
   session.append(
     'assistant/message',
-    { turn: 1, step: 2, content: [{ type: 'text', text: 'summary two' }] },
+    { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 2, content: [{ type: 'text', text: 'summary two' }] },
     { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [0, 2] },
   )
 }
@@ -338,7 +338,7 @@ describe('session event tracing', () => {
       type: 'assistant/message',
       seq: 1,
       time: 2,
-      data: { turn: 1, step: 1, content: [] },
+      data: { turn: 1, step: 1, content: [], provenance: { provider: 'mock', model: 'mock' } },
       surfaceOp: { op: 'replace', start: 9, end: 9 },
       sourceEventSeqs: [],
     }]

packages/subagent/subagent-fork/tests/multi-subagent.spec.ts

@@ -30,7 +30,7 @@ async function setup(script: Script) {
   await ctx.plugin(Spawn, { providerName: 'spawn' })
   await ctx.plugin(fork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 

packages/subagent/subagent-fork/tests/subagent-fork.spec.ts

@@ -36,7 +36,7 @@ async function setup(script: Script) {
   await ctx.plugin(SubagentService)
   await ctx.plugin(fork, { providerName: 'fork' })
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }
 

packages/subagent/subagent-inprocess/src/index.ts

@@ -107,8 +107,10 @@ export async function startInProcessRun(
   const childId = AgentId(randomUUID())
   const seedLength = options.seed?.length ?? 0
   const parentHeader = parent.session.header
+  const parentProvider = parent.options.provider
   const parentModel = parent.options.model
   const agentOptions: AgentOptions = {
+    ...parentProvider !== undefined ? { provider: parentProvider } : {},
     ...parentModel !== undefined ? { model: parentModel } : {},
     ...request.agentOptions,
     subagentDepth: childDepth,

packages/subagent/subagent-inprocess/tests/structured.spec.ts

@@ -61,7 +61,7 @@ async function setup(script: Script, options: SetupOptions = {}) {
     start: (request: SubagentStartRequest) => startInProcessRun(request, {}),
   })
   ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent, adapter, disposeProvider }
 }
 

packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts

@@ -17,7 +17,7 @@ async function setup(script: Script) {
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(SubagentService)
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' })
+  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
 }