Merge branch 'codex/simp-compaction-surface' into codex/simp-agent-entry-state

AGENTS.md

@@ -18,6 +18,7 @@ packages/    Harness packages at packages/<group>/<pkg>/, all named @deepseek-ai
   skill/       skill provider registry + local impl + catalog/loader tool
   web/         web seam + search/fetch providers + model-facing web tools
   compact/     compaction seam + basic backend
+  context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
   workflow/    workflow seam + worker-thread engine + the workflow tool
   todo/        the todo_write tool
@@ -34,7 +35,7 @@ docs/        architecture, generated catalogs, RFCs, postmortems, cookbook (see
 scripts/     repo gates and generators
 ```
 
-Per-package map: the group READMEs, indexed from [packages/README.md](packages/README.md).
+Package groups: [packages/README.md](packages/README.md).
 
 ## Commands
 

docs/config-catalog.md

@@ -780,6 +780,22 @@ export interface Config {
 
 Source: [`packages/core/system-prompt/src/index.ts:147`](../packages/core/system-prompt/src/index.ts)
 
+## `@deepseek-ai/dsh-time-context`
+
+Requires: `systemPrompt`
+
+```ts config-catalog
+/** Request-time clock formatting and refresh policy. Invalid values fail plugin load. */
+export interface Config {
+  /** IANA time zone used for the rendered timestamp. Omit to resolve the Node process's system zone at plugin load. */
+  timeZone?: string
+  /** Maximum age of a reading within one turn, in milliseconds (default 60,000; `0` refreshes every step). */
+  refreshIntervalMs?: number
+}
+```
+
+Source: [`packages/context/time-context/src/index.ts:22`](../packages/context/time-context/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-cordis`
 
 Requires: `tools`

docs/cookbook/adding-a-package.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+adding-a-package.md: 2930cee9ab64b382f6211335ae639bce45629d1d
+adding-a-package.zh.md: 10e906c320203c3658c103fc8936540f72697d65

docs/cookbook/adding-a-package.md

@@ -1,6 +1,8 @@
 # Cookbook: adding a workspace package
 
-The file-by-file checklist for a new `@deepseek-ai/dsh-<name>` package. (Verified by the bash and adapter packages; if it drifts, fix it here.)
+English | [中文](adding-a-package.zh.md)
+
+The file-by-file checklist for a new `@deepseek-ai/dsh-<name>` package. This checklist is validated against the bash and adapter packages as templates; if it drifts from them, fix it here.
 
 ## 1. Create the package
 

docs/cookbook/adding-a-package.zh.md

@@ -0,0 +1,83 @@
+# 实操手册：添加 workspace 包（package）
+
+[English](adding-a-package.md) | 中文
+
+为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和 adapter 这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
+
+## 1. 创建包
+
+```
+packages/<group>/<pkg>/
+  package.json     # copy from packages/core/tools, adjust name/description/deps
+  tsconfig.json    # extends ../../../tsconfig.base.json, rootDir src,
+                   # outDir lib/types, references: ../../../vendor/cosmokit,
+                   # ../../../vendor/cordis (+ ../../../vendor/schemastery if
+                   # you use Config, + ../../<group>/<dep> for each dsh dep)
+  src/index.ts     # service default export or plugin (name/inject/apply/Config)
+  tests/<x>.spec.ts
+  README.md        # service API, events, extension points, design notes,
+                   # + gated Model Experience context blocks or short sentence
+                   # + the gated "Known Limitations and Deferred Work" section
+                   # (or a whitelist entry in scripts/verify-package-readme-limitations.ts)
+```
+
+当已有分组与包的角色匹配时，选择该分组（`core`、`llm`、`bash`、`compact`、`subagent`、`todo`、`session-persistence`、`ui`、`util` 或 `support`）。允许新建分组，但分组只是纯容器：没有 `package.json`，没有源文件，包仍然恰好位于其下一层。
+
+package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表要精确：`lib/index.js`、`lib/types/**/*.d.ts`、`lib/types/**/*.d.ts.map` 和 `src`；不要发布 `lib/types` 下的 JS 或 JS-map 中间产物，也不要发布陈旧的根声明文件。带有 `bin` 的 CLI 应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
+
+包内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export * from './types.ts'`）。编译器在输出的 JS 中将其重写为 `.js`，在声明文件中保留显式 `.ts` 后缀；标准的 NodeNext/Node16 TypeScript 消费方会将其解析到同目录的 `.d.ts` 文件。
+
+## 2. 在根配置中注册
+
+| 文件 | 变更 |
+|---|---|
+| `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
+| `tsconfig.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` |
+| `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` |
+| `knip.json` | 仅当包有非 `*.spec.ts` 入口时需要（如 `*.e2e.ts` → 添加 per-workspace override，参照 `packages/llm/llm-deepseek`） |
+
+以下内容由 glob 或包 manifest 发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`、`scripts/check-workspace-constraints.ts`。
+
+## 3. 确定包拓扑
+
+对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
+
+## 4. 编写包 README
+
+将包特有的服务 API、配置、事件、扩展点和设计说明放在前面。limitations 部分记录持久的消费方缺口和本包拥有的非显而易见的维护者约束；日常清理事项留在源码 TODO 或 RFC 中。间接的 Model Experience 语句可以点名暴露本包贡献的消费方，但不重述该消费方的实现。包 README 以如下规范序列结尾：
+
+````markdown
+## Model Experience
+
+### Request surface and condition
+
+**What the model sees**: An exact data-dependent shape, an anchored generated-catalog link, or an introduction to the verbatim literal below.
+
+**Token effect**: Fixed, conditional, retained, replaced, capped, or zero-direct token effect.
+
+#### Verbatim text for this context surface, when needed
+
+```markdown
+Stable system-prompt prose of any length, or another long non-generated literal, copied exactly from source.
+```
+
+## Known Limitations and Deferred Work
+
+- **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
+````
+
+根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述两个字段。引用包拥有的稳定文本：系统提示词放在带标题的 H4 加 `markdown` 围栏中，其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
+
+没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience RFC](../rfc/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
+
+## 5. 验证
+
+```sh
+pnpm install        # registers the workspace
+pnpm run doc-sync
+pnpm run constraints && pnpm run typecheck && pnpm run lint
+pnpm run test:coverage  # 100% per-file over src (types.ts exempt)
+pnpm run build && pnpm run hygiene
+```
+
+测试要求：每个注册表/注册操作都需要一个 HMR（热模块替换）安全测试（从子 fiber 注册，dispose（资源释放）它，断言清理完成）。鼓励编写充分的测试——见 [docs/testing.md](../testing.md)。

docs/cookbook/adding-a-tool.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+adding-a-tool.md: 4920c98894326fb8eab3b3d5df298baf1da33c1d
+adding-a-tool.zh.md: 3caf1e62f15f2f15103836b4d3f22be20ba02385

docs/cookbook/adding-a-tool.md

@@ -1,5 +1,7 @@
 # Cookbook: adding a tool
 
+English | [中文](adding-a-tool.zh.md)
+
 How to give the model a new capability. Reference implementations: `examples/echo-agent/src/echo-tool.ts` (minimal) and `packages/bash/tool-bash` (production-grade, three-package seam).
 
 ## The minimal shape
@@ -49,7 +51,7 @@ Follow tool-bash's background pattern: a `run_in_background` flag returns a task
 
 ## Execution policy and observation
 
-Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](./extension-cookbook.md#a-hook-plugin-permission-gate)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap core dispatch with a deadline/retry/metrics scope, `tools/post-execute` to transform or attach model-facing context, and `tools/result` to observe the immutable normalized outcome without changing it. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points).
+Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](./extension-cookbook.md#a-hook-plugin-permission-gate-example)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap core dispatch with a deadline/retry/metrics scope, `tools/post-execute` to transform or attach model-facing context, and `tools/result` to observe the immutable normalized outcome without changing it. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points).
 
 ## Code Mode reaches your tool for free
 

docs/cookbook/adding-a-tool.zh.md

@@ -0,0 +1,85 @@
+# 实操手册：添加工具
+
+[English](adding-a-tool.md) | 中文
+
+如何为模型赋予一项新能力。参考实现：`examples/echo-agent/src/echo-tool.ts`（最小化）和 `packages/bash/tool-bash`（生产级，由三个包（package）构成的 seam）。
+
+## 最小形态
+
+```ts
+import { readFile } from 'node:fs/promises'
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'my-tool'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  ctx.tools.register(defineTool({
+    name: 'read_file',
+    description: 'Read a file from disk.',          // what the model sees
+    parameters: {
+      path: { type: 'string', required: true, description: 'Absolute path' },
+      limit: { type: 'number' },                     // optional by default
+    },
+    async execute(args, exec) {
+      // args is TYPED from the schema: { path: string; limit?: number }
+      // exec carries immutable identity + token; signal is the operational field
+      return [{ type: 'text', text: await readFile(args.path, 'utf8') }]
+    },
+  }))
+}
+```
+
+注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具（请编写 HMR（热模块替换）测试）。schema 会自动流入系统提示词的组装过程。
+
+## execute() 契约的规则
+
+- **参数已为你校验。** `defineTool` 在 `execute` 运行前，会根据 `SchemaSpec` 校验模型生成的 `arguments`（类型、必填键、枚举成员、嵌套对象/数组——见[运行时参数校验](../rfc/implemented/architecture/2026-06-11-runtime-arg-validation.md)），因此 `execute` 内部的 args 已匹配 `InferArgs`。你仍需手动检查 DSL 无法表达的值约束（非空字符串、正数、跨字段规则），对这些情况抛出描述性 Error。直接注册的原始 JSON-Schema 工具（MCP）不由 harness 校验，它们自行校验输入。
+- **注册借用你的只读定义。** 类型化的同进程贡献不是序列化边界；注册后不要修改其 schema 或替换回调。`schemas()` 只物化显式的模型可见投影。如需热替换工具，请 dispose 其所属副作用并注册替代品；回调闭包内的可变状态仍是普通的插件状态。
+- **执行身份受保护。** 注册表在一次递归遍历中将 `arguments` 物化为分离的无损 JSON，在策略开始前冻结该值，并分配一个不透明的 `exec.token`；`callId`、`name`、`arguments`、`agent`、`token` 以及可选的外层传输 `parent` token 在整个分发过程中保持不可变。`parent` 仅用于身份标识，不暴露活跃的外层执行。请将 `args` 视为只读输入。around-dispatch 包装器只能添加、替换或移除 `exec.signal`，以施加取消或截止时间。
+- **抛出异常或返回非 JSON 数据意味着 `isError`。** 注册表捕获异常，并在观察者运行前物化最终结果。格式错误或非 JSON 的结果变为 `{ isError: true }`，防止出现无法记录的活跃成功。基础设施故障请抛异常；当模型需要解读领域失败时，请在结果文本中报告。
+- **遵守 `exec.signal`。** 信号触发时取消进行中的工作。
+- **使用 `meta` 附加持久化的卡片数据（可选）。** `execute` 可以返回 `{ content, meta }` 而非裸的 `ContentBlock[]`。`meta` 是 JSON 可序列化的载荷，核心将其视为不透明数据，持久化在 `tool/result` 事件上并回传给你的 `presentResult`（这样需要 `args` 之外信息的卡片——如 `write`/`edit` 的已应用 hunk diff——在会话回放中依然存活）。仅在此处放 UI 数据，绝不放入模型可见的 `content`。
+- **使用 `exec.agent` 发送异步通知。** `agent.inject(content, {source: {kind: 'plugin', plugin: '<name>'}})` 追加持久化上下文，下一次模型请求会看到它——这不是唤醒（空闲的 agent（智能体）保持空闲）。请防范已 dispose 的 agent（try/catch）。
+
+## 长时间运行的工作
+
+遵循 tool-bash 的后台模式：`run_in_background` 标志立即返回一个 task id；配套工具增量轮询和终止；完成通知通过 `agent.inject()` 到达。限定缓冲区大小，将完整输出溢写到磁盘，避免静默丢失。
+
+> TODO: 目前每个工具都手动重新实现这套后台模式。未来需要一个通用的长时间运行工具层，统一处理 task id、增量轮询、终止和完成通知。
+
+## 执行策略与观测
+
+尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许/拒绝/询问策略（见[权限门禁示例](./extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝（后续监听器无法撤销）；使用 `tools/execute` 为核心分发包装截止时间/重试/指标作用域；使用 `tools/post-execute` 转换或附加模型可见的上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
+
+## Code Mode 自动触达你的工具
+
+在 [Code Mode](../../packages/core/tools/README.md) 中，每个可见的已注册工具都可通过 `await tools.<name>(args)` 调用，无需额外集成。SDK 从同一份 JSON Schema 派生参数，调用重新进入正常的执行流水线。请将描述写成面向模型的 API 文档；非文本结果块在程序中变为占位符。
+
+## 工具在编辑器中的渲染方式（ACP 展示）
+
+工具的 `execute` 返回模型可见的内容；其**编辑器卡片**是一个独立的、可选的关注点，通过 `defineTool` 选项中的两个纯展示方法声明。请与 `execute` 同步设计，而非事后补充——编辑器（如 Zed，通过 ACP（Agent Client Protocol）桥接）会展示该卡片，没有展示方法的工具回退为一个朴素的通用卡片（标题 = 工具名，原始 args 作为输入）。
+
+两个方法都返回一个 **`card` 标签的渲染意图**——选择与你的工具行为匹配的卡片类型：
+
+- `presentCall(args)` → 一个 `ToolCallView`（PENDING 卡片）：
+  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`——默认。设置 `kind` 获取图标（`read`/`search`/…）；设置 `locations: [{ path, line? }]` 标注工具涉及的文件，使有能力的编辑器跟随/跳转。
+  - `{ card: 'terminal', title, description?, cwd? }`——你的调用本身就是 shell 命令。`title` 是命令，`description` 渲染在终端卡片上方。（tool-bash。）
+  - `{ card: 'diff', title, diffs, locations? }`——你的调用创建或修改文件。`diffs: [{ path, oldText, newText }]`（新文件时 `oldText: null`）渲染为内联 diff 卡片。（tool-fs `write`/`edit`。）
+- `presentResult(args, { content, isError, meta? })` 返回完成后的卡片：
+  - `generic` 提供可选的标题和内容。
+  - `terminal` 提供原始输出和可选的退出元数据；桥接层渲染能力特定或围栏回退视图。
+  - `diff` 提供已应用的 hunk，通常由持久化的 `result.meta` 携带，使回放能重现它们。变更类工具保留 diff 结果，因为 ACP 更新会替换 pending 卡片的内容。
+
+硬性规则（违反会出问题）：
+
+- **纯函数。** 这些方法在实时流式输出和会话日志回放时都会运行，因此必须是 `args`（加 result）的纯函数——不做 I/O、不读会话状态、不用时钟/随机数。diff 从 args 派生（`write` 使用 `oldText: null`，因为调用时的展示器没有文件先前内容）；**桥接层**（而非工具）填充会话 cwd 并相对化展示路径标题。如果你发现自己想在 `presentCall` 内获取文件旧内容或工作目录，请停下——那属于桥接层或未来的 result-event 形态，不属于展示器。
+- **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径——这些都不得出现在 `execute` 返回给模型的内容中；它们只存在于展示层。（`terminal` 结果视图携带原始 `output`；桥接层添加围栏。）
+- **`defineTool` 对展示路径做软校验。** 格式错误或旧版日志中的 arg 形态会使包装器返回 `undefined`（通用回退）而非抛异常——展示绝不能导致回放崩溃。
+
+中性词汇定义在 `dsh-tools` 中（绝不在工具中导入 ACP 类型）；ACP 桥接层将每个 `card` 映射到协议格式（wire format）。设计与原因见[渲染意图联合体 RFC](../rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md)；`dsh-tool-fs`（generic/diff）和 `dsh-tool-bash`（terminal）是参考实现。
+
+## 每个工具必须的测试
+
+覆盖参数拒绝、每种结果形态和 HMR dispose。对于有副作用的工具，使用脚本化的 `MockAdapter` 驱动真实工具通过 agent loop（智能体循环），并断言其 `tool/call` 和 `tool/result` 会话事件。对于编辑器卡片，断言 `presentCall` 和 `presentResult` 的精确视图，并通过真实桥接层添加一个 [ACP 快照](../rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)；终端卡片的场景设置 `terminalOutput: true` 以覆盖 capable-client 路径。

