Merge origin/master into parallel-tool-call

2026-07-17 22:08:40 +08:00
parent 62f6251bf9 e73cadb99d
commit 688b95a7e5
432 changed files with 28392 additions and 3077 deletions
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -8,7 +8,7 @@

 import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentId, AgentOptions, AgentStatus, SendOptions } from '@deepseek-ai/dsh-agent'
+import type { AgentId, AgentOptions, AgentStatus, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
@@ -230,14 +230,20 @@ export class ReactLoopAgent implements Agent {
    agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
  }

-  inject(content: ContentBlock[], options?: SendOptions): void {
+  inject(content: ContentBlock[], options?: InjectOptions): void {
    this.assertNotDisposed()
    const source = this.resolveSource(options)
+    const context = {
+      content,
+      source,
+      ...options?.envelope !== undefined ? { envelope: options.envelope } : {},
+      ...options?.meta !== undefined ? { meta: options.meta } : {},
+    }
    if (isTurnOpen(this.session)) {
      // A turn is open in the LOG (decided from the log, not agent status —
      // status can be `running` with no turn open): the context/message is
      // turn-enclosed by that turn, so append it directly.
-      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
+      this.session.append('context/message', context, { surfaceOp: 'append' })
      return
    }
    // No turn open: wrap the injection in a one-shot turn so every event stays
@@ -249,7 +255,7 @@ export class ReactLoopAgent implements Agent {
    // are contained by Session and cannot create a false append failure.
    try {
      this.session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
+      this.session.append('context/message', context, { surfaceOp: 'append' })
    } finally {
      // Close the turn if turn/start made it into the log. A pre-commit veto
      // must escape rather than being mistaken for a committed turn/end.
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -237,10 +237,15 @@ async function runTurn(
      // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
      const content = decision.content ?? message.content
      session.append('user/message', { content, source: message.source }, { surfaceOp: 'append' })
-      // `allow.additionalContext` is a SEPARATE context/message the next request
-      // also sees. The turn is open, so inject() appends it into THIS turn.
-      if (decision.additionalContext) {
-        agent.inject(decision.additionalContext.content, { source: decision.additionalContext.source })
+      // Every `allow.additionalContexts` entry is a separate context/message the
+      // next request also sees. The turn is open, so inject() appends each one
+      // into THIS turn without flattening provenance, framing, or metadata.
+      for (const context of decision.additionalContexts ?? []) {
+        agent.inject(context.content, {
+          source: context.source,
+          ...context.envelope !== undefined ? { envelope: context.envelope } : {},
+          ...context.meta !== undefined ? { meta: context.meta } : {},
+        })
      }
    }

@@ -568,7 +573,11 @@ async function runStep(

  // Append context after the complete result batch to preserve call/result adjacency.
  for (const context of pendingContext) {
-    agent.inject(context.content, { source: context.source })
+    agent.inject(context.content, {
+      source: context.source,
+      ...context.envelope !== undefined ? { envelope: context.envelope } : {},
+      ...context.meta !== undefined ? { meta: context.meta } : {},
+    })
  }

  return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish }
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -11,7 +11,7 @@
 * The session log stays the source of truth and is reconstructable regardless
 * of dispatch timing: each STARTED call appends its own `tool/call` before its
 * body runs, `tool/result` events are appended in MODEL order (slot-buffered
- * behind a commit cursor), and buffered `additionalContext` is injected in model
+ * behind a commit cursor), and buffered `additionalContexts` are injected in model
 * call order after every result. A `tool/call`'s log position may interleave
 * with a sibling's `tool/result` as the pool replenishes; that is safe because
 * `tool/call` is log-only and derived history pairs the assistant message's
@@ -24,7 +24,7 @@ import type { Context } from 'cordis'
 import { assertNever, type ToolCallBlock } from '@deepseek-ai/dsh-llm'
 import type { HookContext } from '@deepseek-ai/dsh-agent'
 import type { Session } from '@deepseek-ai/dsh-session'
-import { TOOL_REGISTRY_SCHEDULER, type ToolExecution, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import { TOOL_REGISTRY_SCHEDULER, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult, type ToolRunContext } from '@deepseek-ai/dsh-tools'
 import type { ReactLoopAgent } from './agent.ts'

 /** One tool call after argument parsing, ready to schedule. */
@@ -38,7 +38,7 @@ interface PlannedCall {
 /** A settled call's slot, filled in model order before ordered finalization. */
 interface Slot {
  /** The registry-minted execution object, carrying this call's token. */
-  exec: ToolExecution
+  exec: ToolRunContext
  /** The raw dispatch/pre result. */
  result: ToolExecutionResult
  /** Whether the result still needs ordered `tools/post-execute` finalization. */
@@ -49,7 +49,7 @@ interface Slot {
 * Execute one assistant step's tool calls, honoring per-call concurrency safety.
 *
 * Appends `tool/call` (per started call) and `tool/result` (in model order) to
- * the session, and returns the ordered `additionalContext` buffer for the loop
+ * the session, and returns the ordered `additionalContexts` buffer for the loop
 * to inject after the batch. On abort it drains only already-started calls to
 * results, drops buffered context, and throws the abort error so `runTurn` owns
 * the turn-end reason.
@@ -62,7 +62,7 @@ interface Slot {
 * @param toolCalls - the assistant message's `tool-call` blocks, in model order.
 * @param signal - the step's abort signal (shared by every call).
 * @param maxParallel - the already-validated cap snapshot for parallel groups.
- * @returns the per-step `additionalContext` buffer in model call order.
+ * @returns the per-step `additionalContexts` buffer in model call order.
 */
 export async function executeToolCalls(
  ctx: Context,
@@ -121,7 +121,7 @@ function parseArguments(raw: string): unknown {
 * it against the live registry. An exclusive result stops replenishment, drains
 * the current run, and remains for the caller's next singleton group. Settled
 * dispatches land in model-order slots; a commit cursor appends `tool/result`
- * (and collects `additionalContext`) only while the next slot is ready, so the
+ * (and collects `additionalContexts`) only while the next slot is ready, so the
 * log stays model-ordered regardless of completion order.
 *
 * Abort: an already-aborted signal starts nothing and throws before any
@@ -152,7 +152,7 @@ async function runGroup(
  let aborted: boolean = signal.aborted

  // Advance the commit cursor over contiguous settled slots: run post-execute in
-  // model order, append each tool/result, and collect its additionalContext.
+  // model order, append each tool/result, and collect its additionalContexts.
  const commitReady = async (): Promise<void> => {
    while (committed < group.length) {
      const slot = slots[committed]
@@ -164,7 +164,7 @@ async function runGroup(
      // committed < group.length, so call and its callSeq (set at start) exist.
      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
      appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!)
-      if (result.additionalContext) pendingContext.push(result.additionalContext)
+      pendingContext.push(...result.additionalContexts ?? [])
      committed++
    }
  }
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -17,7 +17,7 @@ import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 * The interception seams introduced by the hooks taxonomy: `agent/prompt-submit`,
 * `agent/session-start`, the reshaped `agent/turn-continuation`
 * ({@link ContinuationDecision}), and the `tools/pre-execute` / `tools/post-execute`
- * split with `additionalContext` buffering. These verify the canonical event
+ * split with `additionalContexts` buffering. These verify the canonical event
 * surface a hook bridge (or a native plugin) programs against, WITHOUT any
 * external protocol — a native plugin uses the typed decisions directly.
 */
@@ -91,15 +91,21 @@ describe('agent/prompt-submit', () => {
    expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('original')
  })

-  it('allow with additionalContext injects a separate context/message into the turn', async () => {
+  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 meta = { kind: 'prompt-context', version: 1 }
    ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
      ({
        kind: 'allow',
-        additionalContext: { content: [{ type: 'text', text: 'extra ctx' }], source: { kind: 'plugin', plugin: 'test' } },
+        additionalContexts: [{
+          content: [{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }],
+          source: { kind: 'plugin', plugin: 'test' },
+          envelope: 'raw',
+          meta,
+        }],
      }))

    send(agent, 'go')
@@ -109,14 +115,16 @@ describe('agent/prompt-submit', () => {
    const userMsg = log.find(e => e.type === 'user/message')
    const ctxMsg = log.find(e => e.type === 'context/message')
    expect(userMsg).toBeDefined()
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: 'extra ctx' }])
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.envelope).toBe('raw')
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.meta).toEqual(meta)
    // both the prompt and the injected context reach the model
    const sent = JSON.stringify(adapter.requests[0]!.messages)
    expect(sent).toContain('extra ctx')
  })

-  it('a prompt-submit rewrite + additionalContext is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
+  it('a prompt-submit rewrite + additionalContexts is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
    // Prompt rewrites and injected context land before `agent/pre-step`, so a
    // compaction listener measures the current surface before the single derive.
    const adapter = new MockAdapter([textResponse('ok')])
@@ -127,7 +135,7 @@ describe('agent/prompt-submit', () => {
      ({
        kind: 'allow',
        content: [{ type: 'text', text: 'REWRITTEN prompt' }],
-        additionalContext: { content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' } },
+        additionalContexts: [{ content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' } }],
      }))

    // The pre-step seam (where compaction lives) derives the surface it would act
@@ -538,8 +546,8 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
  })
 })

-describe('tools/post-execute additionalContext buffering across a multi-call step', () => {
-  it('appends each call\'s additionalContext only AFTER all tool/results, preserving adjacency', async () => {
+describe('tool additionalContexts buffering across a step', () => {
+  it('appends each call\'s contexts only AFTER all tool/results, preserving adjacency', async () => {
    // One assistant step with TWO tool calls; the second model response stops.
    const twoCalls = [
      { type: 'block-start' as const, index: 0, blockType: 'tool-call' as const },
@@ -557,9 +565,17 @@ describe('tools/post-execute additionalContext buffering across a multi-call ste
    }))
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

-    // Each call attaches additionalContext naming itself.
+    // Each call attaches one context naming itself.
    ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
-      ({ kind: 'accept', additionalContext: { content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } } }))
+      ({
+        kind: 'accept',
+        additionalContexts: [{
+          content: [{ type: 'text', text: `ctx-${exec.callId}` }],
+          source: { kind: 'plugin', plugin: 'p' },
+          envelope: 'raw',
+          meta: { callId: exec.callId },
+        }],
+      }))

    send(agent, 'go')
    await waitForIdle(ctx, agent)
@@ -579,6 +595,37 @@ describe('tools/post-execute additionalContext buffering across a multi-call ste
      .flatMap(e => (e.type === 'context/message' ? e.data.content : []))
      .map(b => (b.type === 'text' ? b.text : ''))
    expect(ctxTexts).toEqual(['ctx-c1', 'ctx-c2'])
+    const contextEvents = events(agent).filter(e => e.type === 'context/message')
+    expect(contextEvents.map(e => e.type === 'context/message' && e.data.envelope)).toEqual(['raw', 'raw'])
+    expect(contextEvents.map(e => e.type === 'context/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
+  })
+
+  it('appends multiple contexts deferred by one composite tool after its outer result', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'composite', {}), textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'composite', description: 'composite', parameters: {},
+      async execute(_args, exec) {
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-a' }], source: { kind: 'plugin', plugin: 'a' }, meta: { order: 1 } })
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-b' }], source: { kind: 'plugin', plugin: 'b' }, envelope: 'raw', meta: { order: 2 } })
+        return [{ type: 'text', text: 'outer result' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const resultIndex = log.findIndex(event => event.type === 'tool/result')
+    const contextEvents = log.filter(event => event.type === 'context/message')
+    expect(resultIndex).toBeGreaterThanOrEqual(0)
+    expect(log.findIndex(event => event === contextEvents[0])).toBeGreaterThan(resultIndex)
+    expect(contextEvents.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'a' },
+      { kind: 'plugin', plugin: 'b' },
+    ])
+    expect(contextEvents.map(event => event.type === 'context/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
  })
 })

@@ -638,7 +685,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
      ctx.on('tools/post-execute', async (_exec, _result, next): Promise<PostToolDecision> => {
        const decision = await next()
        if (decision.kind === 'accept') {
-          return { kind: 'accept', additionalContext: { content: [{ type: 'text', text: 'audited' }], source: { kind: 'plugin', plugin: 'native-guard' } } }
+          return { kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: 'audited' }], source: { kind: 'plugin', plugin: 'native-guard' } }] }
        }
        return decision
      })
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -383,6 +383,32 @@ describe('agent loop', () => {
    expect(flat).toContain('<context source=\\"plugin\\">')
  })

+  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 text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
+    const meta = {
+      kind: 'workspace-instructions',
+      version: 1,
+      changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md', digest: 'abc123' }],
+    }
+
+    agent.inject([{ type: 'text', text }], {
+      source: { kind: 'plugin', plugin: 'workspace-context' },
+      envelope: 'raw',
+      meta,
+    })
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const contextEvent = agent.session.events.find(event => event.type === 'context/message')
+    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ envelope: 'raw', meta })
+    const requestText = JSON.stringify(adapter.requests[0]!.messages)
+    expect(requestText).toContain('Additional instructions from: pkg/AGENTS.md')
+    expect(requestText).not.toContain('<context source=')
+  })
+
  it('inject() while running appends into the open turn (no extra synthetic turn)', async () => {
    const adapter = new MockAdapter([
      toolCallResponse('c1', 'noticer', {}, 'calling'),
--- a/packages/core/agent-loop/tests/tool-calls.spec.ts
+++ b/packages/core/agent-loop/tests/tool-calls.spec.ts
@@ -3,7 +3,7 @@
 * `ctx.tools.executionMode`, the rolling pool for parallel groups, model-order
 * `tool/result` commit despite out-of-order settlement, registry-change
 * reclassification, interleaved `tool/call` audit records, ordered
- * `tools/pre-execute`/`tools/post-execute`, model-ordered `additionalContext`,
+ * `tools/pre-execute`/`tools/post-execute`, model-ordered `additionalContexts`,
 * and abort behavior.
 *
 * Tools are mocked and deterministic — no real API, no snapshot here (the
@@ -383,7 +383,7 @@ describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () =>

 })

-describe('tool-call scheduler: ordered middleware and additionalContext', () => {
+describe('tool-call scheduler: ordered middleware and additional contexts', () => {
  it('tools/pre-execute and tools/post-execute observe model call order', async () => {
    const adapter = new MockAdapter([
      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }, { id: 'c3', name: 'p', args: { id: '3' } }]),
@@ -409,7 +409,7 @@ describe('tool-call scheduler: ordered middleware and additionalContext', () =>
    expect(post).toEqual([CallId('c1'), CallId('c2'), CallId('c3')].map(String))
  })

-  it('injects additionalContext in model call order, not settlement order', async () => {
+  it('injects additional contexts in model call order, not settlement order', async () => {
    const adapter = new MockAdapter([
      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
      textResponse('done'),
@@ -418,7 +418,7 @@ describe('tool-call scheduler: ordered middleware and additionalContext', () =>
    const gated = gatedParallelTool('p')
    ctx.tools.register(gated.tool)
    ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
-      ({ kind: 'accept', additionalContext: { content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } } }))
+      ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }] }))
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

    agent.send([{ type: 'text', text: 'go' }])
@@ -527,7 +527,7 @@ describe('tool-call scheduler: abort handling', () => {
      .toEqual([CallId('c1')])
  })

-  it('stops replenishing after abort, commits started results, and drops buffered additionalContext', async () => {
+  it('stops replenishing after abort, commits started results, and drops buffered additional contexts', async () => {
    const adapter = new MockAdapter([
      multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))),
      textResponse('should never be requested'),
@@ -537,7 +537,7 @@ describe('tool-call scheduler: abort handling', () => {
    ctx.tools.register(gated.tool)
    ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => ({
      ...await next(),
-      additionalContext: { content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } },
+      additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }],
    }))
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })