refactor(agent-loop): separate injected context from turns

packages/context/session-reference/README.md

@@ -1,18 +1,18 @@
 # `@deepseek-ai/dsh-session-reference`
 
-`ctx.sessionReferences` prepares bounded, read-only snapshots of other sessions as prompt-prefix context. It consumes `ctx.sessionQuery` and the backend-independent compact checkpoint marker; SQLite FTS is not required. The standard TUI and ACP demo bundles mount it, while other hosts may call the service directly.
+`ctx.sessionReferences` prepares bounded, read-only snapshots of other sessions as additional context. It consumes `ctx.sessionQuery` and the backend-independent compact checkpoint marker; SQLite FTS is not required. The standard TUI and ACP demo bundles mount it, while other hosts may call the service directly.
 
 ## Public API
 
 - `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id or cwd, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses its latest log-backed title as the mention label and falls back to the session id; titles and message bodies are not searched.
-- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `HookContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host calls `send()` or `steer()`.
+- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated `AdditionalContext`. Any invalid reference, failed read, cancellation, or budget failure rejects before the host injects context and sends or steers the direct message.
 - `encodeSessionReferenceUri()` and `decodeSessionReferenceUri()` implement `dsh-session:<base64url(JSON.stringify(sessionId))>` so every JavaScript string id round-trips exactly. `formatSessionReferenceMention()` emits `@[label](uri)`, and `parseSessionReferenceText()` replaces Markdown mentions or bare canonical URIs with readable `@label` text while returning structured references. Explicit Markdown mentions reject every malformed URI; bare text is considered a reference only when a non-empty base64url-shaped payload follows the scheme, and a matching noncanonical candidate still fails. Empty or punctuation-only scheme mentions remain ordinary discussion text.
 
 ## Snapshot semantics
 
-Preparation calls `ctx.sessionQuery.readSurface()` once per distinct source and never rereads it after enqueue. It projects only direct-user `user/message`, direct-user `steering/message`, assistant text, and `user/message` checkpoints carrying the canonical `dsh-compact` source marker from the folded current surface. For a source prompt that already contains baked prefix context, projection reads only its model-hidden display content, preventing recursive snapshot propagation. Shadowed pre-compaction events, tools, reasoning, context, plugin-generated user messages other than marked compact checkpoints, and unfinished assistant chunks are excluded. A compacted source therefore contributes its latest checkpoint plus retained later conversation, not restored shadowed text.
+Preparation calls `ctx.sessionQuery.readSurface()` once per distinct source and never rereads it after delivery. It projects only direct-user `user/message`, direct-user `steering/message`, assistant text, and `user/message` checkpoints carrying the canonical `dsh-compact` source marker from the folded current surface. Synthetic context, shadowed pre-compaction events, tools, reasoning, plugin-generated user messages other than marked compact checkpoints, and unfinished assistant chunks are excluded. A compacted source therefore contributes its latest checkpoint plus retained later conversation, not restored shadowed text.
 