docs/cookbook/adding-a-vendored-package.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+adding-a-vendored-package.md: d7b5b93b59fb39d8369be6eb42fb0a8b977c68b4
+adding-a-vendored-package.zh.md: 86b1e6c959180ba15b6fcb56b6dfe5a3be791b47

docs/cookbook/adding-a-vendored-package.md

@@ -1,5 +1,7 @@
 # Cookbook: adding a vendored package
 
+English | [中文](adding-a-vendored-package.zh.md)
+
 When the harness needs another upstream Cordis package (e.g. `@cordisjs/plugin-http`), it is **vendored** as pinned source under `vendor/`, not added as an npm dependency — see [the vendoring decision](../rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md) for why. [vendor/README.md](../../vendor/README.md) covers *updating* an already-vendored package; this guide is the file-by-file checklist for adding a **new** one. (Verified against the existing vendored set; if it drifts, fix it here.)
 
 ## 1. Copy the source in

docs/cookbook/adding-a-vendored-package.zh.md

@@ -0,0 +1,60 @@
+# 实操手册：添加一个 vendored 包（package）
+
+[English](adding-a-vendored-package.md) | 中文
+
+当 harness 需要引入另一个上游 Cordis 包（如 `@cordisjs/plugin-http`）时，应将其作为固定版本的源码 **vendor** 到 `vendor/` 下，而非作为 npm 依赖添加——原因见[vendoring 决策](../rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md)。[vendor/README.md](../../vendor/README.md) 介绍如何*更新*已有的 vendored 包；本指南是添加**新** vendored 包的逐文件清单。（已对照现有 vendored 集合验证；如有偏差，请在此修正。）
+
+## 1. 复制源码
+
+```
+vendor/<dir>/
+  package.json     # from upstream; set "private": true, keep name/exports/type
+  tsconfig.json    # extends ../../tsconfig.base.json (see shape below)
+  src/             # the upstream src/ verbatim
+  README.md LICENSE # if upstream ships them
+```
+
+`tsconfig.json` 与其他 vendored 包保持一致：`rootDir: src`、`outDir: lib/types`、上游代码所需的严格性放宽项，以及对所导入的每个其他 vendored 包的 `references` 条目：
+
+```jsonc
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src", "outDir": "lib/types",
+    "noUncheckedIndexedAccess": false, "exactOptionalPropertyTypes": false,
+    "noImplicitOverride": false, "noUnusedLocals": false, "noUnusedParameters": false
+  },
+  "include": ["src"],
+  "references": [{ "path": "../cordis" }, { "path": "../cosmokit" }]
+}
+```
+
+`package.json` 的不变式：`"private": true`（vendored 包永不发布）；保留上游的 `name`/`version`/`exports`/`type`；声明元数据指向 `lib/types`；发布 `.d.ts` 与 `.d.ts.map` 声明输出；在 `peerDependencies` 中列出其 Cordis 依赖（与上游 manifest（元数据清单）一致）。传递性上游依赖本身也必须被 vendor 或已存在于仓库中——vendor 一个包往往意味着 vendor 其整条依赖树（如 `@cordisjs/plugin-http` 会拉入 `@cordisjs/fetch-file`）。
+
+vendored TypeScript 源码中的本地相对导入/导出在复制后使用显式 `.ts` 后缀。这是仓库本地的构建形态与上游的差异：`rewriteRelativeImportExtensions` 输出 `.js` 运行时导入，而声明文件保留显式 `.ts` 后缀，使 NodeNext/Node16 的 TypeScript 消费方能够解析。
+
+## 2. 在根配置中注册
+
+| 文件 | 修改内容 |
+|---|---|
+| `tsconfig.base.json` | 在 `paths` 中添加 `"<npm-name>": ["./vendor/<dir>/src"]` |
+| `tsconfig.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }` |
+| `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }`（置于 `packages/*` 条目之前） |
+| `vendor/README.md` | 添加一行 manifest 表格行（dir、npm name、version、upstream repo、commit SHA）并记录所有本地修改 |
+| `scripts/publint-all.ts` | 仅当该 vendored 包本身从此仓库发布时才需要（vendored 依赖通常不发布——跳过） |
+
+以下由 glob 自动覆盖，无需手动编辑：根 `package.json` 的 workspaces（`vendor/*`）、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`。只有当构建形态偏离根默认值时（双 ESM/CJS 或多入口——参见 `vendor/schemastery` 和 `vendor/logger-console`），才需要单独的 `vendor/<dir>/tsdown.config.ts`；其入口应读取 `lib/types` 下输出的 JS。
+
+## 3. 注意 manifest 守卫
+
+`scripts/check-vendor-manifest.sh`（pre-commit 钩子）会在 `vendor/*/src` 下有暂存改动但 `vendor/README.md` 未一起暂存时失败。请将 manifest 更新与源码一起暂存，以通过提交检查。
+
+## 4. 验证
+
+```sh
+pnpm install        # registers the workspace
+pnpm run typecheck
+pnpm run build && pnpm run test && pnpm run constraints
+```
+
+源码 `paths` 映射由构建配置和根类型检查配置共享。重要的隔离边界是 project-reference 图：vendored 源码必须通过其自身的 `vendor/<dir>/tsconfig.json` 被引用，而非被拉入根目录的严格程序中。

docs/cookbook/adding-an-llm-adapter.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+adding-an-llm-adapter.md: 70306ccf119f523dd812a859eef1e8628383bb48
+adding-an-llm-adapter.zh.md: e6d151adfc793a829a876031d5d7280ba078c8e9

docs/cookbook/adding-an-llm-adapter.md

@@ -1,5 +1,7 @@
 # Cookbook: adding an LLM adapter
 
+English | [中文](adding-an-llm-adapter.zh.md)
+
 How to connect a new model provider. Reference implementations: `packages/llm/llm-deepseek` (hand-rolled HTTP/SSE) and `packages/llm/llm-pi-ai` (wrapping an LLM library). Read the `StreamChunk` doc in `packages/llm/llm/src/types.ts` first — it records the protocol conventions both adapters were verified against.
 
 ## The shape

docs/cookbook/adding-an-llm-adapter.zh.md

@@ -0,0 +1,45 @@
+# 实操手册：添加 LLM 适配器
+
+[English](adding-an-llm-adapter.md) | 中文
+
+如何接入一个新的模型提供方。参考实现：`packages/llm/llm-deepseek`（手写 HTTP/SSE）与 `packages/llm/llm-pi-ai`（封装 LLM 库）。请先阅读 `packages/llm/llm/src/types.ts` 中的 `StreamChunk` 文档——它记录了两个适配器都经过验证的协议约定。
+
+## 基本形态
+
+```ts ignore-check
+class MyAdapter extends LlmAdapter {
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> { … }
+}
+
+export const name = 'llm-myprovider'
+export const inject = ['llm']
+export const Config: z<Config> = z.object({ apiKey: z.string(), … })
+
+export function apply(ctx: Context, config: Config) {
+  ctx.llm.registerAdapter(['model-a', 'model-b'], new MyAdapter(…))
+}
+```
+
+注册基于副作用（HMR 安全）；每个模型名称对应一个适配器，重复注册会抛出异常。密钥采用 Cordis 原生方式管理：schemastery Config 带环境变量回退，通过 cordis.yml 的 `!!js process.env.MY_KEY` 注入。代码中禁止临时读取密钥文件。
+
+## 协议义务（两个实现共同验证的契约）
+
+- 在 `finish` **之前**发出 `usage`；`finish` 之后**不再发出任何内容**。稳健做法：缓冲 finish/usage 直到提供方的流结束标记，再统一 flush（可处理提供方在末尾发送仅含 usage 的分片的情况）。
+- 工具调用的 `arguments` 全程为原始 JSON 字符串；流式片段以 `argumentsDelta` 发送。如果你的提供方返回已解析的对象，请在 `block-end` 时重新 stringify。
+- 按首次出现的流顺序分配块 `index`；同一个块的每次 delta 复用该 index。
+- 错误有且仅有两条合法路径：从 `stream()` **抛出**（传输与协议故障——使用带稳定 code 的 `LlmError`），或以 `finish {kind: 'error' | 'aborted'}` 结束流（提供方带内故障）。消费方两者都处理；按故障类别选择路径并加以文档化。
+- 遵守 `options.signal`（将其传递给 fetch 或你的 SDK）。
+- 如果 `GenerateOptions` 中某个字段你的提供方无法支持（例如提供方不支持 stop sequences 时收到 `stop` 列表）：抛出 `LlmError(..., 'UNSUPPORTED')`，而非静默丢弃。
+
+提供方特有的请求旋钮（thinking 模式、effort 级别）放在**适配器**的 Config 中，而非 `GenerateOptions` 中——核心词汇保持提供方无关。
+
+## 经验证有效的结构
+
+将适配器拆分为可测试的阶段（llm-deepseek 的布局）：协议格式（wire format）类型（`types.ts`，豁免覆盖率）→ 请求序列化器 → SSE/传输解析器 → 分片转换状态机 → 一个将它们串联的薄适配器类。每个阶段配备独立的单元测试套件。
+
+## 测试
+
+- **单元测试：mock 提供方，而非 harness。** 用脚本化的 `node:http` 服务器模拟提供方的协议格式，覆盖正常路径、所有错误状态码、畸形载荷、连接提前关闭和中止——无需网络，且能满足 100% 逐文件覆盖率门禁。对基于 SDK 的适配器同样适用（将 SDK 的 baseURL 指向 mock 服务器）。
+- **恶意分帧测试。** 在任意字节位置（包括 UTF-8 字符中间）切割流载荷——真实网络环境正是如此。
+- **E2E：`tests/*.e2e.ts`**，通过 `pnpm run test:e2e` 运行，以 `describe.skipIf(!process.env.MY_KEY)` 守卫，确保无密钥的 CI 保持绿色。覆盖你映射的每个模型 × 每种提供方模式（thinking 开/关、effort 级别）、一次包含后续轮次（历史中带工具结果）的工具调用往返，以及仅做宽松断言（子串/结构匹配、有界的 maxTokens——真实模型是非确定性的）。
+- 在 `knip.json` 中注册 e2e 文件模式（per-workspace `entry` 覆盖），否则 knip 会将其标记为未使用。

docs/cookbook/extension-cookbook.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+extension-cookbook.md: 40ee22b352c884d7f295c87726c54ab8e166c844
+extension-cookbook.zh.md: 4e5bc68c973649574bcb2404bea00096eb9ca41f

docs/cookbook/extension-cookbook.md

@@ -1,14 +1,18 @@
 # Cookbook: extension plugin shapes
 
+English | [中文](extension-cookbook.zh.md)
+
+> FIXME: This important guide has not received sufficient human design review; complete that review before the first release.
+
 The three plugin shapes you write against the harness extension surface, as illustrative snippets (elided imports and helper stubs — not copy-paste-complete). For the full step-by-step guides see [adding a package](./adding-a-package.md), [adding a tool](./adding-a-tool.md), and [adding an LLM adapter](./adding-an-llm-adapter.md); for the seams these hook into see [docs/architecture.md](../architecture.md).
 
 ## A tool plugin
 
 A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `execute` args, result shaping, the `run_in_background` pattern) lives in [adding-a-tool.md](./adding-a-tool.md) — that guide is the source of truth for the tool shape. Raw JSON-Schema `ToolDefinition`s are also accepted by `ctx.tools.register()` directly (that is how MCP-sourced tools arrive); `defineTool` is the typed sugar for first-party tools.
 
-## A hook plugin (permission gate)
+## A hook plugin (permission-gate example)
 
-A hook returns a typed decision from the `tools/pre-execute` gate to allow or deny a call — the seam where sandbox, permission, and plan-mode plugins live. (A "native hook" is just this: an ordinary cordis plugin on the interception seams, returning typed decisions — no external protocol needed.)
+This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this seam. Hook plugins can intercept other seams and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception seam; it needs no external protocol.
 
 ```ts
 import type { Context } from 'cordis'

docs/cookbook/extension-cookbook.zh.md

@@ -0,0 +1,125 @@
+# 实操手册：扩展插件形态
+
+[English](extension-cookbook.md) | 中文
+
+> FIXME：这篇重要指南尚未经过充分的人工设计审查；请在首次发布前完成审查。
+
+针对 harness 扩展表面编写的三种插件形态，以示意性代码片段呈现（省略了 import 和辅助桩——不可直接复制运行）。完整的分步指南见[添加包（package）](./adding-a-package.md)、[添加工具](./adding-a-tool.md)和[添加 LLM（大语言模型）适配器](./adding-an-llm-adapter.md)；这些插件所挂接的 seam 见 [docs/architecture.md](../architecture.md)。
+
+## 工具插件
+
+工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](./adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON-Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
+
+## 钩子插件（以权限门禁为例）
+
+这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该 seam。钩子插件也可以拦截其他 seam，本身并不等同于权限门禁。「原生钩子」是在拦截 seam 上运行的普通 Cordis 插件，不需要外部协议。
+
+```ts
+import type { Context } from 'cordis'
+import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
+
+declare function isAllowed(exec: ToolExecution): Promise<boolean>
+
+export const name = 'permission-gate'
+
+export function apply(ctx: Context) {
+  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
+    if (!(await isAllowed(exec))) {
+      return { kind: 'deny', reason: 'Denied by policy.' }
+    }
+    return next()
+  })
+}
+```
+
+这个 waterfall（瀑布式事件）是可重排的策略层。当不变式需要单调的最终拒绝时使用 `ctx.tools.guard()`；当插件需要包裹实际分发生命周期时（超时/重试/指标；仅 `exec.signal` 可替换）使用 `tools/execute`；显式结果变换使用 `tools/post-execute`；对不可变最终结果的受限观察使用 `tools/result`。选择规则见[添加工具指南](./adding-a-tool.md#execution-policy-and-observation)。
+
+## UI 插件
+
+UI 插件从 `session/event` 事件流渲染（助手 token 流以 `assistant/chunk` 形式到达，加上轮次/步骤边界与工具活动），并通过 `agent.send()` / `agent.steer()` 将输入驱动回去。
+
+```ts
+import type { Context } from 'cordis'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+
+declare function render(text: string): void
+declare function onUserInput(handler: (text: string) => void): void
+
+export const name = 'my-ui'
+export const inject = ['agents']
+
+export function apply(ctx: Context) {
+  ctx.on('session/event', (_session, event) => {
+    if (event.type === 'assistant/chunk' && event.data.chunk.type === 'text-delta') {
+      render(event.data.chunk.text)
+    }
+  })
+  onUserInput(text => ctx.agents.get(AgentId('main'))?.send([{ type: 'text', text }]))
+}
+```
+
+## 客户端驱动插件（外部协议桥接）
+
+*客户端驱动*是面向协议格式（wire format）对端的 UI 插件。它拥有 stdio，因此必须禁用 stdout 日志；通过工厂创建或恢复 agent（智能体）；将 harness 事件映射为协议消息；将请求映射为 `send()` 或 `cancel()`。每个请求从持久的 `turn/end` 恰好结算一次（即使渲染失败），并通过 `AgentHandle.dispose()` 拆除 agent 以使 dispose（资源释放）达到静止状态。
+
+`packages/ui/acp` 是完整的工作示例：它将 agent 桥接到 ACP（Agent Client Protocol）（基于 stdio 的 JSON-RPC），使 Zed 及其他 ACP 编辑器能够驱动它。其 README 描述了完整的方法接口以及它在审批 seam 上注册的权限提示应答器。
+
+```ts
+import type { Context } from 'cordis'
+
+export const name = 'my-protocol-bridge'
+export const inject = ['agents', 'sessions', 'sessionPersistence']
+
+export function apply(ctx: Context) {
+  // Stream every logged assistant text/reasoning delta out to the client.
+  ctx.on('session/event', (_session, event) => {
+    if (event.type === 'assistant/chunk') {
+      const chunk = event.data.chunk
+      if (chunk.type === 'text-delta') {
+        // sendToClient({ kind: 'message_chunk', text: chunk.text })
+      }
+    }
+  })
+  // Inbound "prompt": create/resume an agent and feed it; settle on turn end.
+  // Teardown reaches quiescence via AgentHandle.dispose() (stop + await exit).
+}
+```
+
+## 可运行的组装示例
+
+三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app 包入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent)，ACP 演示加载 [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent)，两个 app 包通过 [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle 共享主干。
+
+## 功能→机制映射
+
+每个产品功能都映射到一个文档化扩展 seam 上的监听器——微内核声明由此可验证（[微内核 RFC](../rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）。没有任何一行修改循环本身。
+
+`system-prompt/assemble` 是一个专家协作式的整体装配变换：其返回的装配结果具有权威性，因此监听器作者有责任保留活跃的 Code Mode 和结构化输出协议的贡献。对于需要在展示、查找和执行之间保持对齐的工具过滤，优先使用 `ctx.tools.restrict()`。
+
+| 产品功能 | 插件机制 |
+|---|---|
+| 钩子系统（用户级 + 项目级） | `agent/session-start`、`agent/prompt-submit`、`agent/request`、`agent/step-result`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-continuation` 上的监听器——每个拦截 waterfall 返回一个类型化 Decision；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
+| `/goal` | 通过 `agent/turn-continuation` 强制继续 + `steer()` 提醒 |
+| `/loop` | 在 `turn/end` 会话事件上 `send()` 下一次迭代；或强制继续 |
+| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的 prompt/工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code`）和终端 `agent/turn-stop` 来强制输出 |
+| 排队消息 + steering（中途引导） | 核心 `Agent.send()` / `Agent.steer()` |
+| 上下文压缩（context compaction）（自动 + 手动） | `ctx.compact` seam + 串行 `agent/pre-step` seam 上的后端（`dsh-compact-basic`）；自动 = 每步之前的 token 压力检查；手动触发调用同一个 `ctx.compact` 例程（[压缩 RFC](../rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)——面向模型的 `/compact` 消费方工具已推迟） |
+| 系统提示词可配置性 | `ctx.systemPrompt.section()`，支持排序与作用域局部覆盖 |
+| AGENTS.md（根目录） | 一个读取该文件的 section provider |
+| AGENTS.md（子目录，按需触发）+ 文件变更通知 | 从 watcher / tool-result 监听器调用 `agent.inject()` |
+| 内置工具 | `ctx.tools.register()`；schema 自动流入装配——`dsh-tool-*` 系列（bash、fs、web、subagent、todo）是已交付的示例 |
+| ToolSearch / 渐进式披露 | 当可见集变化时替换一个作用域化的 `ctx.tools.restrict()` 注册；注册表保持展示、查找和执行三者对齐 |
+| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装器可替换 `exec.signal`、委托执行，并在同一词法生命周期内检视规范化结果 |
+| 最终工具结果指标 / 审计 / 捕获 | 用 `tools/result` 观察不可变的权威结果；仅当插件需要变换结果或附加上下文时才使用 `tools/post-execute` |
+| 单调终端轮次策略 | 从串行 `agent/turn-stop` 返回 `{ action: 'stop' }`，此时 continuation 和 steering 已折叠完毕 |
+| 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
+| 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
+| Plan mode | `tools/pre-execute`（拒绝写操作）+ 通过 `ctx.systemPrompt.section()` 或 `agent.inject()` 注入模式提示词段（model-visible ⟺ logged：`agent/request` 仅塑形调用配置） |
+| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
+| MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
+| Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
+| 记忆 | section provider + 工具 |
+| 定时任务（cron） | 插件注册面向模型的调度工具；定时器触发 → 空闲时 `send(…, {source: {kind: 'cron', …}})`／忙碌时 `inject()` 通知 |
+| UI（GUI；CLI 输出 JSONL） | 监听 `session/event`（助手分片、边界、工具活动）；输入 → `send()` |
+| 遥测 / 可回放 trace | `session/event` → JSONL；回放 = `sessions.create(id, { seed })` |
+| 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek`、`dsh-llm-pi-ai`） |
+| 插件热重载 | 每个注册都是一个 `ctx.effect` → vendor 的 HMR（热模块替换）直接生效 |

docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+responding-to-pr-review-on-a-stack.md: 3fb7eb943eeb8d703303be3f6a844870cc26fd47
+responding-to-pr-review-on-a-stack.zh.md: d96323b853c093265931904c20996df335f82926

docs/cookbook/responding-to-pr-review-on-a-stack.md

@@ -1,6 +1,8 @@
 # Responding to review across a stacked PR chain
 
-A wave of review comments lands across several PRs in a dependent stack (`A ← B ← C …`). This is the discipline for resolving it without corrupting the stack. The two invariants it rests on are standing orders in the root [AGENTS.md](../../AGENTS.md) § Conventions: merge commits only, and never rewrite a pushed branch.
+English | [中文](responding-to-pr-review-on-a-stack.zh.md)
+
+Review comments may target several PRs in a dependent stack (`A ← B ← C …`). This guide explains how to resolve them without corrupting the stack. The two invariants it rests on are standing orders in the root [AGENTS.md](../../AGENTS.md) § Conventions: merge commits only, and never rewrite a pushed branch.
 
 ## Ground rules
 
@@ -9,7 +11,7 @@ A wave of review comments lands across several PRs in a dependent stack (`A ←
 3. **A fix lands on the PR that INTRODUCED the issue, then flows down.** When a comment on PR `B` points at code `B` introduced, fix it on `B` and merge `B` into `C` — even if `C` also carries the file. Originating the fix downstream leaves `B` shipping the unfixed code and hides the fix from `B`'s reviewer.
 4. **Each review fix is a separate commit, never an amend.** The "fix review findings" commit documents what the review caught. Amending is fine only for your own not-yet-pushed, not-yet-reviewed work.
 
-## Working the wave
+## Resolve comments through the stack
 
 1. Triage every comment on the merits before acting: verify the claim against the code — a reviewer flagging the right symptom can still mis-diagnose the cause.
 2. Map each accepted finding to its originating PR, fix it there, then merge down the chain in order.

docs/cookbook/responding-to-pr-review-on-a-stack.zh.md

@@ -0,0 +1,26 @@
+# 在堆叠 PR 链中回应评审意见
+
+[English](responding-to-pr-review-on-a-stack.md) | 中文
+
+评审意见可能同时针对一条依赖堆叠（`A ← B ← C …`）中的多个 PR（Pull Request）。本指南说明如何在不破坏堆叠的前提下解决这些意见。它依赖的两个不变式是根 [AGENTS.md](../../AGENTS.md) § Conventions 中的常设指令：只用 merge commit，以及永远不改写已推送的分支。
+
+## 基本规则
+
+1. **每个 PR 分支一个 worktree。** 每个 PR 的修复在该 PR 自己的 worktree 中进行；并行修复绝不共享同一个 checkout。
+2. **通过将父分支向下合并来更新子分支**（在子分支中执行 `git merge <parent-branch>`，产生一个新的 merge commit）。绝不对已推送的分支做 rebase/amend/force-push：改写会使分支与父 PR 及 GitHub 记录的内容产生分歧，破坏堆叠合并图，并抹去评审修复历史。
+3. **修复落在引入问题的那个 PR 上，然后向下流动。** 当 PR `B` 上的评论指向 `B` 引入的代码时，在 `B` 上修复，再将 `B` 合并到 `C`——即使 `C` 也包含该文件。把修复发起在下游会导致 `B` 带着未修复的代码交付，并对 `B` 的评审者隐藏修复。
+4. **每个评审修复是一个独立 commit，绝不 amend。** "修复评审发现"的 commit 记录了评审捕获的内容。只有你自己尚未推送、尚未评审的工作才可以 amend。
+
+## 沿堆叠解决评审意见
+
+1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
+2. 将每个被接受的发现映射到其发起 PR，在那里修复，然后按顺序沿链向下合并。
+3. 委派的修复需要信任但验证：子 agent（智能体）的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。子 agent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
+4. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及承载修复的 commit。
+5. 合并堆叠之前，检查依赖方：删除一个 PR 的 base 分支会自动关闭依赖它的 PR。用 `gh pr list --state open --base <branch> --json number --jq length` 检查每个分支（非零 = 有打开的依赖方），当子 PR 仍以该分支为 base 时，合并时不带 `--delete-branch`。完整的落地流程见 [dsh-merging-stacked-prs](../../.agents/skills/dsh-merging-stacked-prs/SKILL.md) skill（技能）。
+
+## 验证
+
+- 每个已修复的 PR 显示一个新 commit（PR 时间线中没有 force-push 图标）。
+- 每个子 PR 相对其父 PR 的 diff 仍然只包含自身的变更。
+- 门禁在堆叠中的每个 PR 上都通过，而不仅仅是顶部。

docs/i18n/terminology.md

@@ -40,7 +40,7 @@
 | Cordis | Cordis | | | |
 | dispose | dispose | dispose（资源释放） | | |
 | doc-sync | doc-sync | doc-sync（文档同步门禁） | | |
-| fiber | fiber | fiber（插件运行时） | | |
+| fiber | fiber | | | |
 | fixture | fixture | fixture（测试前置数据） | | |
 | fork | fork | | | |
 | Function Calling | Function Calling | Function Calling（函数调用） | | |
@@ -51,7 +51,6 @@
 | loader | loader | | | |
 | manifest | manifest | manifest（元数据清单） | | |
 | monorepo | monorepo | | | |
-| package | package | | | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） |
 | schema | schema | | | |
 | schema DSL | schema DSL | | | |
 | seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` |
@@ -125,6 +124,7 @@
 | module | 模块 | | | |
 | orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
 | orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
+| package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
 | pairing | 配对 | | | |
 | peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |
 | permission | 权限 | | | |

docs/i18n/translation-prompt.md

@@ -79,6 +79,11 @@ You are a senior technical translator specializing in LLM and agent development
 
 #### When translating into English
 - Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.
+- Convert enumeration commas (、) to English commas; convert 「」 quotes to English double quotes.
+- Render the terminology table's English column the same way the Chinese column binds the other direction: listed terms use exactly the table's English form; first-occurrence glosses do not carry over (English prose never glosses an English term with Chinese).
+- Chinese topic-comment sentences and dropped subjects become explicit English subjects; prefer concise declaratives over nominalizations.
+- Do not transliterate Chinese engineering idioms literally: render the underlying concept (误报 → false positive, 执行红线 → enforcement frontier), consulting the terminology table first.
+- Keep the register of institutional developer documentation: contractions are acceptable, marketing language and hedging (very, quite, simply) are not.
 
 ## Terminology
 

docs/module-graph.md

@@ -107,6 +107,9 @@ flowchart TD
     pkg_code_runtime["code-runtime"]
     pkg_code_runtime_worker["code-runtime-worker"]
   end
+  subgraph group_context["packages/context"]
+    pkg_time_context["time-context"]
+  end
   subgraph group_guard["packages/guard"]
     pkg_repeat_tool_guard["repeat-tool-guard"]
   end
@@ -183,6 +186,8 @@ flowchart TD
   pkg_user_approval --> pkg_system_prompt
   pkg_user_interaction --> pkg_agent
   pkg_user_interaction --> pkg_llm
+  pkg_time_context --> pkg_agent
+  pkg_time_context --> pkg_system_prompt
   pkg_workflow --> pkg_agent
   pkg_workflow --> pkg_brand
   pkg_workflow --> pkg_llm
@@ -375,6 +380,7 @@ flowchart TD
 | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
+| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
 | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox) |

docs/rfc/INDEX.md

@@ -77,6 +77,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 |
 | [Exact session query service](implemented/feature/2026-07-10-session-query-service.md) | 2026-07-10 |
 | [Configure subagent persona, tool visibility, and depth](implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md) | 2026-07-12 |
+| [Optional time-context plugin](implemented/feature/2026-07-14-time-context-plugin.md) | 2026-07-14 |
 
 ### Simplification
 

docs/rfc/implemented/feature/2026-07-14-time-context-plugin.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-14-time-context-plugin.md: 13e0eff4b9d286ee562d7a0a2c0a3a659126ba3b
+2026-07-14-time-context-plugin.zh.md: 5ee50a4d49eb9a7e00a09f70b436e15d72612b1f

docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md

@@ -0,0 +1,57 @@
+# RFC: Optional time-context plugin
+
+Status: implemented
+
+English | [中文](2026-07-14-time-context-plugin.zh.md)
+
+## Problem
+
+An agent request has no live clock unless a deployment puts one in prompt text or gives the model a query tool. Static text becomes stale, while a tool call adds overhead to ordinary reasoning about dates, deadlines, or idle time. Without elapsed time, the model cannot distinguish an immediate follow-up from one sent hours after the preceding message.
+
+Prompt assembly can derive both facts per step from durable session timestamps, and request-header logging can record the exact rendered value. Accumulating stale readings in conversation history or waking idle agents would violate the existing request lifecycle.
+
+## Decision
+
+`@deepseek-ai/dsh-time-context` is an opt-in function plugin at `packages/context/time-context/`. The `context/` product group holds bounded request-context enrichments that define neither a tool nor a service. `dsh-agent-core` and shipped examples do not load the package; deployments mount it explicitly when its token and disclosure costs are acceptable.
+
+The plugin registers the global `context:time` system-prompt section at order 10, after the deployment persona and before tool guidance. For an active turn it emits an ISO-shaped timestamp with numeric UTC offset and IANA zone, plus a compact whole-second duration since the last model-visible message before the turn opened. Bare and idle assemblies receive an empty section.
+
+### Previous-message baseline
+
+At a turn's first assembly, the provider scans before `turn/start` for the latest `user/message`, `assistant/message`, `tool/result`, `context/message`, or `steering/message`. It excludes the current prompt so the duration expresses the inter-turn gap instead of approximately zero. Every refresh in that turn keeps the same baseline, and the first turn reports `unavailable (no earlier message in this session)`.
+
+The baseline is the session event's append time, not an unlogged client timestamp. Resume and fork behavior are therefore deterministic from the durable log, and the model-visible value remains reconstructable without a new event. A backward wall-clock adjustment clamps the duration to zero.
+
+### Refresh policy
+
+`refreshIntervalMs` defaults to 60,000 and must be a non-negative safe integer. Every turn's first request refreshes. Later assemblies in that turn reuse the block until its age reaches the interval; `0` refreshes every step. No timer creates work during model calls, tools, or idle time because refresh is request-bound.
+
+When `timeZone` is omitted, `Intl.DateTimeFormat` resolves the Node process's system zone once at plugin load. Node honors `TZ`; without that override, the host or container supplies the zone. An explicit value must be an IANA identifier and is validated at load. The captured zone remains stable until plugin reload, and the ISO-shaped local timestamp includes its current numeric offset so daylight-saving changes stay explicit. This is the deployment process's zone, not a remote user's zone.
+
+### Logging and token shape
+
+The loop records the temporal block through `request/header` and `request/header-delta` before transmission, satisfying the [reconstructable-requests contract](../architecture/2026-07-05-reconstructable-requests.md). Each request carries one current block; earlier readings do not remain in conversation history. The plugin owns the fact and contributes it through the prompt registry, following the [prompt-variables RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) without a loop special case.
+
+## Testing
+
+Unit tests pin formatting, baselines, refresh policy, validation, per-agent state, disposal, and load-time system-zone capture. A real agent-loop test pins the transmitted prompt and `request/header-delta`. A keyless subprocess e2e boots a test-only `cordis.yml` through the real Loader and stdio app, omits `timeZone` under a controlled `TZ`, drives two turns, and verifies the persisted request headers externally. Default snapshot compositions omit the plugin, so their transcript fixtures contain no temporal block.
+
+## Alternatives considered
+
+- **Append a `context/message` on every turn or refresh** — rejected because readings and token cost would accumulate in history. Replacing a prior surface node would preserve its old position, while replacing the tail would hide intervening conversation.
+- **Use `agent/session-prefix`** — rejected because the session-stable prefix cannot represent a per-turn or per-step clock.
+- **Mutate requests in `agent/request`** — rejected because that seam shapes call config after the message boundary; inserted model content would bypass prompt-pressure accounting and request-header logging.
+- **Register separate `{{current_time}}` and `{{elapsed}}` variables** — rejected because independent providers can sample different instants and require shared caching. One section records the pair atomically without a deployment-authored template.
+- **Refresh from a background timer** — rejected because a new value has no consumer outside request assembly. Timer-driven `agent.inject()` would create turns and wake idle sessions merely to report time passing.
+- **Keep UTC as the omitted default** — rejected because an explicitly enabled clock should follow its deployment environment unless the operator chooses UTC. `timeZone: UTC` remains available when a deployment requires it.
+- **Add a time-zone detection library** — rejected because Node's `Intl` runtime already exposes the process's IANA zone. Another dependency cannot infer a remote user's zone either.
+- **Mount the plugin in `dsh-agent-core`** — rejected because time zone, disclosure, token budget, and freshness are deployment policy. Opt-in keeps default context stable.
+- **Place the package in `core/`** — rejected because `core/` owns the product API spine, while this plugin is an optional leaf with no service key.
+
+## Consequences
+
+- Opted-in models receive a zoned clock and inter-turn duration without a tool call. The system-prompt cost is fixed per request instead of growing with the session.
+- An omitted `timeZone` follows the process's `TZ`, host, or container zone as observed at plugin load. Operators must configure an explicit zone when the deployment environment does not represent the intended user.
+- A refresh changes the request header and can add a `request/header-delta`. `refreshIntervalMs` trades freshness against durable deltas; `0` records a new value on every step whose whole-second rendering changes.
+- No request exists solely to refresh time. A long-running tool leaves the prior reading until the next step assembles.
+- Duration reflects harness processing time at durable append boundaries, not client-network latency before logging. Preserving a client-origin timestamp requires a separate durable input contract.

docs/rfc/implemented/feature/2026-07-14-time-context-plugin.zh.md

@@ -0,0 +1,57 @@
+# RFC：可选时间上下文插件
+
+Status: implemented
+
+[English](2026-07-14-time-context-plugin.md) | 中文
+
+## 问题
+
+如果部署方既未在提示词中提供时钟，也未给模型提供查询工具，agent（智能体）请求就无法获得实时准确的时间。静态文本会变得陈旧，而对于日期、截止时间或闲置时长等常规推理，调用工具会增加开销。缺少已经过去的时长时，模型无法区分紧接着发送的消息与上一条消息几小时后才发送的消息。
+
+提示词组装流程可以在每个步骤中根据持久会话时间戳派生这两项信息，请求头日志则可以记录实际渲染的确切值。在会话历史中累积陈旧读数或唤醒空闲 agent 都会违反现有请求生命周期。
+
+## 决策
+
+`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 产品分组用于容纳既不定义工具、也不定义服务的有界请求上下文增强。`dsh-agent-core` 和仓库提供的示例都不会加载该 package；只有当 token 与信息披露成本可接受时，部署方才显式挂载它。
+
+该插件注册顺序值为 10 的全局系统提示词区段 `context:time`，位置在部署方角色设定之后、工具指导之前。对于活跃轮次，它会输出带数字 UTC 偏移和 IANA 时区、形似 ISO 的时间戳，以及从轮次开始前最后一条模型可见消息起算的紧凑整秒时长。未绑定 agent 或 agent 处于空闲状态时，该区段为空。
+
+### 上一条消息基线
+
+在轮次首次组装时，提供方会在 `turn/start` 之前查找最近的 `user/message`、`assistant/message`、`tool/result`、`context/message` 或 `steering/message`。它会排除当前提示词，使时长表达轮次间隔，而不是接近零。同一轮次中的每次刷新都保留这条基线；首个轮次报告 `unavailable (no earlier message in this session)`。
+
+基线采用会话事件的追加时间，而不是日志中不存在的客户端时间戳。因此，恢复和 fork 行为可以从持久日志中确定性重现，模型可见值也无需新增事件即可重建。系统挂钟向后调整时，插件会将时长钳制为零。
+
+### 刷新策略
+
+`refreshIntervalMs` 默认值为 60,000，并且必须是非负安全整数。每个轮次的首次请求都会刷新。同一轮次中的后续组装会复用该区块，直至其存在时间达到该间隔；设为 `0` 时每个步骤都刷新。刷新仅由请求驱动，因此在模型调用、工具运行或空闲期间，计时器不会创建任务。
+
+省略 `timeZone` 时，`Intl.DateTimeFormat` 会在插件加载时解析一次 Node 进程的系统时区。Node 会遵循 `TZ`；没有该覆盖值时，时区由主机或容器提供。显式值必须是 IANA 标识符，并在加载时接受校验。捕获的时区在插件重新加载前保持稳定，形似 ISO 的本地时间戳包含其当前数字偏移，使夏令时变化保持显式可见。该默认值代表部署进程的时区，而不是远程用户的时区。
+
+### 日志与 token 形态
+
+agent loop（智能体循环）会在发送前通过 `request/header` 和 `request/header-delta` 记录时间区块，从而满足[可重建请求契约](../architecture/2026-07-05-reconstructable-requests.md)。每个请求只携带一个当前区块；先前的读数不会保留在会话历史中。该插件拥有时间信息，并按照[提示词变量 RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)通过提示词注册表贡献该信息，无需为循环添加特殊分支。
+
+## 测试
+
+单元测试固定格式化、基线、刷新策略、校验、逐 agent 状态、资源释放行为，以及系统时区在加载时的捕获行为。使用真实 agent loop 的测试固定实际发送的提示词和 `request/header-delta`。无密钥子进程端到端测试通过真实 Loader 和 stdio 应用启动测试专用 `cordis.yml`，在受控 `TZ` 下省略 `timeZone`，驱动两个轮次，并从外部校验持久请求头。默认快照组合不包含该插件，因此其中的 transcript（文本记录）fixture（测试前置数据）不包含时间区块。
+
+## 考虑过的替代方案
+
+- **每个轮次或每次刷新都追加一条 `context/message`**——不予采纳，因为读数和 token 成本会在历史中累积。替换先前的表层节点会保留其旧位置，而替换尾部节点会隐藏中间的会话内容。
+- **使用 `agent/session-prefix`**——不予采纳，因为会话期间保持稳定的前缀无法表示逐轮次或逐步骤变化的时钟。
+- **在 `agent/request` 中修改请求**——不予采纳，因为该边界在消息边界之后塑造调用配置；插入模型可见内容会绕过提示词压力核算和请求头日志。
+- **注册独立的 `{{current_time}}` 和 `{{elapsed}}` 变量**——不予采纳，因为独立提供方可能在不同时间点采样，并且需要共享缓存。单个区段会以原子方式记录两项信息，也不需要部署方编写时间模板。
+- **通过后台计时器刷新**——不予采纳，因为请求组装之外没有消费新值的对象。由计时器驱动 `agent.inject()` 会创建轮次，并且只为报告时间流逝就唤醒空闲会话。
+- **省略配置时仍默认使用 UTC**——不予采纳，因为显式启用的时钟应跟随部署环境，除非运维方选择 UTC。需要 UTC 的部署仍可配置 `timeZone: UTC`。
+- **引入时区探测库**——不予采纳，因为 Node 的 `Intl` 运行时已经能够提供进程的 IANA 时区，而且额外依赖同样无法推断远程用户的时区。
+- **在 `dsh-agent-core` 中挂载插件**——不予采纳，因为时区、信息披露、token 预算和新鲜度都属于部署策略。选择加入能保持默认上下文稳定。
+- **将 package 放入 `core/`**——不予采纳，因为 `core/` 负责产品 API 主干，而该插件是没有服务键的可选叶节点。
+
+## 后果
+
+- 选择加入的模型无需调用工具，即可获得分区时钟和轮次间隔时长。每个请求的系统提示词成本固定，不会随会话增长。
+- 省略 `timeZone` 时，插件采用加载时观察到的进程 `TZ`、主机或容器时区。当部署环境不能代表目标用户时，运维方必须显式配置时区。
+- 刷新会改变请求头，并可能新增 `request/header-delta`。`refreshIntervalMs` 用新鲜度换取持久增量记录的数量；设为 `0` 时，每个整秒渲染结果发生变化的步骤都会记录新值。
+- 系统不会仅为刷新时间而创建请求。长时间运行的工具会保留先前读数，直至下一步骤开始组装。
+- 时长反映持久追加边界处的 harness 处理时间，不包含消息进入日志之前的客户端网络延迟。若要保留客户端来源时间戳，需要单独的持久输入契约。

docs/testing.md

@@ -23,7 +23,7 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword
 
 ## Test the real entry path
 
-- A plugin shipped via `cordis.yml` needs at least one test through the REAL Loader path: hand-built `ctx.plugin({...})` mounts bypass `unwrapExports` and cannot catch a broken export shape ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md); export-shape rules in [packages/AGENTS.md](../packages/AGENTS.md)).
+- Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external/nondeterministic boundaries, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults.
 - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green under a broken export shape — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert.
 - "Real entry path" means the published artifact: the package `bin` points at built `lib/bin.js` under plain `node`, which tsx masks (settle races, module resolution, a swallowed load failure exiting 0). The same applies to any non-index runtime entry the built package resolves at run time (the worker-thread runtime's sibling `lib/worker.cjs`). Keep the built-artifact smokes green (`packages/ui/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero.
 - An e2e that spawns an example from a temp cwd sets `TSX_TSCONFIG_PATH` to the repo-root tsconfig, or it silently falls back to stale built `lib/` ([examples/AGENTS.md](../examples/AGENTS.md)).

knip.json

@@ -23,6 +23,10 @@
       "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
       "project": ["src/**/*.ts", "tests/**/*.ts"]
     },
