Merge current master into invariant service seam

packages/core/agent/README.md

@@ -10,7 +10,7 @@ Tracks live agents and carries the initiating Agent through asynchronous driver
 
 ### Public API
 
-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `installAgentLlmTarget(agentCtx, target)` snapshots a mutable provider/model selection during prompt assembly and applies that pair to both prompt variables and request routing for one step. `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
 - Advanced ordered lifecycle: `enter(agent, owner): () => void` enforces `agent.id === agent.session.id`, performs the authoritative ID collision check, and inserts without announcing; `owner` explicitly records the live creator-agent relation (or `undefined` for a root), independently of durable session lineage. `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.

packages/core/agent/src/index.ts

@@ -15,6 +15,7 @@ import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
+export * from './llm-target.ts'
 export { agentEvents, assembleContextFor } from './dispatch.ts'
 export type { AgentEventDispatch, AgentSubjectEvent } from './dispatch.ts'
 

packages/core/agent/src/llm-target.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent-scoped provider/model target snapshot shared by interactive front doors.
+ * @module @deepseek-ai/dsh-agent/llm-target
+ */
+
+import type { Context } from 'cordis'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+/** Complete provider/model route selected for one live agent. */
+export interface AgentLlmTarget {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+
+/** Mutable selection plus the target captured for the current step. */
+export interface AgentLlmTargetRef {
+  /** Target selected for the next step that enters prompt assembly. */
+  current: AgentLlmTarget | undefined
+  /** Target captured when the current step entered prompt assembly. */
+  assembled: AgentLlmTarget | undefined
+}
+
+/**
+ * Couple one mutable target to agent-scoped prompt assembly and request routing.
+ * Prompt assembly snapshots the selected pair before delegating, then applies
+ * both prompt variables and request config to that snapshot so a concurrent
+ * switch takes effect on a later step instead of splitting the two surfaces.
+ *
+ * @param agentCtx - The target agent's scoped context.
+ * @param target - Mutable selection owned by the calling front door.
+ * @returns Disposer for both scoped waterfall listeners.
+ */
+export function installAgentLlmTarget(agentCtx: Context, target: AgentLlmTargetRef): () => void {
+  const disposeAssembly = agentCtx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+    const selected = target.current
+    const assembled = await next()
+    target.assembled = selected
+    if (selected === undefined) return assembled
+    return {
+      ...assembled,
+      variables: {
+        ...assembled.variables,
+        provider: selected.provider,
+        model: selected.model,
+      },
+    }
+  })
+  const disposeRequest = agentCtx.on(
+    'agent/request',
+    async (_agent, _turn, _step, _config, next): Promise<LlmCallConfig> => {
+      const resolved = await next()
+      const selected = target.assembled
+      return selected === undefined ? resolved : {
+        ...resolved,
+        provider: selected.provider,
+        model: selected.model,
+      }
+    },
+  )
+  return () => {
+    disposeAssembly()
+    disposeRequest()
+  }
+}

packages/core/agent/tests/llm-target.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import {
+  agentEvents,
+  installAgentLlmTarget,
+  type Agent,
+  type AgentLlmTargetRef,
+} from '../src/index.ts'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+describe('installAgentLlmTarget()', () => {
+  it('snapshots prompt variables and request routing together, then disposes both listeners', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const target: AgentLlmTargetRef = { current: undefined, assembled: undefined }
+    const dispose = installAgentLlmTarget(ctx, target)
+    const agent = {} as Agent
+    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
+
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+
+    target.current = { provider: 'alpha', model: 'a1' }
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'alpha', model: 'a1' })
+    target.current = { provider: 'beta', model: 'b1' }
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'alpha', model: 'a1', temperature: 0.2 })
+
+    expect((await ctx.systemPrompt.assemble()).variables).toMatchObject({ provider: 'beta', model: 'b1' })
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 1, 1, seed, () => Promise.resolve(seed),
+    )).resolves.toEqual({ provider: 'beta', model: 'b1', temperature: 0.2 })
+
+    dispose()
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    await expect(agentEvents(ctx, agent).waterfall(
+      'agent/request', 2, 0, seed, () => Promise.resolve(seed),
+    )).resolves.toBe(seed)
+    await ctx.fiber.dispose()
+  })
+})