feat(invariants): add package-owned service seam

packages/core/agent-loop/README.md

@@ -27,6 +27,10 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo
 
 `agents`, `sessions`, `llm`, `tools`, `systemPrompt` — all five interface services.
 
+### Invariant companion
+
+The optional `@deepseek-ai/dsh-agent-loop/invariant` companion registers request reconstruction with `ctx.invariants`. For each frozen loop-built request carrying a live session id, it independently rebuilds the message boundary and folded request header from the session log; direct one-shot calls remain outside this marker contract.
+
 ### Configuration (schemastery)
 
 ```ts

packages/core/agent-loop/package.json

@@ -11,10 +11,15 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -22,6 +27,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-scope": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",

packages/core/agent-loop/src/invariant.ts

@@ -0,0 +1,73 @@
+/**
+ * Package-owned request-reconstruction invariant for loop-built LLM calls.
+ * @module @deepseek-ai/dsh-agent-loop/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-loop-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants', 'sessions']
+
+/** Install the request-reconstruction contribution into its child registration fiber. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  // Prepend prevents a short-circuiting replay listener from silencing the
+  // check; correctness itself comes from the sequence-bounded reconstruction.
+  ctx.on('llm/stream', (options: GenerateOptions, next) => {
+    if (options.sessionId === undefined || !Object.isFrozen(options)) return next()
+    const session = ctx.sessions.get(options.sessionId)
+    if (!session) return next()
+    if (!Object.isFrozen(options.messages)) {
+      fail('a loop-built request must carry a frozen messages array')
+    }
+
+    const events = session.events
+    let boundary = -1
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      if (events[index]?.type === 'step/start') {
+        boundary = index
+        break
+      }
+    }
+    if (boundary === -1) {
+      return fail('a loop-built request with no step/start in its session log')
+    }
+    const header = foldRequestHeader(events)
+    if (header === undefined) {
+      return fail('a loop-built request with no request/header event in its session log')
+    }
+    const rebuilt = new Session(
+      SessionId(`${String(session.id)}-invariant-rebuild`),
+      structuredClone(events.slice(0, boundary)),
+    )
+    const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
+    if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
+      fail(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
+    }
+
+    const headerMatches = options.model === header.config.model
+      && options.system === header.system
+      && options.temperature === header.config.temperature
+      && options.maxTokens === header.config.maxTokens
+      && JSON.stringify(options.stop) === JSON.stringify(header.config.stop)
+      && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? [])
+    if (!headerMatches) {
+      fail(`llm request for session "${String(session.id)}" diverges from the folded request header`)
+    }
+    return next()
+  }, { global: true, prepend: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the agent-loop invariant companion.
+ * @param ctx - Cordis context carrying the invariant and session services.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -7,9 +7,19 @@ import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/ds
 import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
+async function mountInvariants(ctx: Context): Promise<void> {
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SessionInvariant)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoopInvariant)
+}
+
 function driverDone(agent: Agent): Promise<void> {
   return (agent as Agent & { done: Promise<void> }).done
 }
@@ -144,7 +154,7 @@ describe('successful provider completion survives agent/step-result failure', ()
   ): Promise<void> {
     const adapter = new MockAdapter([response])
     const ctx = await harness(adapter)
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     const agent = ctx.agentLoop.create(SessionId(id), { provider: 'mock', model: 'mock' })
     const failure = new Error(`${id} result processing failed`)
     const reported: Error[] = []
@@ -1014,7 +1024,7 @@ describe('step boundary publication order', () => {
 })
 
 describe('turn and step boundary recovery', () => {
-  // The invariants plugin makes an unbalanced log fail the test.
+  // The session invariant companion makes an unbalanced log fail the test.
   async function balancedHarness(adapter: MockAdapter) {
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -1023,7 +1033,7 @@ describe('turn and step boundary recovery', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
     return ctx
   }
@@ -1437,7 +1447,7 @@ describe('surface: assistant/message records exact empty provenance when no chun
     // stream from legacy events whose provenance was not recorded.
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
@@ -1474,7 +1484,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
     // Parent-owned listener survives agent-fiber disposal.
@@ -1525,7 +1535,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
     const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
@@ -1580,7 +1590,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
     ctx.on('agent/pre-step', async () => {
@@ -1631,7 +1641,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
     ctx.on('agent/pre-step', async () => {
@@ -1680,7 +1690,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
     ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {

packages/core/agent-loop/tests/invariant.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentLoopInvariant)
+  return ctx
+}
+
+function dispatch(ctx: Context, options: unknown): void {
+  void ctx.waterfall('llm/stream', options as never, () => (async function* () {})() as never)
+}
+
+async function requestSetup() {
+  const ctx = await setup()
+  const session = ctx.sessions.create(SessionId('req-check'))
+  session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+  const boundary = session.deriveMessages()
+  session.append('step/start', { turn: 1, step: 1 })
+  session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+  return { ctx, session, boundary }
+}
+
+describe('request-reconstruction invariant', () => {
+  it('accepts a frozen request equal to the boundary derivation and folded header', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+    expect(() => { dispatch(ctx, options) }).not.toThrow()
+  })
+
+  it('uses the step boundary rather than content appended afterward', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
+    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+    expect(() => { dispatch(ctx, options) }).not.toThrow()
+  })
+
+  it('requires the folded session prefix ahead of derived history', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' })
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })) })
+      .not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+  })
+
+  it('rejects message and header divergence', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const divergent = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }]
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze(divergent), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'other', messages: Object.freeze(boundary), sessionId: session.id })) })
+      .toThrow(/diverges from the folded request header/)
+  })
+
+  it('rejects loop requests with no boundary or header', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create(SessionId('req-bare'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const bare = Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: session.id })
+    expect(() => { dispatch(ctx, bare) }).toThrow(/no step\/start/)
+    session.append('step/start', { turn: 1, step: 1 })
+    expect(() => { dispatch(ctx, bare) }).toThrow(/no request\/header event/)
+  })
+
+  it('rejects an unfrozen messages array but skips requests outside the loop contract', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: [...boundary], sessionId: session.id })) })
+      .toThrow(/frozen messages array/)
+    expect(() => { dispatch(ctx, { model: 'summarizer', messages: [], sessionId: session.id }) }).not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]) })) }).not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: SessionId('ghost') })) })
+      .not.toThrow()
+  })
+
+  it('prepends ahead of a short-circuiting stream listener', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    ctx.on('llm/stream', () => (async function* () {})() as never)
+    await ctx.plugin(InvariantService)
+    await ctx.plugin(AgentLoopInvariant)
+    const session = ctx.sessions.create(SessionId('prepend-check'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+    const divergent = Object.freeze({
+      model: 'm',
+      messages: Object.freeze([{ role: 'user', content: [{ type: 'text', text: 'phantom' }] }]),
+      sessionId: session.id,
+    })
+    expect(() => { dispatch(ctx, divergent) }).toThrow(/diverges from the boundary derivation/)
+  })
+})

packages/core/agent-loop/tests/turn-stop.spec.ts

@@ -7,9 +7,19 @@ import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent, type ContinuationStop } from '@deepseek-ai/dsh-agent'
 
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
+async function mountInvariants(ctx: Context): Promise<void> {
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SessionInvariant)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoopInvariant)
+}
+
 async function harness(adapter: MockAdapter): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
@@ -17,7 +27,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
-  await ctx.plugin(Invariants)
+  await mountInvariants(ctx)
   await ctx.plugin(AgentLoop, { agents: [] })
   ctx.llm.registerAdapter(['mock'], adapter)
   return ctx

packages/core/agent-loop/tsconfig.json

@@ -37,6 +37,9 @@
     },
     {
       "path": "../../core/scope"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }

packages/core/agent-loop/tsdown.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])