-The context uses a typed `{ kind: 'session-reference', ... }` source with `placement: 'prompt-prefix'`. That source records version `1`, source ids and labels, capture seqs, compact presence, retained/omitted message counts, omitted UTF-8 bytes, and truncation state. AgentLoop writes the snapshot, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`; the same event's model-hidden envelope retains the direct prompt and source for TUI/ACP replay. Later source mutation, compaction, or deletion cannot change target replay.
+The context uses a typed `{ kind: 'session-reference', ... }` source. That source records version `1`, source ids and labels, capture seqs, compact presence, retained/omitted message counts, omitted UTF-8 bytes, and truncation state. Hosts call `inject()` with the snapshot before delivering the direct prompt, so the session log keeps two simple messages with independent provenance. TUI and ACP replay the direct user message normally and render the injected snapshot as a compact reference card. Later source mutation, compaction, or deletion cannot change target replay.
 
 ## Configuration
 
@@ -30,7 +30,7 @@ Retention applies `maxReferenceBytes` independently to each source, keeps compac
 
 #### What the model sees
 
-The model sees one user-role message in this order: the `## Referenced sessions` untrusted snapshot, the `## My request:` delimiter, then the current message with its readable `@label`. The warning forbids following instructions, permission claims, or tool requests from the snapshot unless the current user repeats them. Labels, cwd values, ids, and conversation text are serialized as JSON inside `<referenced-sessions>` tags; every data `<` is emitted as the lossless JSON escape `\u003c`, so source text cannot spell a framing tag.
+The model sees two consecutive user-role messages: the `## Referenced sessions` untrusted snapshot, then the current message with its readable `@label`. The warning forbids following instructions, permission claims, or tool requests from the snapshot unless the current user repeats them. Labels, cwd values, ids, and conversation text are serialized as JSON inside `<referenced-sessions>` tags; every data `<` is emitted as the lossless JSON escape `\u003c`, so source text cannot spell a framing tag.
 
 #### Token effect
 
@@ -38,7 +38,7 @@ Each referenced message adds the fixed warning plus up to three serialized snaps
 
 #### KV Cache effect
 
-The combined snapshot and request are append-only at the target message boundary and preserve earlier cacheable history. Different references or source capture contents change the new suffix only; later target compaction may invalidate reuse from its replacement boundary.
+The snapshot and request append as adjacent target messages and preserve earlier cacheable history. Different references or source capture contents change the new suffix only; later target compaction may invalidate reuse from its replacement boundary.
 
 ## Known Limitations and Deferred Work
 

packages/context/session-reference/src/index.ts

