Merge remote-tracking branch 'origin/master' into worktree/pr468-retarget-latest-master

# Conflicts: # docs/architecture.i18n.yaml # docs/config-catalog.md # docs/event-producer-consumer.md # docs/module-graph.md # packages/examples/acp-demo/README.md # packages/examples/acp-demo/src/index.ts # packages/examples/acp-demo/tests/built-bin.e2e.ts # packages/examples/tui-demo/package.json # packages/examples/tui-demo/src/index.ts # packages/examples/tui-demo/tests/tui-agent.spec.ts
2026-07-22 22:38:17 +08:00
parent 7a8d5da3d3 54aaab6807
commit e962642926
76 changed files with 1342 additions and 108 deletions
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -16,13 +16,14 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
 | `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | exact current-surface reads and bounded `dsh-session:` snapshots |
+| `@deepseek-ai/dsh-session-checkpoint-policy` | semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
 | ~~`@deepseek-ai/dsh-user-approval`~~ | **omitted by default** — permission policy is deployment-specific; sandbox/approval leaves opt in and the ACP bridge then supplies the answerer |
 | ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../../ui/acp/README.md)) |
 | ~~`hmr`~~ | **omitted** — the editor owns the subprocess |

-Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends. A leaf author can still add `@cordisjs/plugin-logger-console` as a sibling entry, so the rule remains: never add a stdout logger to an ACP leaf; use a stderr exporter instead.
+The app owns this cluster through one ordered Cordis effect. Teardown drains the ACP bridge before removing the checkpoint policy or persistence backend, so a graceful disconnect persists the real closing `step/end` and `turn/end` events rather than leaving crash recovery to synthesize them. Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends. A leaf author can still add `@cordisjs/plugin-logger-console` as a sibling entry, so the rule remains: never add a stdout logger to an ACP leaf; use a stderr exporter instead.

 ## Config

@@ -44,6 +45,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | `llmRetry` | owner defaults | bounded transient model-request retry policy routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
+| `sessionReferences` | service defaults | cross-session candidate and snapshot limits routed to `dsh-session-reference` |

 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay), a bash executor, and optionally a `ctx.fs` provider. Workspace context becomes a no-op without `ctx.fs`; the shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) selects `dsh-sandbox-policy`, `dsh-fs-sandbox`, `dsh-fs-policy`, and `dsh-tool-fs` so baseline instructions and model-facing `read`/`write`/`edit` share one provider, sandbox mode, workspace root, and observed-version policy.

--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -43,6 +43,7 @@
    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-app-boot": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-session-query": "^0.0.1",
    "@deepseek-ai/dsh-session-reference": "^0.0.1",
@@ -62,6 +63,7 @@
    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-session-query": "workspace:^",
    "@deepseek-ai/dsh-session-reference": "workspace:^",
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -1,7 +1,9 @@
 /**
 * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}),
 * human-command registry, JSONL session persistence, and the
- * {@link @deepseek-ai/dsh-acp} bridge. It writes nothing to stdout.
+ * {@link @deepseek-ai/dsh-acp} bridge. The app owns those plugins through one
+ * ordered lifecycle so ACP sessions quiesce before persistence detaches. It
+ * writes nothing to stdout.
 * It pre-creates no agents and leaves adapters, executors, and optional tools to
 * the leaf, which must likewise avoid stdout loggers. Named exports are
 * required so Loader retains this plugin's `Config` schema (see
@@ -21,6 +23,7 @@ import SessionPersistenceJsonl, {
  JsonlCompressionSchema,
  type JsonlCompression,
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
@@ -106,23 +109,24 @@ export const Config: z<Config> = z.object({
 * NO agents (its `agents` list defaults to `[]`) and carries the deployment
 * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
 * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
- * from the provider/model pair. No logger, no `hmr` — stdout stays pure.
+ * from the provider/model pair. The composite effect unloads in reverse order,
+ * keeping checkpoint and persistence listeners attached until ACP agents have
+ * flushed their closing events. No logger, no `hmr` — stdout stays pure.
 */
 export function apply(ctx: Context, config: Config): void {
  const goals = config.goals ?? {}
-  ctx.plugin(CommandService)
-  if (goals !== false) ctx.plugin(commandGoal)
-  ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals })
-  // This front door owns the same persistence/reference cluster as the TUI;
-  // extracting these few calls would introduce a shared app-composition facade.
-  /* jscpd:ignore-start */
-  ctx.plugin(UserInteractionService)
-  ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
-    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-  })
-  ctx.plugin(SessionQueryService)
-  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
-  /* jscpd:ignore-end */
-  ctx.plugin(acp, { provider: config.provider, model: config.model })
+  ctx.effect(function* () {
+    yield ctx.plugin(CommandService).dispose
+    if (goals !== false) yield ctx.plugin(commandGoal).dispose
+    yield ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals }).dispose
+    yield ctx.plugin(UserInteractionService).dispose
+    yield ctx.plugin(SessionPersistenceJsonl, {
+      root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+      ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
+    }).dispose
+    yield ctx.plugin(sessionCheckpointPolicy).dispose
+    yield ctx.plugin(SessionQueryService).dispose
+    yield ctx.plugin(SessionReferenceService, config.sessionReferences ?? {}).dispose
+    yield ctx.plugin(acp, { provider: config.provider, model: config.model }).dispose
+  }, 'acp-demo.composition')
 }
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -36,8 +36,8 @@ const dshPackages = [
  'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
  'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'session-query/session-query',
-  'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
+  'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
+  'session-query/session-query', 'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -50,6 +50,9 @@
    {
      "path": "../../ui/tool-ask-user"
    },
+    {
+      "path": "../../session-persistence/session-checkpoint-policy"
+    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
    },
--- a/packages/examples/cli-demo/package.json
+++ b/packages/examples/cli-demo/package.json
@@ -43,6 +43,7 @@
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
@@ -58,6 +59,7 @@
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
--- a/packages/examples/cli-demo/src/index.ts
+++ b/packages/examples/cli-demo/src/index.ts
@@ -15,6 +15,7 @@ import SessionPersistenceJsonl, {
  JsonlCompressionSchema,
  type JsonlCompression,
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'

 const DEFAULT_PERSISTENCE_ROOT = './.sessions'
@@ -94,4 +95,5 @@ export function apply(ctx: Context, config: Config): void {
    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
  })
+  ctx.plugin(sessionCheckpointPolicy)
 }
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -24,7 +24,8 @@ const dshPackages = [
  'examples/agent-spine-demo', 'examples/cli-demo', 'core/agent', 'core/session',
  'core/system-prompt', 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
-  'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl',
+  'session-persistence/session-persistence', 'session-persistence/session-checkpoint-policy',
+  'session-persistence/session-persistence-jsonl',
  'context/workspace-context',
  'spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention',
 ]
--- a/packages/examples/cli-demo/tsconfig.json
+++ b/packages/examples/cli-demo/tsconfig.json
@@ -32,6 +32,9 @@
    {
      "path": "../agent-spine-demo"
    },
+    {
+      "path": "../../session-persistence/session-checkpoint-policy"
+    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
    },
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -12,6 +12,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-commands` | Human-only discovery and dispatch consumed by the TUI and command plugins |
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
+| `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | Exact current-surface reads and bounded `@session` snapshots consumed by the TUI |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
@@ -38,6 +39,7 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `workspaceContext` | required | Workspace-instruction config, or `false` |
 | `persistenceRoot` | `./.sessions` | JSONL persistence root |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
+| `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
 | `welcome` | `ready.` | TUI subtitle |
 | `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height |
 | `resumeSessionId` | — | Exact persisted session to resume |
--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -46,6 +46,7 @@
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
    "@deepseek-ai/dsh-session-query": "^0.0.1",
    "@deepseek-ai/dsh-session-reference": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
@@ -69,6 +70,7 @@
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
    "@deepseek-ai/dsh-session-query": "workspace:^",
    "@deepseek-ai/dsh-session-reference": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -21,6 +21,7 @@ import SessionPersistenceJsonl, {
  JsonlCompressionSchema,
  type JsonlCompression,
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQueryService from '@deepseek-ai/dsh-session-query'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
@@ -124,6 +125,7 @@ export function composeTuiApp(ctx: Context, config: Config): void {
    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
  })
+  ctx.plugin(sessionCheckpointPolicy)
  ctx.plugin(SessionQueryService)
  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
  ctx.plugin(UserInteractionService)
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -50,6 +50,7 @@ describe('dsh-tui-demo app', () => {
      'CommandService',
      'command-goal',
      'SessionPersistenceJsonl',
+      'session-checkpoint-policy',
      'SessionQueryService',
      'SessionReferenceService',
      'UserInteractionService',
@@ -59,12 +60,12 @@ describe('dsh-tui-demo app', () => {
    ])
    expect(calls[0]?.config).toBeUndefined()
    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[4]?.config).toEqual({
+    expect(calls[5]?.config).toEqual({
      maxReferences: 2,
      candidateLimit: 7,
      maxReferenceBytes: 1234,
    })
-    const tuiConfig = calls[6]?.config as { sessionId: string }
+    const tuiConfig = calls[7]?.config as { sessionId: string }
    expect(tuiConfig).toMatchObject({
      welcome: 'TUI ready',
      resumeCommand: 'dsh --resume {session}',
@@ -72,7 +73,7 @@ describe('dsh-tui-demo app', () => {
      maxToolOutputLines: 3,
    })
    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[7]?.config as {
+    const spineConfig = calls[8]?.config as {
      readonly agents: Array<Record<string, unknown>>
      readonly goals: Record<string, never>
      readonly maxParallelToolCalls: number
@@ -106,10 +107,10 @@ describe('dsh-tui-demo app', () => {
    })

    expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[4]?.config).toEqual({})
+    expect(calls[5]?.config).toEqual({})
    // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[6]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
+    expect(calls[7]?.config).toEqual({ sessionId: 'persisted-session' })
+    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
      id: 'main',
      resumeSessionId: 'persisted-session',
    })
@@ -125,12 +126,12 @@ describe('dsh-tui-demo app', () => {
      workspaceContext: false,
    })

-    const tuiConfig = calls[5]?.config as { sessionId: string }
+    const tuiConfig = calls[6]?.config as { sessionId: string }
    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[6]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
+    expect((calls[7]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
      .toMatchObject({ sessionId: tuiConfig.sessionId })
    expect(calls.map(call => call.name)).not.toContain('command-goal')
-    expect(calls[6]?.config).toMatchObject({ goals: false })
+    expect(calls[7]?.config).toMatchObject({ goals: false })
  })

  it('has the namespace-plugin export shape so the Loader keeps its schema', () => {
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -53,6 +53,9 @@
    {
      "path": "../../ui/tool-ask-user"
    },
+    {
+      "path": "../../session-persistence/session-checkpoint-policy"
+    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
    },