fix(session-reference): bind snapshots to prompts

2026-07-22 17:34:31 +08:00
parent 3fa368854c
commit da8c0ab092
102 changed files with 838 additions and 248 deletions
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -52,7 +52,7 @@ Configured agents start automatically. A model call requires both `provider` and

 The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.

-Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore append only after admission. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`: an open turn records the steering message followed by its contexts at the next steering checkpoint before a request or continuation decision, but policy can still stop before another step; steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.
+Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore materialize only after admission. Absent or `separate` placement appends an independent `context/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.

 ### Loop lifecycle (`loop.ts`)

--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -12,7 +12,7 @@ import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorC
 import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
-import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
+import type { PromptMessageData, Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
 import type { TransmissionLog } from './request-log.ts'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -92,6 +92,45 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
 /** Internal control-flow sentinel; durable classification comes only from the turn signal. */
 const TURN_INTERRUPTED = new Error('turn interrupted')

+const PROMPT_PREFIX_REQUEST_DELIMITER: ContentBlock = {
+  type: 'text',
+  text: '\n\n## My request:\n',
+}
+
+interface PreparedPromptMessage {
+  data: PromptMessageData
+  separateContexts: HookContext[]
+}
+
+/** Bake declared prefix contexts into one reconstructable prompt message. */
+function preparePromptMessage(
+  content: ContentBlock[],
+  source: PromptMessageData['source'],
+  contexts: readonly HookContext[],
+): PreparedPromptMessage {
+  const prefixContexts = contexts.filter(context => context.placement === 'prompt-prefix')
+  const separateContexts = contexts.filter(context => context.placement !== 'prompt-prefix')
+  if (prefixContexts.length === 0) return { data: { content, source }, separateContexts }
+  return {
+    data: {
+      content: [
+        ...prefixContexts.flatMap(context => context.content),
+        PROMPT_PREFIX_REQUEST_DELIMITER,
+        ...content,
+      ],
+      source,
+      envelope: {
+        displayContent: content,
+        prefixContexts: prefixContexts.map(context => ({
+          source: context.source,
+          ...context.meta === undefined ? {} : { meta: context.meta },
+        })),
+      },
+    },
+    separateContexts,
+  }
+}
+
 /** Stop at an explicit cooperative boundary without stringifying the runtime reason. */
 function interruptionCheckpoint(signal: AbortSignal): void {
  if (signal.aborted) throw TURN_INTERRUPTED
@@ -240,9 +279,14 @@ async function runTurn(
  const drainSteering = (): boolean => {
    const messages = handle.inbox.drainSteering()
    for (const message of messages) {
-      session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
-      for (const context of message.contexts) {
-        session.append('context/message', context, { surfaceOp: 'append' })
+      const prepared = preparePromptMessage(message.content, message.source, message.contexts)
+      session.append('steering/message', { turn, ...prepared.data }, { surfaceOp: 'append' })
+      for (const context of prepared.separateContexts) {
+        session.append('context/message', {
+          content: context.content,
+          source: context.source,
+          ...context.meta === undefined ? {} : { meta: context.meta },
+        }, { surfaceOp: 'append' })
      }
    }
    return messages.length > 0
@@ -316,11 +360,12 @@ async function runTurn(
    } else {
      // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
      const content = promptDecision.content ?? message.content
-      session.append('user/message', { content, source: message.source }, { surfaceOp: 'append' })
-      // 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 or metadata.
-      for (const context of promptDecision.additionalContexts ?? []) {
+      const prepared = preparePromptMessage(content, message.source, promptDecision.additionalContexts ?? [])
+      session.append('user/message', prepared.data, { surfaceOp: 'append' })
+      // Separate contexts still enter THIS turn through inject(). Prefix
+      // contexts are already baked into the user/message with their durable
+      // display envelope, so appending them again would duplicate model input.
+      for (const context of prepared.separateContexts) {
        agent.inject(context.content, {
          source: context.source,
          ...context.meta !== undefined ? { meta: context.meta } : {},
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -875,24 +875,51 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    expect(agent.status).toBe('running')
    const content = [{ type: 'text' as const, text: 'accepted-steer' }]
    const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
-    const contexts: HookContext[] = [{
-      content: [{ type: 'text', text: 'accepted-steering-context' }],
-      source: { kind: 'plugin', plugin: 'steering-context' },
-    }]
+    const contexts: HookContext[] = [
+      {
+        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
+        source: { kind: 'plugin', plugin: 'steering-prefix' },
+        placement: 'prompt-prefix',
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context' }],
+        source: { kind: 'plugin', plugin: 'steering-context' },
+        meta: { kind: 'separate-card' },
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
+        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
+      },
+    ]
    agent.steer(content, { source, contexts })
    content[0]!.text = 'caller-mutated-steer'
    source.plugin = 'caller-mutated-source'
-    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context' }
+    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-steering-prefix' }
+    contexts[0]!.placement = 'separate'
+    contexts[1]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context' }
+    contexts[2]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context-without-meta' }
    const idle = waitForIdle(ctx, agent)
    release.resolve(undefined)
    await idle

    expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-steer' }])
    expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
-    expect(notifiedContexts).toEqual([{
-      content: [{ type: 'text', text: 'accepted-steering-context' }],
-      source: { kind: 'plugin', plugin: 'steering-context' },
-    }])
+    expect(notifiedContexts).toEqual([
+      {
+        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
+        source: { kind: 'plugin', plugin: 'steering-prefix' },
+        placement: 'prompt-prefix',
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context' }],
+        source: { kind: 'plugin', plugin: 'steering-context' },
+        meta: { kind: 'separate-card' },
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
+        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
+      },
+    ])
    expect(Object.isFrozen(notifiedContent)).toBe(true)
    expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
    expect(Object.isFrozen(notifiedSource)).toBe(true)
@@ -900,14 +927,28 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
    const recorded = agent.session.events.flatMap(event => event.type === 'steering/message' ? [event.data] : [])
    expect(recorded).toContainEqual({
      turn: 1,
-      content: [{ type: 'text', text: 'accepted-steer' }],
+      content: [
+        { type: 'text', text: 'accepted-steering-prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'accepted-steer' },
+      ],
      source: { kind: 'plugin', plugin: 'accepted-source' },
+      envelope: {
+        displayContent: [{ type: 'text', text: 'accepted-steer' }],
+        prefixContexts: [{
+          source: { kind: 'plugin', plugin: 'steering-prefix' },
+        }],
+      },
    })
    const request = JSON.stringify(adapter.requests[1]!.messages)
    expect(request).toContain('accepted-steer')
+    expect(request).toContain('accepted-steering-prefix')
    expect(request).toContain('accepted-steering-context')
+    expect(request).toContain('accepted-steering-context-without-meta')
    expect(request).not.toContain('caller-mutated-steer')
+    expect(request).not.toContain('caller-mutated-steering-prefix')
    expect(request).not.toContain('caller-mutated-steering-context')
+    expect(request).not.toContain('caller-mutated-steering-context-without-meta')

    const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
    const contextIndex = agent.session.events.findIndex(event => event.type === 'context/message'
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -117,6 +117,55 @@ describe('agent/prompt-submit', () => {
    expect(sent).toContain('extra ctx')
  })

+  it('bakes prompt-prefix contexts and a request delimiter into one durable user message', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('prefixed'), { provider: 'mock', model: 'mock' })
+
+    ctx.on('agent/prompt-submit', async (_agent, _content, _source, _signal, next): Promise<PromptDecision> => {
+      const downstream = await next()
+      return downstream.kind === 'block'
+        ? downstream
+        : { ...downstream, content: [{ type: 'text', text: 'rewritten request' }] }
+    })
+    agent.send([{ type: 'text', text: 'original request' }], {
+      contexts: [{
+        content: [{ type: 'text', text: 'untrusted prefix' }],
+        source: { kind: 'plugin', plugin: 'prefix' },
+        placement: 'prompt-prefix',
+        meta: { kind: 'prefix-card' },
+      }],
+    })
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const user = log.find(event => event.type === 'user/message')
+    expect(user?.type === 'user/message' && user.data).toEqual({
+      content: [
+        { type: 'text', text: 'untrusted prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'rewritten request' },
+      ],
+      source: { kind: 'user' },
+      envelope: {
+        displayContent: [{ type: 'text', text: 'rewritten request' }],
+        prefixContexts: [{
+          source: { kind: 'plugin', plugin: 'prefix' },
+          meta: { kind: 'prefix-card' },
+        }],
+      },
+    })
+    expect(log.some(event => event.type === 'context/message')).toBe(false)
+    expect(adapter.requests[0]?.messages.at(-1)).toEqual({
+      role: 'user',
+      content: [
+        { type: 'text', text: 'untrusted prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'rewritten request' },
+      ],
+    })
+  })
+
  it('runs pre-step after prompt rewrites and injected context become durable', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)