+    "packages/context/time-context": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
     "packages/sandbox/sandbox-local": {
       "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
       "project": ["src/**/*.ts", "tests/**/*.ts"]

packages/AGENTS.md

@@ -4,7 +4,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 
 - **Plugin export shape:** service packages default-export their service class; function plugins named-export `name` / `inject` / `Config` / `apply` and have no default export. Mixing the forms makes the Loader discard the function plugin's namespace ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
 - **Optional services use `ctx.get(name)`.** Reserve `ctx.<name>` for declared injections; the property proxy is topology-sensitive, while strict `ctx.get` reads the global service store ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
-- **A plugin shipped via `cordis.yml` needs at least one test through the REAL Loader/export path** — hand-built `ctx.plugin({...})` mounts bypass `unwrapExports` and cannot catch a broken export shape. Full testing policy (tiers, with-key generosity, real-entry-path guards): [docs/testing.md](../docs/testing.md).
+- **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Typed same-process service and plugin calls are contracts, not serialization boundaries.** Prefer readonly borrowed values; materialize or defensively validate only at parser/config, queued, model/tool JSON, durable/file, worker, process, or wire boundaries.
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
 

packages/README.md

@@ -1,6 +1,6 @@
 # Packages
 
-Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis plugin: a default `Service` subclass or functional plugin declaring ctx keys/events through declaration merging and contributing through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md) § Conventions.
+Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass or function plugin; contributions use `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring rules: [package](AGENTS.md) and [root](../AGENTS.md#conventions).
 
 ## Hierarchy
 
@@ -16,6 +16,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
+| [`context/`](context/README.md) | Opt-in request-context enrichment | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |

packages/context/README.md

@@ -0,0 +1,7 @@
+# context/ — optional request context
+
+Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-core` bundle excludes them.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `time-context/` | Current time and elapsed-time system-prompt context | (none) |