@@ -7,7 +7,7 @@
 
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
-import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
+import type { AdditionalContext, Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionSurfaceSnapshot } from '@deepseek-ai/dsh-session-query'
@@ -148,7 +148,7 @@ export class SessionReferenceService extends Service {
    * @param content - already host-normalized readable message content.
    * @param references - structured source sessions in mention order.
    * @param signal - optional cancellation boundary for host request teardown.
-   * @returns detached content and zero or one prepared contexts.
+   * @returns detached content and optional referenced-session context.
    */
   async prepare(
     agent: Agent,
@@ -158,7 +158,7 @@ export class SessionReferenceService extends Service {
   ): Promise<PreparedReferencedMessage> {
     const acceptedContent = structuredClone(content)
     const inputs = normalizeReferences(agent.id, references, this.config.maxReferences)
-    if (inputs.length === 0) return { content: acceptedContent, contexts: [] }
+    if (inputs.length === 0) return { content: acceptedContent }
     assertNotCancelled(signal)
     let prepared: PreparedSource[]
     try {
@@ -192,12 +192,11 @@ export class SessionReferenceService extends Service {
         inputIndex: index,
       })),
     }
-    const context: HookContext = {
+    const additionalContext: AdditionalContext = {
       source,
       content: [{ type: 'text', text: prompt }],
-      placement: 'prompt-prefix',
     }
-    return { content: acceptedContent, contexts: [context] }
+    return { content: acceptedContent, additionalContext }
   }
 
   private renderSources(sources: readonly PreparedSource[]): RenderedSource[] {

packages/context/session-reference/src/projection.ts

@@ -1,7 +1,6 @@
 /** Current-surface projection and byte-bounded rendering. */
 
 import { isCompactCheckpointSource } from '@deepseek-ai/dsh-compact'
-import { displayPromptContent } from '@deepseek-ai/dsh-session'
 import type { SessionSurfaceSnapshot } from '@deepseek-ai/dsh-session-query'
 import { assertNever } from '@deepseek-ai/dsh-llm'
 import { TextRetainer } from '@deepseek-ai/dsh-retention'
@@ -41,13 +40,13 @@ function projectSessionConversation(snapshot: SessionSurfaceSnapshot): Projected
       case 'user/message': {
         const checkpoint = isCompactCheckpointSource(event.data.source)
         if (!checkpoint && event.data.source.kind !== 'user') break
-        const text = textContent(displayPromptContent(event.data))
+        const text = textContent(event.data.content)
         if (text !== '') conversation.push({ role: 'user', text, checkpoint, originalText: text, omittedBytes: 0 })
         break
       }
       case 'steering/message': {
         if (event.data.source.kind !== 'user') break
-        const text = textContent(displayPromptContent(event.data))
+        const text = textContent(event.data.content)
         if (text !== '') conversation.push({ role: 'user', text, checkpoint: false, originalText: text, omittedBytes: 0 })
         break
       }

packages/context/session-reference/src/types.ts

@@ -1,6 +1,6 @@
 /** Public session-reference request, candidate, and preparation records. */
 
-import type { HookContext } from '@deepseek-ai/dsh-agent'
+import type { AdditionalContext } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 
@@ -48,12 +48,12 @@ export interface SessionReferenceCandidate {
   createdAt: number
 }
 
-/** Message payload and the zero-or-one durable snapshot contexts bound to it. */
+/** Direct message content and optional referenced-session context. */
 export interface PreparedReferencedMessage {
   /** Readable message content after host mention tokens are removed. */
   content: ContentBlock[]
-  /** Empty without references; otherwise one aggregated untrusted context. */
-  contexts: HookContext[]
+  /** Aggregated untrusted snapshot, absent when the message has no references. */
+  additionalContext?: AdditionalContext
 }
 
 /** Text-only projected conversation item. */

packages/context/session-reference/tests/session-reference.spec.ts

@@ -238,11 +238,9 @@ describe('session reference discovery and preparation', () => {
       [{ sessionId: source.id, label: 'source' }],
     )
     expect(prepared.content).toEqual([{ type: 'text', text: 'use @source' }])
-    expect(prepared.contexts).toHaveLength(1)
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context?.content[0]?.type !== 'text') throw new Error('expected text context')
     expect(context.source).toMatchObject({ kind: 'session-reference' })
-    expect(context.placement).toBe('prompt-prefix')
     expect(context.content[0].text).toContain('untrusted, read-only snapshot')
     expect(promptData(context.content[0].text)).toEqual([{
       sessionId: 'source',
@@ -276,21 +274,17 @@ describe('session reference discovery and preparation', () => {
     expect(context.content[0].text).not.toContain('later source mutation')
   })
 
-  it('projects only the direct prompt when a source message contains baked prefix context', async () => {
+  it('excludes injected context when projecting a referenced session', async () => {
     const ctx = await harness()
     const target = ctx.sessions.create(SessionId('target'))
     const source = ctx.sessions.create(SessionId('source'))
     source.append('user/message', {
-      content: [
-        { type: 'text', text: 'nested referenced snapshot must not propagate' },
-        { type: 'text', text: '\n\n## My request:\n' },
-        { type: 'text', text: 'direct source question' },
-      ],
+      content: [{ type: 'text', text: 'nested referenced snapshot must not propagate' }],
+      source: { kind: 'plugin', plugin: 'session-reference' },
+    }, { surfaceOp: 'append' })
+    source.append('user/message', {
+      content: [{ type: 'text', text: 'direct source question' }],
       source: { kind: 'user' },
-      envelope: {
-        displayContent: [{ type: 'text', text: 'direct source question' }],
-        prefixContexts: [{ source: { kind: 'plugin', plugin: 'session-reference' } }],
-      },
     }, { surfaceOp: 'append' })
 
     const prepared = await ctx.sessionReferences.prepare(
@@ -298,7 +292,7 @@ describe('session reference discovery and preparation', () => {
       [{ type: 'text', text: 'inspect source' }],
       [{ sessionId: source.id }],
     )
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context?.content[0]?.type !== 'text') throw new Error('expected text context')
     expect(promptData(context.content[0].text)).toMatchObject([{
       conversation: [{ role: 'user', text: 'direct source question' }],
@@ -322,7 +316,7 @@ describe('session reference discovery and preparation', () => {
       [{ type: 'text', text: 'use @source' }],
       [{ sessionId: source.id }],
     )
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context?.content[0]?.type !== 'text') throw new Error('expected text context')
     const prompt = context.content[0].text
     expect(prompt).toMatch(/^## Referenced sessions\n/u)
@@ -347,14 +341,14 @@ describe('session reference discovery and preparation', () => {
     const content = [{ type: 'text' as const, text: 'go' }]
 
     const withoutReferences = await ctx.sessionReferences.prepare(agent, content, [])
-    expect(withoutReferences).toEqual({ content, contexts: [] })
+    expect(withoutReferences).toEqual({ content })
     expect(withoutReferences.content).not.toBe(content)
 
     await expect(ctx.sessionReferences.prepare(agent, content, [
       { sessionId: one.id, label: 'first' },
       { sessionId: one.id, label: 'ignored duplicate' },
       { sessionId: two.id },
-    ])).resolves.toMatchObject({ contexts: [{ source: { references: [{ label: 'first' }, { label: 'two' }] } }] })
+    ])).resolves.toMatchObject({ additionalContext: { source: { references: [{ label: 'first' }, { label: 'two' }] } } })
     await expect(ctx.sessionReferences.prepare(agent, content, [{ sessionId: target.id }]))
       .rejects.toThrow(expectCode('SESSION_REFERENCE_SELF_REFERENCE'))
     await expect(ctx.sessionReferences.prepare(agent, content, [null as never]))
@@ -425,7 +419,7 @@ describe('session reference discovery and preparation', () => {
     )
 
     const prepared = await ctx.sessionReferences.prepare(fakeAgent(target), [{ type: 'text', text: 'go' }], [{ sessionId: source.id }])
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context?.content[0]?.type !== 'text') throw new Error('expected text context')
     const data = promptData(context.content[0].text) as unknown[]
     expect(Buffer.byteLength(stringifyTagSafeJson(data[0]), 'utf8')).toBeLessThanOrEqual(360)
@@ -459,7 +453,7 @@ describe('session reference discovery and preparation', () => {
       [{ type: 'text', text: 'go' }],
       sources.map(source => ({ sessionId: source.id })),
     )
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context?.content[0]?.type !== 'text') throw new Error('expected text context')
     const data = promptData(context.content[0].text) as unknown[]
     const sizes = data.map(source => Buffer.byteLength(stringifyTagSafeJson(source), 'utf8'))
@@ -492,17 +486,12 @@ describe('session reference discovery and preparation', () => {
       [{ type: 'text', text: 'use @source' }],
       [{ sessionId: source.id }],
     )
-    const context = prepared.contexts[0]
+    const context = prepared.additionalContext
     if (context === undefined) throw new Error('expected prepared context')
+    target.append('user/message', context, { surfaceOp: 'append' })
     target.append('user/message', {
-      content: [...context.content, { type: 'text', text: '\n\n## My request:\n' }, ...prepared.content],
+      content: prepared.content,
       source: { kind: 'user' },
-      envelope: {
-        displayContent: prepared.content,
-        prefixContexts: [{
-          source: context.source,
-        }],
-      },
     }, { surfaceOp: 'append' })
     const before = target.deriveMessages()
 
@@ -529,7 +518,7 @@ describe('session reference discovery and preparation', () => {
     expect(ctx.sessions.get(source.id)).toBeUndefined()
     expect(target.deriveMessages()).toEqual(before)
     expect(JSON.stringify(before)).toContain('durable referenced fact')
-    expect(JSON.stringify(before)).toContain('## My request:')
+    expect(JSON.stringify(before)).toContain('use @source')
     expect(JSON.stringify(before)).not.toContain('later source mutation')
     expect(new Session(SessionId('replayed-target'), target.events).deriveMessages()).toEqual(before)
   })