Merge origin/master into worktree/explicit-turn-signal

packages/context/time-context/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-time-context
 
-Opt-in durable context with the current zoned time and elapsed time sampled during model-request preparation. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the durable time-context RFC](../../../docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.md).
+Opt-in durable context with the current zoned time and elapsed time sampled during model-request preparation. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the durable time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md).
 
 ## Config
 
@@ -32,24 +32,32 @@ The time reading stays in derived conversation history until a later compaction
 
 ### Preparation-time temporal context
 
-**What the model sees**: On each preparation attempt that injects, one source-tagged context message containing the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; durations use compact whole-second units. Positive intervals can leave an attempted step without a new reading.
+#### What the model sees
 
-**Token effect**: Each injected two-line message accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one for every eligible preparation attempt.
+On each preparation attempt that injects, one source-tagged context message containing the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; durations use compact whole-second units. Positive intervals can leave an attempted step without a new reading.
 
-#### First step
+##### First step
 
 ```markdown
 Time sampled while preparing turn <turn>, step 1: <timestamp>
 Elapsed since the preceding model-visible message: <duration-or-unavailable>.
 ```
 
-#### Later steps
+##### Later steps
 
 ```markdown
 Time sampled while preparing turn <turn>, step <step>: <timestamp>
 Elapsed since the preceding step context: <duration-or-unavailable>.
 ```
 
+#### Token effect
+
+Each injected two-line message accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one for every eligible preparation attempt.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Whole-second display** — timestamps and durations omit sub-second precision even though durable event times retain milliseconds.

packages/context/time-context/src/index.ts

@@ -8,7 +8,6 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { Message } from '@deepseek-ai/dsh-llm'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'time-context'
@@ -162,8 +161,6 @@ export function apply(ctx: Context, config: Config): void {
     agent: Agent,
     turn: number,
     step: number,
-    _fullSystemPrompt: string,
-    _sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ) => {
     if (signal.aborted) return

packages/context/time-context/tests/time-context.e2e.ts

@@ -1,34 +1,21 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
-import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { readFile, readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { type SessionEvent } from '@deepseek-ai/dsh-session'
-import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
 
 // Keep the Loader config under examples so both modes exercise the same deployable
 // topology: local fixture source plus bare plugins owned by the examples workspace.
-const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url))
+const driver = fileURLToPath(new URL(
+  '../../../../examples/headless-agent/tests/fixtures/time-context-driver.ts',
+  import.meta.url,
+))
 const configPath = fileURLToPath(new URL(
-  '../../../../examples/echo-agent/tests/fixtures/context/time-context/cordis.yml',
+  '../../../../examples/headless-agent/tests/fixtures/time-context.cordis.yml',
   import.meta.url,
 ))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