packages/context/time-context/README.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-time-context
+
+Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-core` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).
+
+## Config
+
+```yaml
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+  config:
+    timeZone: Asia/Shanghai   # optional IANA override; omit for the process zone
+    refreshIntervalMs: 60000  # default; 0 refreshes on every step
+```
+
+When `timeZone` is omitted, the plugin resolves the Node process's system zone once at plugin load. Node honors `TZ`; without that override, the host or container supplies the zone. An explicit `timeZone` must be an IANA identifier and is validated at plugin load. `refreshIntervalMs` must be a non-negative safe integer. Every turn's first request refreshes; later steps reuse the reading until its age reaches the interval. `0` refreshes every step. Refresh occurs only during request assembly and creates no timer work.
+
+## Message baseline
+
+The duration starts at the latest user, assistant, tool-result, context, or steering message before the current `turn/start`. Every refresh in the turn retains that baseline, so the current prompt does not collapse the interval to approximately zero. The first turn reports that no earlier message exists. The durable clock source is session-event append time, not client send time.
+
+The loop records the dynamic section in `request/header` / `request/header-delta`. Requests therefore remain reconstructable, carry one timing block, and retain no earlier readings in conversation history.
+
+## Model Experience
+
+### Temporal system prompt
+
+**What the model sees**: Every request in an active turn includes the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; `<duration-or-unavailable>` is compact whole-second units or the first-turn fallback.
+
+**Token effect**: Fixed two-line cost per request. A refresh replaces the request-header section; prior readings do not accumulate.
+
+#### Temporal context section
+
+```markdown
+Current time: <timestamp>
+Time since previous message: <duration-or-unavailable>.
+```
+
+## Known Limitations and Deferred Work
+
+- **Request-bound refresh only** — no clock update is emitted while the agent is waiting inside a model call or tool; the next assembled step refreshes once the configured interval has elapsed.
+- **Whole-second display** — timestamps and durations omit sub-second precision even when `refreshIntervalMs` is below 1,000.
+- **Session-event baseline** — elapsed time starts from the durable append timestamp, not a client transport's original send timestamp.
+- **Process-local default zone** — omission uses the Node process's `TZ`, host, or container zone captured at plugin load, not a remote user's zone; configure an explicit IANA zone when those differ.

packages/context/time-context/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-time-context",
+  "description": "Opt-in system-prompt context with the current time and elapsed time since the previous message",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Opt-in request-time clock context. Active turns receive the current zoned
+ * time and elapsed time since the preceding model-visible message. The loop
+ * logs each rendered value as request-header state rather than conversation
+ * history.
+ *
+ * @module @deepseek-ai/dsh-time-context
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { AssembleContext } from '@deepseek-ai/dsh-system-prompt'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'time-context'
+
+/** The system-prompt registry that owns the dynamic request section. */
+export const inject = ['systemPrompt']
+
+/** Request-time clock formatting and refresh policy. Invalid values fail plugin load. */
+export interface Config {
+  /** IANA time zone used for the rendered timestamp. Omit to resolve the Node process's system zone at plugin load. */
+  timeZone?: string
+  /** Maximum age of a reading within one turn, in milliseconds (default 60,000; `0` refreshes every step). */
+  refreshIntervalMs?: number
+}
+
+/** Schemastery validation and defaults for {@link Config}. */
+export const Config: z<Config> = z.object({
+  timeZone: z.string(),
+  refreshIntervalMs: z.number().default(60_000),
+})
+
+interface OpenTurn {
+  turn: number
+  startSeq: number
+}
+
+/** Cached text and the fixed inter-turn baseline used by one agent's open turn. */
+interface RenderState {
+  turn: number
+  renderedAt: number
+  previousMessageTime: number | undefined
+  text: string
+}
+
+type TimestampPart = 'day' | 'hour' | 'minute' | 'month' | 'second' | 'timeZoneName' | 'year'
+
+function openTurn(agent: Agent): OpenTurn | undefined {
+  for (const event of [...agent.session.events].reverse()) {
+    switch (event.type) {
+      case 'turn/end':
+        return undefined
+      case 'turn/start':
+        return { turn: event.data.turn, startSeq: event.seq }
+      default:
+        // Merge-extensible session events: only turn boundaries matter here.
+        break
+    }
+  }
+  return undefined
+}
+
+/** Find the latest model-visible timestamp strictly before one turn boundary. */
+function previousMessageTime(agent: Agent, turnStartSeq: number): number | undefined {
+  for (const event of [...agent.session.events].reverse()) {
+    if (event.seq >= turnStartSeq) continue
+    switch (event.type) {
+      case 'user/message':
+      case 'assistant/message':
+      case 'tool/result':
+      case 'context/message':
+      case 'steering/message':
+        return event.time
+      default:
+        // Merge-extensible session events: non-surface records are not messages.
+        break
+    }
+  }
+  return undefined
+}
+
+/** Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone. */
+function formatTimestamp(now: number, formatter: Intl.DateTimeFormat, timeZone: string): string {
+  const parts = Object.fromEntries(
+    formatter.formatToParts(now).map(part => [part.type, part.value]),
+  ) as Record<TimestampPart, string>
+  const offset = parts.timeZoneName.replace(/^GMT$/, 'GMT+00:00').slice(3)
+  return `${parts['year']}-${parts['month']}-${parts['day']}T${parts['hour']}:${parts['minute']}:${parts['second']}${offset}[${timeZone}]`
+}
+
+/** Format a non-negative elapsed millisecond count as compact whole-second units. */
+function formatDuration(elapsedMs: number): string {
+  let seconds = Math.floor(Math.max(0, elapsedMs) / 1000)
+  const days = Math.floor(seconds / 86_400)
+  seconds %= 86_400
+  const hours = Math.floor(seconds / 3600)
+  seconds %= 3600
+  const minutes = Math.floor(seconds / 60)
+  seconds %= 60
+  const parts: string[] = []
+  if (days > 0) parts.push(`${days}d`)
+  if (hours > 0) parts.push(`${hours}h`)
+  if (minutes > 0) parts.push(`${minutes}m`)
+  parts.push(`${seconds}s`)
+  return parts.join(' ')
+}
+
+function renderText(
+  now: number,
+  previous: number | undefined,
+  formatter: Intl.DateTimeFormat,
+  timeZone: string,
+): string {
+  const elapsed = previous === undefined
+    ? 'unavailable (no earlier message in this session)'
+    : formatDuration(now - previous)
+  return `Current time: ${formatTimestamp(now, formatter, timeZone)}\nTime since previous message: ${elapsed}.`
+}
+
+/**
+ * Register the request-time clock section for the lifetime of `ctx`.
+ * @param ctx - plugin context; the section registration is disposed with it.
+ * @param config - validated time zone and intra-turn refresh interval.
+ * @throws when the time zone or refresh interval is invalid.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const timeZone = config.timeZone
+  const refreshIntervalMs = config.refreshIntervalMs as number
+  if (!Number.isSafeInteger(refreshIntervalMs) || refreshIntervalMs < 0) {
+    throw new Error(`time-context: refreshIntervalMs must be a non-negative safe integer, got ${refreshIntervalMs}`)
+  }
+
+  let formatter: Intl.DateTimeFormat
+  try {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      ...(timeZone === undefined ? {} : { timeZone }),
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+      timeZoneName: 'longOffset',
+    })
+  } catch (error: unknown) {
+    const message = timeZone === undefined
+      ? 'time-context: failed to resolve the system time zone'
+      : `time-context: invalid IANA timeZone ${JSON.stringify(timeZone)}`
+    throw new Error(message, { cause: error })
+  }
+  const resolvedTimeZone = formatter.resolvedOptions().timeZone
+  const states = new WeakMap<Agent, RenderState>()
+
+  ctx.systemPrompt.section({
+    name: 'context:time',
+    order: 10,
+    text(context: AssembleContext): string {
+      const agent = context.agent
+      if (agent === undefined) return ''
+      const currentTurn = openTurn(agent)
+      if (currentTurn === undefined) return ''
+
+      const now = Date.now()
+      const prior = states.get(agent)
+      if (prior !== undefined
+        && prior.turn === currentTurn.turn
+        && now >= prior.renderedAt
+        && now - prior.renderedAt < refreshIntervalMs) {
+        return prior.text
+      }
+
+      const previous = prior?.turn === currentTurn.turn
+        ? prior.previousMessageTime
+        : previousMessageTime(agent, currentTurn.startSeq)
+      const text = renderText(now, previous, formatter, resolvedTimeZone)
+      states.set(agent, { turn: currentTurn.turn, renderedAt: now, previousMessageTime: previous, text })
+      return text
+    },
+  })
+}

packages/context/time-context/tests/fixtures/cordis.yml

@@ -0,0 +1,17 @@
+# Test-only composition: keep time-context opt-in while exercising its real Loader/app path.
+- id: mock-llm
+  name: '../../../../../examples/echo-agent/src/mock-llm.ts'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: mock-echo
+    persona: 'Test the time-context plugin.'
+    welcome: 'time-context e2e ready.'
+    persistenceRoot: './.sessions'

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

@@ -0,0 +1,115 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { foldRequestHeader, type SessionEvent } from '@deepseek-ai/dsh-session'
+
+const binScript = fileURLToPath(new URL('../../../ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url))
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+const PROCESS_TIMEOUT_MS = 30_000
+const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
+const FIRST_REPLY = 'You said: "first". Try "echo <something>" to see a tool call.'
+
+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 })
+  const paths = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return jsonlFiles(path)
+    return entry.isFile() && entry.name.endsWith('.jsonl') ? [path] : []
+  }))
+  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 proc = spawn(
+      process.execPath,
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
+      {
+        cwd,
+        env: {
+          ...process.env,
+          TZ: 'Asia/Shanghai',
+          TSX_TSCONFIG_PATH: repoTsconfig,
+          DSH_HOME: join(cwd, '.dsh'),
+          DSH_AGENTS_HOME: join(cwd, '.agents'),
+        },
+        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}\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 both first-turn and elapsed-time request context', 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('You said: "second".')
+
+    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 firstHeader = events.find(event => event.type === 'request/header')
+    if (firstHeader?.type !== 'request/header') throw new Error('missing initial request/header event')
+    expect(firstHeader.data.header.system).toMatch(
+      /Current time: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+08:00\[Asia\/Shanghai\]/,
+    )
+    expect(firstHeader.data.header.system).toContain(
+      'Time since previous message: unavailable (no earlier message in this session).',
+    )
+
+    const finalSystem = foldRequestHeader(events)?.system
+    expect(finalSystem).toContain('[Asia/Shanghai]')
+    expect(finalSystem).toMatch(
+      /Time since previous message: (?:\d+d )?(?:\d+h )?(?:\d+m )?\d+s\./,
+    )
+  }, TEST_TIMEOUT_MS)
+})

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

@@ -0,0 +1,371 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as timeContext from '@deepseek-ai/dsh-time-context'
+import type { Config } from '@deepseek-ai/dsh-time-context'
+
+const BASE = Date.parse('2026-07-14T00:00:00.000Z')
+const ORIGINAL_TIME_ZONE = process.env['TZ']
+
+beforeEach(() => {
+  process.env['TZ'] = 'UTC'
+  vi.useFakeTimers()
+  vi.setSystemTime(BASE)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+  if (ORIGINAL_TIME_ZONE === undefined) delete process.env['TZ']
+  else process.env['TZ'] = ORIGINAL_TIME_ZONE
+})
+
+async function mount(config: Config = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  const fiber = await ctx.plugin(timeContext, config)
+  return { ctx, fiber }
+}
+
+function sessionAgent(session: Session, id = 'agent'): Agent {
+  return { id: AgentId(id), session } as unknown as Agent
+}
+
+async function sectionText(ctx: Context, agent?: Agent): Promise<string | undefined> {
+  const assembly = await ctx.systemPrompt.assemble(agent === undefined ? {} : { agent })
+  return assembly.sections.find(section => section.name === 'context:time')?.text
+}
+
+function openMessageTurn(session: Session, turn: number): void {
+  session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('user/message', {
+    content: [{ type: 'text', text: `turn ${turn}` }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+function textResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+function toolCallResponse(): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'tool-call' },
+    {
+      type: 'block-end',
+      index: 0,
+      block: { type: 'tool-call', id: CallId('tick-1'), name: 'tick', arguments: '{}' },
+    },
+    { type: 'finish', reason: { kind: 'tool-calls' } },
+  ]
+}
+
+class ScriptedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private readonly script: StreamChunk[][]) {
+    super()
+  }
+
+  override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const chunks = this.script.shift()
+    if (chunks === undefined) throw new Error('ScriptedAdapter: script exhausted')
+    for (const chunk of chunks) yield chunk
+  }
+}
+
+async function loopHarness(adapter: ScriptedAdapter, config: Config = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(timeContext, config)
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+describe('temporal section rendering', () => {
+  it('renders the first turn in UTC with the explicit no-previous-message fallback', async () => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId('first'))
+    openMessageTurn(session, 1)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toBe(
+      'Current time: 2026-07-14T00:00:00+00:00[UTC]\n'
+      + 'Time since previous message: unavailable (no earlier message in this session).',
+    )
+  })
+
+  it('renders a non-UTC numeric offset and all compact duration units', async () => {
+    const { ctx } = await mount({ timeZone: 'Asia/Shanghai' })
+    const session = new Session(SessionId('offset'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'previous' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 90_061_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toBe(
+      'Current time: 2026-07-15T09:01:01+08:00[Asia/Shanghai]\n'
+      + 'Time since previous message: 1d 1h 1m 1s.',
+    )
+  })
+
+  it('clamps a backward wall-clock adjustment to a zero duration', async () => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId('backward-duration'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'future by adjusted clock' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE - 5_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Time since previous message: 0s.')
+  })
+
+  const previousMessageCases = [
+    ['user/message', (session: Session): void => {
+      session.append('user/message', { content: [{ type: 'text', text: 'u' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    }],
+    ['assistant/message', (session: Session): void => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] }, { surfaceOp: 'append' })
+    }],
+    ['tool/result', (session: Session): void => {
+      session.append('tool/result', {
+        turn: 1,
+        step: 1,
+        callId: CallId('previous'),
+        content: [{ type: 'text', text: 'r' }],
+        isError: false,
+      }, { surfaceOp: 'append' })
+    }],
+    ['context/message', (session: Session): void => {
+      session.append('context/message', {
+        content: [{ type: 'text', text: 'c' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }, { surfaceOp: 'append' })
+    }],
+    ['steering/message', (session: Session): void => {
+      session.append('steering/message', {
+        turn: 1,
+        content: [{ type: 'text', text: 's' }],
+        source: { kind: 'user' },
+      }, { surfaceOp: 'append' })
+    }],
+  ] as const
+
+  it.each(previousMessageCases)('uses a prior %s as the duration baseline', async (_name, appendPrevious) => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId(`previous-${_name}`))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    appendPrevious(session)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 5_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Time since previous message: 5s.')
+  })
+
+  it('contributes empty text without an active agent turn', async () => {
+    const { ctx } = await mount()
+    expect(await sectionText(ctx)).toBe('')
+
+    const empty = sessionAgent(new Session(SessionId('empty')))
+    expect(await sectionText(ctx, empty)).toBe('')
+
+    const closedSession = new Session(SessionId('closed'))
+    openMessageTurn(closedSession, 1)
+    closedSession.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(await sectionText(ctx, sessionAgent(closedSession))).toBe('')
+  })
+})
+
+describe('refresh policy', () => {
+  it('reuses within the interval, refreshes at expiry, and refreshes after a backward clock jump', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const session = new Session(SessionId('interval'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 30_000)
+    expect(await sectionText(ctx, agent)).toBe(first)
+    vi.setSystemTime(BASE + 60_000)
+    const expired = await sectionText(ctx, agent)
+    expect(expired).toContain('2026-07-14T00:01:00+00:00[UTC]')
+    vi.setSystemTime(BASE + 59_000)
+    expect(await sectionText(ctx, agent)).toContain('2026-07-14T00:00:59+00:00[UTC]')
+  })
+
+  it('refreshes every assembly when refreshIntervalMs is zero', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 0 })
+    const session = new Session(SessionId('every-step'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 1_000)
+    expect(await sectionText(ctx, agent)).not.toBe(first)
+  })
+
+  it('always refreshes for a new turn and keeps the preceding message baseline', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const session = new Session(SessionId('turn-refresh'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 1_000)
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'done' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 2_000)
+    openMessageTurn(session, 2)
+
+    const second = await sectionText(ctx, agent)
+    expect(second).not.toBe(first)
+    expect(second).toContain('Time since previous message: 1s.')
+  })
+
+  it('keeps refresh caches independent per agent', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const sessionA = new Session(SessionId('agent-a'))
+    const sessionB = new Session(SessionId('agent-b'))
+    const agentA = sessionAgent(sessionA, 'a')
+    const agentB = sessionAgent(sessionB, 'b')
+    openMessageTurn(sessionA, 1)
+    openMessageTurn(sessionB, 1)
+    const aFirst = await sectionText(ctx, agentA)
+    vi.setSystemTime(BASE + 30_000)
+    const bFirst = await sectionText(ctx, agentB)
+    vi.setSystemTime(BASE + 40_000)
+
+    expect(await sectionText(ctx, agentA)).toBe(aFirst)
+    expect(bFirst).toContain('2026-07-14T00:00:30+00:00[UTC]')
+  })
+})
+
+describe('configuration and lifecycle', () => {
+  it('defaults to the process system zone and retains the zone resolved at plugin load', async () => {
+    process.env['TZ'] = 'Asia/Shanghai'
+    const { ctx } = await mount()
+    process.env['TZ'] = 'America/New_York'
+    const session = new Session(SessionId('system-zone'))
+    openMessageTurn(session, 1)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain(
+      'Current time: 2026-07-14T08:00:00+08:00[Asia/Shanghai]',
+    )
+  })
+
+  it('fails loud for negative, fractional, unsafe, and invalid-zone config', async () => {
+    for (const refreshIntervalMs of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      await expect(ctx.plugin(timeContext, { refreshIntervalMs })).rejects.toThrow(/non-negative safe integer/)
+    }
+
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await expect(ctx.plugin(timeContext, { timeZone: 'Not/A_Real_Zone' })).rejects.toThrow(/invalid IANA timeZone/)
+  })
+
+  it('fails loud when the process system zone cannot be resolved', async () => {
+    vi.spyOn(Intl, 'DateTimeFormat').mockImplementationOnce(() => {
+      throw new RangeError('system zone unavailable')
+    })
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    await expect(ctx.plugin(timeContext, {})).rejects.toThrow(/failed to resolve the system time zone/)
+  })
+
+  it('removes its section when the plugin fiber disposes', async () => {
+    const { ctx, fiber } = await mount()
+    const session = new Session(SessionId('dispose'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    expect(await sectionText(ctx, agent)).toContain('Current time:')
+
+    await fiber.dispose()
+    expect(await sectionText(ctx, agent)).toBeUndefined()
+  })
+})
+
+describe('real agent-loop request logging', () => {
+  it('refreshes a long turn in the system prompt and records the header delta without context history', async () => {
+    const adapter = new ScriptedAdapter([toolCallResponse(), textResponse('done'), textResponse('next turn')])
+    const ctx = await loopHarness(adapter, { refreshIntervalMs: 60_000 })
+    ctx.tools.register(defineTool({
+      name: 'tick',
+      description: 'advance fake time',
+      parameters: {},
+      async execute() {
+        vi.setSystemTime(BASE + 61_000)
+        return [{ type: 'text' as const, text: 'advanced' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('loop'), { model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'start' }])
+    await agent.whenIdle()
+    expect(adapter.requests).toHaveLength(2)
+    expect(adapter.requests[0]!.system).toContain('2026-07-14T00:00:00+00:00[UTC]')
+    expect(adapter.requests[1]!.system).toContain('2026-07-14T00:01:01+00:00[UTC]')
+    expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(agent.session.events.filter(event => event.type === 'request/header-delta')).toHaveLength(1)
+    expect(foldRequestHeader(agent.session.events)?.system).toBe(adapter.requests[1]!.system)
+
+    vi.setSystemTime(BASE + 361_000)
+    agent.send([{ type: 'text', text: 'again' }])
+    await agent.whenIdle()
+    expect(adapter.requests[2]!.system).toContain('Time since previous message: 5m 0s.')
+    await ctx.fiber.dispose()
+  })
+})
+
+describe('real Loader export path', () => {
+  it('keeps the namespace metadata and boots through unwrapExports', async () => {
+    expect('default' in timeContext).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(timeContext) as Record<string, unknown>
+    expect(unwrapped).toBe(timeContext)
+    expect(unwrapped.name).toBe('time-context')
+    expect(unwrapped.inject).toEqual(['systemPrompt'])
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const plugin = loader.unwrapExports(timeContext) as Parameters<Context['plugin']>[0]
+    await ctx.plugin(plugin)
+    const session = new Session(SessionId('loader'))
+    openMessageTurn(session, 1)
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Current time:')
+  })
+})

packages/context/time-context/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../../core/agent" }
+  ]
+}

pnpm-lock.yaml

@@ -240,6 +240,34 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/context/time-context:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
   packages/cordis/tool-cordis:
     dependencies:
       schemastery:

scripts/translation-pairing.manifest.json

@@ -2,6 +2,12 @@
   "requiredSince": "2026-07-14",
   "required": [
     "README.md",
+    "docs/cookbook/adding-a-package.md",
+    "docs/cookbook/adding-a-tool.md",
+    "docs/cookbook/adding-a-vendored-package.md",
+    "docs/cookbook/adding-an-llm-adapter.md",
+    "docs/cookbook/extension-cookbook.md",
+    "docs/cookbook/responding-to-pr-review-on-a-stack.md",
     "docs/development.md",
     "docs/i18n/README.md",
     "docs/i18n/translation-rules.md",

tsconfig.base.json

@@ -47,6 +47,7 @@
         "./packages/fs/*/src",
         "./packages/skill/*/src",
         "./packages/compact/*/src",
+        "./packages/context/*/src",
         "./packages/guard/*/src",
         "./packages/subagent/*/src",
         "./packages/workflow/*/src",

tsconfig.build.json

@@ -21,6 +21,7 @@
     { "path": "./packages/session-query/session-query" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
+    { "path": "./packages/context/time-context" },
     { "path": "./packages/ui/user-interaction" },
     { "path": "./packages/ui/user-approval" },
     { "path": "./packages/ui/permission" },

tsconfig.json

@@ -32,6 +32,7 @@
     { "path": "./packages/session-query/session-query" },
     { "path": "./packages/core/system-prompt" },
     { "path": "./packages/core/agent" },
+    { "path": "./packages/context/time-context" },
     { "path": "./packages/ui/user-interaction" },
     { "path": "./packages/ui/user-approval" },
     { "path": "./packages/ui/permission" },