Merge remote-tracking branch 'origin/master' into codex/skill-system

# Conflicts: # docs/event-producer-consumer.md # docs/module-graph.md # docs/rfc/README.md # packages/core/agent-core/package.json # packages/core/agent-core/src/index.ts # packages/core/agent-loop/README.md # packages/core/agent-loop/src/index.ts # packages/ui/acp-agent/src/index.ts # packages/ui/acp-agent/tests/acp-agent.spec.ts # packages/ui/stdio-agent/README.md # packages/ui/stdio-agent/src/index.ts # packages/ui/stdio-agent/tests/stdio-agent.spec.ts
2026-07-06 10:09:26 +08:00
parent ad14b210bf 9c0cd392b9
commit 545b2775db
205 changed files with 2738 additions and 1268 deletions
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -28,13 +28,12 @@ interface Config {
  agents: Array<{
    id: string                 // required
    model?: string
-    systemPrompt?: string
    cwd?: string               // optional workspace cwd for the fresh session
  }>
 }
 ```

-Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header.
+Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.

 ### Classes

@@ -56,7 +55,7 @@ forever:
    if every prompt blocked: 'turn/end'(rejected), no step  ⟵ zero-step turn
    STEP loop:
      drain steering
-      assembly = systemPrompt.assemble()
+      assembly = systemPrompt.assemble({agent})  ⟵ renderPrompt(assembly) IS the full prompt
      await serial agent/pre-step        ⟵ surface mutation (compaction) outside the step
      session('step/start')
      request = waterfall agent/request
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -74,7 +74,6 @@ export class AgentLoop extends Service implements AgentFactory {
    agents: z.array(z.object({
      id: z.string().required(),
      model: z.string(),
-      systemPrompt: z.string(),
      cwd: z.string(),
      resumeSessionId: z.string(),
    })).default([]),
@@ -85,6 +84,16 @@ export class AgentLoop extends Service implements AgentFactory {
    // Provide the agent-creation factory to the registry (effect-scoped: the
    // slot is cleared on dispose).
    ctx.effect(() => this.ctx.agents.setFactory(this), 'agentLoop.setFactory()')
+    // The prompt variables the shipped loop provides, registered once. The
+    // sections themselves (`harness:identity`, `deployment:persona`) belong to
+    // dsh-system-prompt — they must survive a swapped loop plugin — but
+    // `{{model}}`/`{{cwd}}` are runtime facts of the agents THIS loop drives:
+    // it assembles with `{ agent }` each step (loop.ts), and the variables
+    // project the agent's configured model and its session workspace from that
+    // context. A provider returns undefined when the fact is absent
+    // (renderPrompt then rejects a persona that claims it — fail loud).
+    ctx.systemPrompt.variable('model', context => context.agent?.options.model)
+    ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd)
    for (const { id, cwd, resumeSessionId, ...options } of config.agents) {
      if (resumeSessionId !== undefined && resumeSessionId !== '') {
        // Resume a prior session instead of starting fresh. resume() needs
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -152,7 +152,8 @@ export interface LoopHandle {
 *     every prompt blocked → 'turn/end'(rejected), 0 steps
 *     STEP loop:
 *       drain steering → session('steering/message')  ⟵ catches late steering
- *       assembly = ctx.systemPrompt.assemble()        ⟵ waterfall system-prompt/assemble
+ *       assembly = ctx.systemPrompt.assemble({agent}) ⟵ waterfall system-prompt/assemble; renderPrompt
+ *                                                        (persona section + {{variables}}) IS the full prompt
 *       await ctx.serial('agent/pre-step')            ⟵ surface mutation (compaction) OUTSIDE the step
 *       session('step/start')                         ⟵ durable step boundary (no agent/* mirror)
 *       req = {model, system, tools, messages: session.deriveMessages(), signal}
@@ -434,11 +435,11 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
      // because the pre-step seam needs it: compaction measures token pressure
      // against the system prompt (it counts toward the budget). runStep reuses
      // this same assembly for the request, so the prompt is assembled once per
-      // step.
-      const assembly = await ctx.systemPrompt.assemble()
-      const fullSystemPrompt = [renderPrompt(assembly), agent.options.systemPrompt ?? '']
-        .filter(text => text.length > 0)
-        .join('\n\n')
+      // step. renderPrompt IS the full prompt — the persona is the order-0
+      // section (registered by the AgentLoop plugin) and `{{variable}}`
+      // interpolation happens in the render, so there is no separate join.
+      const assembly = await ctx.systemPrompt.assemble({ agent })
+      const fullSystemPrompt = renderPrompt(assembly)

      // Interruption landing after assembly: dispose() or cancel() in a
      // turn-start listener (or a listener whose promise resolved before the
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -35,7 +35,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', systemPrompt: '' }] })
+    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
    await ctx1.plugin(SessionPersistenceJsonl, { root })
    ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
    const a1 = ctx1.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -52,7 +52,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', systemPrompt: '' }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
    await ctx2.plugin(SessionPersistenceJsonl, { root })
    ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
    const a2 = ctx2.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -92,7 +92,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', systemPrompt: '', resumeSessionId: SessionId('sticky-1') }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
    await ctx2.plugin(SessionPersistenceJsonl, { root })
    ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('second')]))

@@ -120,7 +120,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', systemPrompt: '', resumeSessionId: SessionId('does-not-exist') }] })
+    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), 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 })
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -8,11 +8,11 @@ import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'

-async function harness(adapter: MockAdapter) {
+async function harness(adapter: MockAdapter, persona = '') {
  const ctx = new Context()
  await ctx.plugin(LlmService)
  await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(SystemPrompt, { persona })
  await ctx.plugin(ToolRegistry)
  await ctx.plugin(AgentRegistry)
  await ctx.plugin(AgentLoop, { agents: [] })
@@ -141,10 +141,12 @@ describe('agent loop', () => {
      .toEqual({ diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] })
  })

-  it('passes assembled system prompt and tool schemas into the request', async () => {
+  it('renders harness identity, then the persona, then tool guidance — with {{variables}} resolved', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
-    const ctx = await harness(adapter)
-    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are a test agent.' })
+    // The persona is a TEMPLATE: {{model}} is the loop-registered variable
+    // projecting this agent's configured model, so the model knows its own name.
+    const ctx = await harness(adapter, 'You are a test agent on {{model}}.')
+    ctx.systemPrompt.section({ name: 'tool:noop', order: 100, text: 'Use the noop tool wisely.' })
    ctx.tools.register(defineTool({
      name: 'noop',
      description: 'does nothing',
@@ -153,16 +155,111 @@ describe('agent loop', () => {
        return []
      },
    }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock', systemPrompt: 'Agent-specific suffix.' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

    send(agent, 'hi')
    await waitForIdle(ctx, agent)

    const request = adapter.requests[0]
-    expect(request!.system).toBe('You are a test agent.\n\nAgent-specific suffix.')
+    expect(request!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a test agent on mock.\n\nUse the noop tool wisely.')
    expect(request!.tools?.map(t => t.name)).toEqual(['noop'])
  })

+  it('resolves {{cwd}} from the agent session workspace (factory create with meta.cwd)', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter, 'Working in {{cwd}}.')
+    const handle = ctx.agents.create({
+      agentId: AgentId('a-cwd'),
+      sessionId: SessionId('s-cwd'),
+      meta: { cwd: '/work/space' },
+      agentOptions: { model: 'mock' },
+    })
+
+    const agent = handle.agent as ReactLoopAgent
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nWorking in /work/space.')
+  })
+
+  it('contains a strict-variable render failure: the turn errors, the loop keeps serving turns', async () => {
+    // A persona claiming {{cwd}} on a session with NO cwd is a deployment
+    // authoring error — renderPrompt throws, the turn ends with an error, and
+    // the same agent must then RUN a later turn to completion (not merely
+    // report idle status): a rescue listener supplies the variable and the
+    // follow-up prompt reaches the model.
+    const adapter = new MockAdapter([textResponse('ok after rescue')])
+    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' })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(0) // the request was never sent
+    expect(errors.some(e => e.message.includes('no value for this assembly'))).toBe(true)
+    const turnEnd = agent.session.events.find(e => e.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('error')
+
+    // The loop survived: a waterfall listener rescues {{cwd}} and the SAME
+    // agent completes a real model turn.
+    ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      assembly.variables['cwd'] = '/rescued'
+      return next()
+    })
+    send(agent, 'again')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nIn /rescued.')
+    const turnEnds = agent.session.events.filter(e => e.type === 'turn/end')
+    expect(turnEnds).toHaveLength(2)
+    expect(turnEnds[1]?.type === 'turn/end' && turnEnds[1].data.reason.kind).toBe('completed')
+  })
+
+  it('supports the model-via-agent/request path with a {{model}} persona: the supplier states it via the assemble waterfall', async () => {
+    // AgentOptions.model unset: the model arrives in the agent/request
+    // waterfall (the loop's documented fallback — see runStep's no-model
+    // error). {{model}} renders BEFORE that waterfall, so the SAME plugin
+    // states the fact early on system-prompt/assemble — the owner of a
+    // late-bound fact owns stating it wherever it is claimed.
+    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['model'] = 'mock'
+      return next()
+    })
+    ctx.on('agent/request', async (_agent, _turn, _step, options, next) => {
+      options.model = 'mock'
+      return next()
+    })
+    const agent = ctx.agentLoop.create(AgentId('a-late-model'), {})
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests[0]!.model).toBe('mock')
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou run on mock.')
+  })
+
+  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
+    // The documented escape valve: a deployment that must drop the harness
+    // openers short-circuits the assemble waterfall; the request then carries
+    // NO system field at all (not an empty string).
+    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' })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect('system' in adapter.requests[0]!).toBe(false)
+  })
+
  it('records raw chunks for replay as assistant/chunk session events', async () => {
    const adapter = new MockAdapter([textResponse('abc')])
    const ctx = await harness(adapter)
@@ -371,10 +468,12 @@ describe('agent loop', () => {
    send(agent, 'go')
    await waitForIdle(ctx, agent)

-    // One fire per step, in order, each with the assembled system prompt.
+    // One fire per step, in order, each with the assembled system prompt
+    // (here just the loop's own harness-identity section — no persona set).
+    const HARNESS = 'You are an AI agent powered by the DeepSeek Harness SDK.'
    expect(fires).toEqual([
-      { turn: 1, step: 1, fullSystemPrompt: '' },
-      { turn: 1, step: 2, fullSystemPrompt: '' },
+      { turn: 1, step: 1, fullSystemPrompt: HARNESS },
+      { turn: 1, step: 2, fullSystemPrompt: HARNESS },
    ])
  })

@@ -796,7 +895,7 @@ describe('agent loop', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), model: 'mock', systemPrompt: 'Config prompt' }],
+      agents: [{ id: AgentId('config-agent'), model: 'mock' }],
    })
    ctx.llm.registerAdapter(['mock'], adapter)

@@ -819,7 +918,7 @@ describe('agent loop', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), model: 'mock', systemPrompt: '', cwd: '/work/project' }],
+      agents: [{ id: AgentId('config-agent'), model: 'mock', cwd: '/work/project' }],
    })

    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
--- a/packages/core/agent-loop/tests/review-fixes.spec.ts
+++ b/packages/core/agent-loop/tests/review-fixes.spec.ts
@@ -1016,7 +1016,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    ctx.llm.registerAdapter(['mock'], adapter)

    // Blocking listener on the parent context (survives fiber disposal).
-    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
      await blocked
      return next()
    })
@@ -1072,7 +1072,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(Invariants, { freeze: false })
    ctx.llm.registerAdapter(['mock'], adapter)

-    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
      await blocker
      return next()
    })
@@ -1229,7 +1229,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(Invariants, { freeze: false })
    ctx.llm.registerAdapter(['mock'], adapter)

-    ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
      await blocker
      return next()
    })