-const PROCESS_TIMEOUT_MS = 30_000
-const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
-const FIRST_REPLY = '[main turn 1] You said: "Time sampled while preparing turn 1, step 1:'
-const SECOND_REPLY = '[main turn 2] You said: "Time sampled while preparing turn 2, step 1:'
-
-let child: ChildProcessWithoutNullStreams | undefined
-let workdir: string | undefined
-
-afterEach(async () => {
-  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
-  child = undefined
-  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
-  workdir = undefined
-})
 
 async function jsonlFiles(dir: string): Promise<string[]> {
   const entries = await readdir(dir, { withFileTypes: true })
@@ -40,68 +27,25 @@ async function jsonlFiles(dir: string): Promise<string[]> {
   return paths.flat()
 }
 
-async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> {
-  workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-'))
-  const cwd = workdir
-  return new Promise((resolve, reject) => {
-    const launch = resolveExampleLaunch({
-      srcBin: binScript,
-      configArgs: [configPath],
+describe('time-context through a real headless cordis.yml', () => {
+  it('uses the process zone and persists one ordered context event per request', async () => {
+    let events: SessionEvent[] = []
+    const { stderr } = await runLoaderSmoke({
+      label: 'time-context headless smoke',
+      tempDirPrefix: 'time-context-e2e-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
       tsconfigPath: repoTsconfig,
-      exposeInternals: true,
-      env: {
-        TZ: 'Asia/Shanghai',
-        DSH_HOME: join(cwd, '.dsh'),
-        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      env: { TZ: 'Asia/Shanghai' },
+      inspect: async (cwd) => {
+        const logs = await jsonlFiles(join(cwd, '.sessions'))
+        expect(logs).toHaveLength(1)
+        const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n')
+        events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent)
       },
     })
-    const proc = spawn(launch.command, launch.args, {
-      cwd,
-      env: { ...process.env, ...launch.env },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-    child = proc
-    let stdout = ''
-    let stderr = ''
-    let sentSecond = false
-    proc.stdout.setEncoding('utf8')
-    proc.stdout.on('data', (chunk: string) => {
-      stdout += chunk
-      if (!sentSecond && stdout.includes(FIRST_REPLY) && stdout.includes('Try "echo <something>" to see a tool call.\n> ')) {
-        sentSecond = true
-        proc.stdin.end('second\n')
-      }
-    })
-    proc.stderr.setEncoding('utf8')
-    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
-
-    const timer = setTimeout(() => {
-      proc.kill('SIGKILL')
-      reject(new Error(`time-context e2e did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`))
-    }, PROCESS_TIMEOUT_MS)
-
-    proc.on('exit', (code) => {
-      clearTimeout(timer)
-      if (code === 0) resolve({ stdout, stderr })
-      else reject(new Error(`time-context e2e exited ${code}. stdout:\n${stdout}\nstderr:\n${stderr}`))
-    })
-    proc.on('error', (error) => { clearTimeout(timer); reject(error) })
-    proc.stdin.write('first\n')
-  })
-}
-
-describe('time-context through a real cordis.yml and stdio process', () => {
-  it('uses the process zone and persists one ordered context event per request', async () => {
-    const { stdout, stderr } = await runTwoTurns()
     expect(stderr).not.toContain('UNHANDLED')
-    expect(stdout).toContain('time-context e2e ready.')
-    expect(stdout).toContain(FIRST_REPLY)
-    expect(stdout).toContain(SECOND_REPLY)
-
-    const logs = await jsonlFiles(join(workdir as string, '.sessions'))
-    expect(logs).toHaveLength(1)
-    const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n')
-    const events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent)
     expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2)
 
     const contexts = events.filter(event => event.type === 'context/message')
@@ -127,5 +71,5 @@ describe('time-context through a real cordis.yml and stdio process', () => {
 
     const headers = events.filter(event => event.type === 'request/header')
     expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing')
-  }, TEST_TIMEOUT_MS)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })

packages/context/time-context/tests/time-context.spec.ts

@@ -4,7 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -38,7 +38,7 @@ async function mount(config: Config = {}) {
 
 function sessionAgent(session: Session, id = 'agent'): Agent {
   return {
-    id: AgentId(id),
+    id: SessionId(id),
     options: {},
     session,
     status: 'running',
@@ -83,7 +83,7 @@ async function fire(
   step: number,
   signal: AbortSignal = SIGNAL,
 ): Promise<void> {
-  await ctx.serial('agent/pre-step', agent, turn, step, '', [], signal)
+  await ctx.serial('agent/pre-step', agent, turn, step, signal)
 }
 
 function textResponse(text: string): StreamChunk[] {
@@ -370,7 +370,7 @@ describe('real agent-loop request history', () => {
       if (mode === 'throws') throw new Error('later pre-step failure')
       subject.cancel({ kind: 'user' })
     })
-    const agent = ctx.agentLoop.create(AgentId(`late-${mode}`), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
@@ -396,7 +396,7 @@ describe('real agent-loop request history', () => {
         return [{ type: 'text' as const, text: 'advanced' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('loop'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()