@deepseek-ai/dsh-time-context 0.1.1-rc.2 → 0.1.2-alpha.3

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/context/time-context/README.md
-README.md: 0bdb0d463362427d6a7050c2d7d6d55f96779f9c
-README.zh.md: 8f95b133afed5cd872f80d8f0f5ae69e53062325
+README.md: 52690900b0ac65743345c226128217e2c9ec156b
+README.zh.md: 64299a57a37ec32647e7a2ab0062e02b71516a6e

package/README.md

@@ -1,41 +1,101 @@
+---
+description: "Opt-in per-step clock context with the current time, browser zone, and elapsed time, for users and maintainers enabling or tuning the plugin."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-time-context
 
 English | [中文](README.zh.md)
 
-Opt-in durable context with the current zoned time, the browser zone attached to the open request, and elapsed time sampled during model-request preparation. Default compositions leave it disabled; the Schedule Web overlay mounts it so the model can interpret otherwise-unqualified dates and times in the user's browser zone. Decision record: [the durable time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md).
+## Summary
+
+`dsh-time-context` gives the model a clock: on eligible steps it appends a durable, source-attributed reading with the current time, the browser zone attached to the open request, and the elapsed time since the preceding model-visible message. It helps the model interpret otherwise-unqualified dates and times in the user's browser zone, and tells it to ask when zone provenance is mixed or missing. The plugin is opt-in: default compositions leave it disabled, and the Schedule Web overlay mounts it. A positive `refreshIntervalMs` reduces how often readings accumulate; omission or `0` injects at every eligible step.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this plugin when the model should interpret unqualified dates and times in the user's zone, and when a request-local browser zone is available or a configured fallback is acceptable. Each injection is one additional user-role message in the durable history; schedule it with `refreshIntervalMs` when per-step readings are more than the conversation needs.
 
-## Config
+### What the agent gets
+
+Each injected reading has three lines: an ISO-shaped timestamp with numeric offset and IANA zone, the browser-zone policy for the request, and the elapsed duration in compact whole-second units. Step 1 measures from the latest preceding model-visible message; later steps measure from the preceding time-context event in the same turn. A missing baseline reports `unavailable`, and backward wall-clock movement clamps elapsed time to zero.
+
+### Configuration
+
+The minimal mount needs no configuration. A positive `refreshIntervalMs` suppresses injections that fall within that many milliseconds of the latest one; omission or `0` injects at every eligible entering pre-step whose signal is not already aborted.
 
 ```yaml
-- id: time-context
-  name: '@deepseek-ai/dsh-time-context'
+- name: '@deepseek-ai/dsh-time-context'
   config:
-    timeZone: Asia/Shanghai  # optional fallback when the request has no unique browser zone
-    refreshIntervalMs: 60000 # optional; omit or set to 0 for every eligible attempt
+    timeZone: Asia/Shanghai
 ```
 
-When the open turn contains one Host-validated browser zone, that request-local zone formats the timestamp. With missing or mixed browser provenance, `timeZone` supplies the display fallback; omitting it resolves the Node process zone once at plugin load. Node honors `TZ`, and every explicit fallback is validated through `Intl.DateTimeFormat`.
+| Field | Default | Meaning |
+|---|---|---|
+| `timeZone` | process zone | Fallback display zone when the open turn has no unique browser zone |
+| `refreshIntervalMs` | `0` (every eligible step) | Minimum milliseconds between durable injections in one session |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-time-context) is the exhaustive source for every accepted field and its JSDoc.
+
+### Choosing the zone
+
+When the open turn contains exactly one Host-validated browser zone, the timestamp is formatted in that request-local zone. With missing or mixed browser provenance, the configured `timeZone` formats the display; omitting it resolves the Node process zone once at plugin load, and every explicit fallback is validated through `Intl.DateTimeFormat`. The resolved instruction tells the model to interpret unqualified dates and times in the chosen zone, and to ask the user to clarify when provenance is mixed or unavailable.
 
-`refreshIntervalMs` must be a non-negative safe integer. Omission or `0` adds context to every eligible entering pre-step whose signal is not already aborted. A positive value adds it only when the Session has no earlier time-context injection, wall time moved backward, or at least that many milliseconds elapsed since the latest injection.
+-----
 
-## Request-zone ownership
+<a id="understand-the-implementation"></a>
+## Understand the implementation
 
-The browser samples `Intl.DateTimeFormat().resolvedOptions().timeZone` for each prompt. The Host validates and canonicalizes that value before binding it to the exact durable `user-rpc` message source. Time-context examines only those sources in the open turn: one unique zone resolves the request, multiple zones are `mixed`, and none are `unavailable`. It does not read or mutate Session headers, connection state, or Schedule records.
+<details>
+<summary>Implementation internals — click to expand</summary>
 
-The resolved instruction tells the model to interpret otherwise-unqualified dates and times in that browser zone. Mixed or unavailable provenance tells the model to ask the user to clarify. This is natural-language context, not an input default at another package boundary: a tool that accepts local calendar fields still owns its explicit zone requirement.
+This section explains the design of the plugin; the observable behavior is covered in [Use this package](#use-this-package).
 
-## Timing semantics
+### Design concept
 
-The plugin prepends an `agent/pre-step` listener and delegates first. When an injection is due and the downstream decision enters, it appends one sourced `UserMessage` to the returned batch. AgentLoop records the final batch after `step/start` and before request derivation. Rejection, listener failure, or an already-aborted signal records nothing.
+The plugin prepends an `agent/pre-step` listener that delegates first and appends one sourced `UserMessage` when an injection is due and the downstream decision enters the step. Each reading uses the exact snapshot source `{ kind: 'plugin', plugin: 'time-context', form: 'snapshot', sections: [{ name: 'time-context', text }] }`, and the invariant companion validates that shape, re-derives the current-turn browser policy from the original `user-rpc` messages, and checks the timestamp zone and elapsed baseline.
 
-Each reading uses the exact snapshot source `{ kind: 'plugin', plugin: 'time-context', form: 'snapshot', sections: [{ name: 'time-context', text: <same text> }] }`. The `./invariant` companion validates that shape, re-derives the current-turn browser policy from the original `user-rpc` messages, and checks the timestamp zone and elapsed baseline.
+### Source map
 
-Positive-interval scheduling scans raw durable Session events for the latest plugin-attributed message, including a reading shadowed by compaction. It therefore survives resume without a process-local cache. A positive interval can intentionally let a later request reuse existing history without a fresh reading; the Schedule Web overlay omits the interval.
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: pre-step listener, due scheduling, reading composition |
+| [`src/request-zone.ts`](src/request-zone.ts) | Browser-zone policy derivation from open-turn `user-rpc` sources |
+| [`src/timestamp.ts`](src/timestamp.ts) | `Intl.DateTimeFormat` creation and timestamp formatting |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion for the snapshot contract |
 
-Step 1 measures from the latest preceding durable user, assistant, or tool-result message. The prompt proposed for that step has not been appended yet. Later steps measure from the preceding time-context event in the same turn. Missing baselines report `unavailable`, and backward wall-clock movement clamps elapsed time to zero.
+### Main flow
 
-A reading records an entered step, not a completed or transmitted request. A later preparation failure can leave it in history. The message remains in derived conversation history until compaction shadows it; `request/header` contains no time-context state, and request reconstruction uses the complete durable surface prefix after each `step/start`.
+When an injection is due, the plugin samples the wall clock, derives the browser-zone policy from the open turn's `user-rpc` messages, resolves the display zone (request-local or fallback), and renders the three-line reading. Positive-interval scheduling scans raw durable session events for the latest plugin-attributed message — including one shadowed by compaction — so the schedule survives resume without a process-local cache. A reading records an entered step, not a completed or transmitted request; a later preparation failure can leave it in history.
 
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the design decision to the composition that mounts the plugin and the exhaustive configuration.
+
+- [Durable per-step time-context decision record](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md) — design rationale for the durable reading.
+- [Schedule user guide](../../../docs/user/guide/schedule.md) — the official configuration path for mounting this plugin.
+- [Context group map](../README.md) — sibling request-context packages.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-time-context) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
 ### Preparation-time temporal context
@@ -70,8 +130,23 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when clock context is a poor fit. They are current package constraints.
+
 - **Prompt provenance only** — browser-zone context guides natural-language interpretation but does not silently supply another tool's required zone field.
 - **Mixed turns ask** — if one open turn contains prompts from different browser zones, the model is told to clarify rather than guess which one owns an unqualified time.
 - **Fallback is not user authority** — the configured or process zone formats the clock when browser provenance is missing or mixed, but the model-facing policy still says to clarify.
 - **Whole-second display** — timestamps and durations omit sub-second precision even though durable event times retain milliseconds.
 - **History cost between compactions** — omission or `0` retains one reading for every eligible attempt; a positive interval reduces but does not eliminate this cost and may leave a later request without fresh browser-zone guidance.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,41 +1,101 @@
+---
+description: "可选的按步骤时钟上下文，包含当前时间、浏览器时区与经过时长，供启用或调优本插件的用户与维护者阅读。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-time-context
 
 [English](README.md) | 中文
 
-可选的持久上下文，包含当前带时区时间、附加到当前开放请求的浏览器时区，以及在模型请求准备期间采样的经过时长。默认组合不启用它；Schedule Web overlay 会挂载它，使模型可以按用户的浏览器时区解释未明确限定时区的日期和时间。决策记录：[持久 time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md)。
+## 概述
+
+`dsh-time-context` 给模型一只时钟：在符合条件的步骤上，它追加一条持久、带来源的读数，包含当前时间、附加到当前开放请求的浏览器时区，以及自前一条模型可见消息以来的经过时长。它帮助模型按用户的浏览器时区解释未明确限定时区的日期与时间；时区来源混杂或缺失时，它告诉模型去询问。本插件需主动启用：默认组合不启用它，Schedule Web overlay 会挂载它。正的 `refreshIntervalMs` 会减少读数累积的频率；省略或设为 `0` 时，每个符合条件的步骤都会注入。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当模型需要按用户所在时区解释未限定的日期与时间，且请求本地浏览器时区可用或已配置的回退值可接受时，挂载此插件。每次注入都是持久历史中额外的一条 user 角色消息；当按步骤读数超出对话需要时，用 `refreshIntervalMs` 调度。
 
-## 配置
+### 模型能得到什么
+
+每条注入读数包含三行：带数字偏移与 IANA 时区、形如 ISO 的时间戳，该请求的浏览器时区策略，以及以紧凑整秒单位表示的经过时长。第 1 步从最新一条先前模型可见消息起测量；后续步骤从同一轮次中前一个 time-context 事件起测量。缺少基线时报告 `unavailable`，挂钟时间倒退时把经过时长钳制为零。
+
+### 配置
+
+最小挂载无需任何配置。正的 `refreshIntervalMs` 会抑制距最近一次注入不足该毫秒数的注入；省略或设为 `0` 时，每个信号尚未中止且将进入步骤的合格 pre-step 都会注入。
 
 ```yaml
-- id: time-context
-  name: '@deepseek-ai/dsh-time-context'
+- name: '@deepseek-ai/dsh-time-context'
   config:
-    timeZone: Asia/Shanghai  # optional fallback when the request has no unique browser zone
-    refreshIntervalMs: 60000 # optional; omit or set to 0 for every eligible attempt
+    timeZone: Asia/Shanghai
 ```
 
-当当前开放轮次只包含一个经 Host 校验的浏览器时区时，使用该请求本地时区格式化时间戳。浏览器来源信息缺失或混杂时，`timeZone` 提供显示回退；省略它则会在插件加载时解析一次 Node 进程时区。Node 遵循 `TZ`，每个显式回退值都经 `Intl.DateTimeFormat` 校验。
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `timeZone` | 进程时区 | 当前开放轮次没有唯一浏览器时区时的显示回退时区 |
+| `refreshIntervalMs` | `0`（每个合格步骤） | 同一会话中两次持久注入之间的最小毫秒数 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-time-context)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 选择时区
+
+当当前开放轮次只包含一个经 Host 校验的浏览器时区时，时间戳按该请求本地时区格式化。浏览器来源信息缺失或混杂时，配置的 `timeZone` 格式化显示；省略它则在插件加载时解析一次 Node 进程时区，每个显式回退值都经 `Intl.DateTimeFormat` 校验。解析后的指令告诉模型按所选时区解释未限定的日期与时间；来源信息混杂或不可用时，则要求用户澄清。
 
-`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每个信号尚未中止且将进入步骤的合格 pre-step 添加上下文。正数值只会在会话没有更早的 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
+-----
 
-## 请求时区归属
+<a id="understand-the-implementation"></a>
+## 理解实现
 
-浏览器会为每条提示词采样 `Intl.DateTimeFormat().resolvedOptions().timeZone`。Host 校验并规范化该值，再将其绑定到确切的持久 `user-rpc` 消息来源。Time-context 只检查当前开放轮次中的这些来源：唯一一个时区可解析请求，多个时区记为 `mixed`，没有时区则记为 `unavailable`。它不会读取或修改会话标头、连接状态或 Schedule 记录。
+<details>
+<summary>实现细节——点击展开</summary>
 
-解析后的指令告诉模型，把未明确限定时区的日期和时间解释为该浏览器时区。来源信息为 mixed 或 unavailable 时，模型会收到要求用户澄清的指令。这是自然语言上下文，并非另一个包边界上的输入默认值：接受本地日历字段的工具仍自行负责其显式时区要求。
+本节解释插件的设计；可观察行为见[使用本包](#use-this-package)。
 
-## 时序语义
+### 设计理念
 
-该插件会前置一个 `agent/pre-step` 监听器，并先行委托下游。需要注入且下游决策进入步骤时，它会向返回批次追加一条带来源的 `UserMessage`。AgentLoop 在 `step/start` 之后、请求派生之前记录最终批次。决策被拒绝、监听器失败或信号已经中止时，不会记录任何内容。
+插件前置注册一个 `agent/pre-step` 监听器，先委托下游，需要注入且下游决策进入步骤时追加一条带来源的 `UserMessage`。每个读数都使用确切的快照来源 `{ kind: 'plugin', plugin: 'time-context', form: 'snapshot', sections: [{ name: 'time-context', text }] }`，不变式伴生插件会校验该形状，根据原始 `user-rpc` 消息重新派生当前轮次的浏览器策略，并检查时间戳时区与经过时长基线。
 
-每个读数都使用确切的快照来源 `{ kind: 'plugin', plugin: 'time-context', form: 'snapshot', sections: [{ name: 'time-context', text: <same text> }] }`。`./invariant` 配套模块会校验该形状，根据原始 `user-rpc` 消息重新派生当前轮次的浏览器策略，并检查时间戳时区与经过时长基线。
+### 源码地图
 
-正数间隔调度会扫描原始持久会话事件，查找最新一条归因于插件的消息，其中包括已被压缩（compaction）遮蔽的读数。因此，它无需进程本地缓存也能在恢复后继续生效。正数间隔可以有意让后续请求复用现有历史，而不添加新读数；Schedule Web overlay 会省略该间隔。
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：pre-step 监听器、到期调度、读数组合 |
+| [`src/request-zone.ts`](src/request-zone.ts) | 从开放轮次 `user-rpc` 来源派生浏览器时区策略 |
+| [`src/timestamp.ts`](src/timestamp.ts) | `Intl.DateTimeFormat` 创建与时间戳格式化 |
+| [`src/invariant.ts`](src/invariant.ts) | 快照约定的不变式伴生插件 |
 
-第 1 步从最新一条在其之前持久化的用户、助手或工具结果消息起测量。为该步骤拟议的提示词尚未追加。后续步骤从同一轮次中前一个 time-context 事件起测量。缺少基线时报告 `unavailable`，挂钟时间倒退时将经过时长限制为零。
+### 主要流程
 
-读数记录的是已进入的步骤，不是已完成或已传输的请求。后续准备失败时，该读数可能留在历史中。消息会保留在派生会话历史中，直到压缩将其遮蔽；`request/header` 不含 time-context 状态，请求重建会使用每个 `step/start` 之后的完整持久表层前缀。
+需要注入时，插件采样挂钟时间，从开放轮次的 `user-rpc` 消息派生浏览器时区策略，解析显示时区（请求本地或回退），并渲染三行读数。正数间隔调度会扫描原始持久会话事件，查找最新一条归因于插件的消息——包括被压缩（compaction）遮蔽的读数——因此调度无需进程本地缓存也能在恢复后存续。读数记录的是已进入的步骤，不是已完成或已传输的请求；后续准备失败时，该读数可能留在历史中。
 
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+包级约定不够用时阅读以下页面。它们从设计决策进入挂载本插件的组合与穷尽式配置。
+
+- [持久按步骤 time-context 决策记录](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md)——持久读数的设计理由。
+- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md)——挂载本插件的官方配置路径。
+- [context 组地图](../README.zh.md)——相邻的请求上下文包。
+- [生成的配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-time-context)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
 ### 准备期时间上下文
@@ -68,10 +128,25 @@ Elapsed since the preceding step context: <duration-or-unavailable>.
 
 仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明时钟上下文何时不合适。它们是当前包约束。
 
 - **仅限提示词来源信息**：浏览器时区上下文用于指导自然语言解释，但不会悄然填入另一工具所要求的时区字段。
 - **混合轮次会询问**：如果同一个开放轮次包含来自不同浏览器时区的提示词，模型会收到要求澄清的指令，而不会猜测哪个时区拥有未限定的时间。
 - **回退值不代表用户权威**：浏览器来源信息缺失或混杂时，配置或进程时区用于格式化时钟，但面向模型的策略仍要求澄清。
 - **整秒显示**：时间戳与持续时间省略亚秒精度，尽管持久事件时间保留毫秒。
 - **压缩之间的历史成本**：省略或设为 `0` 时，每次合格尝试都会保留一条读数；正数间隔可以降低但无法消除该成本，也可能使后续请求缺少新鲜的浏览器时区指导。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -1,183 +1,7 @@
-import { createRequire } from "node:module";
 import z from "@deepseek-ai/schemastery";
-import "@deepseek-ai/cordis";
-//#region ../../llm/llm/src/brand.ts
-/**
-* Brand a message identifier.
-* @param id - the opaque message identifier.
-* @returns the same string, branded; no validation is performed.
-*/
-function MessageId(id) {
-	return id;
-}
-//#endregion
-//#region ../../llm/llm/src/call-config.ts
-/**
-* Deep-freeze a value in place with an iterative traversal, guarding cycles,
-* so later mutation throws without imposing a JavaScript call-stack depth cap.
-* {@link AbortSignal} objects are deliberately skipped because they are the
-* request's live cancellation channel and freezing them breaks abort.
-* @param value - the value to freeze in place.
-* @returns the same value, frozen.
-*/
-function deepFreeze(value) {
-	const seen = /* @__PURE__ */ new WeakSet();
-	const pending = [{
-		kind: "visit",
-		node: value
-	}];
-	while (pending.length > 0) {
-		const task = pending.pop();
-		/* v8 ignore next -- the loop condition guarantees one pending task. */
-		if (task === void 0) continue;
-		if (task.kind === "property") {
-			pending.push({
-				kind: "visit",
-				node: task.source[task.key]
-			});
-			continue;
-		}
-		const node = task.node;
-		if (node === null || typeof node !== "object") continue;
-		if (node instanceof AbortSignal) continue;
-		if (seen.has(node)) continue;
-		seen.add(node);
-		Object.freeze(node);
-		const keys = Object.keys(node);
-		for (let index = keys.length - 1; index >= 0; index--) {
-			const key = keys[index];
-			/* v8 ignore next -- the loop is bounded by the captured key count. */
-			if (key === void 0) continue;
-			pending.push({
-				kind: "property",
-				source: node,
-				key
-			});
-		}
-	}
-	return value;
-}
-//#endregion
-//#region ../../llm/llm/src/message.ts
-/** Message value types, identity, and immutable construction helpers. */
-/**
-* Detach and deep-freeze a message whose identity already exists.
-* @param message - complete message, including its stable identity.
-* @returns an immutable snapshot that preserves the identity.
-*/
-function freezeMessage(message) {
-	return deepFreeze(structuredClone(message));
-}
-/**
-* Create one identified message and freeze it before publication.
-* @param input - complete role, content, and source for a new message.
-* @returns an immutable message with a fresh stable identity.
-*/
-function createMessage(input) {
-	return freezeMessage({
-		...input,
-		id: MessageId(crypto.randomUUID())
-	});
-}
-/**
-* Create one identified user-role message and freeze it before publication.
-* @param input - complete content and source for a new user message.
-* @returns an immutable user message with a fresh stable identity.
-*/
-function createUserMessage(input) {
-	return createMessage({
-		...input,
-		role: "user"
-	});
-}
-//#endregion
-//#region ../../util/timeout/src/index.ts
-/** Largest delay Node schedules without clamping it to one millisecond. */
-const MAX_TIMER_DELAY_MS = 2147483647;
-//#endregion
-//#region ../../llm/llm/src/error.ts
-/**
-* Canonical provider-neutral code for a response that completed normally but
-* carried no content blocks at all. Providers occasionally emit a degenerate
-* completion (a terminal stop with zero output); adapters classify it as this
-* failure instead of yielding an empty assistant message, because an empty
-* message silently ends the turn with nothing for the user or the loop to act
-* on. The attempt produced nothing durable, so retry policy treats it as safe
-* to repeat.
-*/
-const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
-new RegExp(String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]` + String.raw`(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, "i");
-new RegExp(String.raw`\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?` + String.raw`too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?` + String.raw`(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, "i");
-new RegExp(String.raw`\b(?:input|prompt|request|messages?)\b.{0,40}` + String.raw`\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}` + String.raw`\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, "i");
-//#endregion
-//#region ../../llm/llm/src/retry-policy.ts
-/**
-* Provider-owned request-retry policy configuration and resolution.
-*
-* Adapters expose one resolved policy per registered provider route; the
-* optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
-*
-* @module @deepseek-ai/dsh-llm/retry-policy
-*/
-const DEFAULT_MAX_RETRIES = 5;
-const DEFAULT_INITIAL_DELAY_MS = 500;
-const DEFAULT_MAX_DELAY_MS = 1e4;
-const DEFAULT_JITTER_RATIO = .1;
-const DEFAULT_RETRYABLE_CODES = Object.freeze([
-	EMPTY_RESPONSE_CODE,
-	"RATE_LIMIT",
-	"SERVER",
-	"TIMEOUT",
-	"TRANSPORT"
-]);
-const backoffSchema = z.object({
-	initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
-	maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
-	jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO)
-});
-const normalPolicySchema = z.object({
-	mode: z.const("normal").required(),
-	maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
-	retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
-	backoff: backoffSchema
-});
-const alwaysPolicySchema = z.object({
-	mode: z.const("always").required(),
-	backoff: backoffSchema
-});
-z.union([normalPolicySchema, alwaysPolicySchema]);
-//#endregion
-//#region ../../llm/llm/src/attribution.ts
-/**
-* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
-* adapters from drifting. See
-* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
-*
-* App-attribution vocabulary for provider requests.
-* @module @deepseek-ai/dsh-llm/attribution
-*/
-const { version } = createRequire(import.meta.url)("../package.json");
-//#endregion
-//#region ../../llm/llm/src/never.ts
-/**
-* Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
-* new variant fails compilation at every required handler. Do not use it for declaration-merged
-* unions such as session events or content blocks: handle known variants and explicitly fall
-* through because plugins may add valid unknown cases.
-* @module @deepseek-ai/dsh-llm/never
-*/
-/**
-* Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
-* a value that escaped its type throws with diagnostics at runtime.
-* @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
-* @param context - optional label (e.g. the switch site) prefixed into the throw message.
-* @returns never — it always throws, with the offending value JSON-rendered in the message.
-*/
-function assertNever(value, context) {
-	const rendered = JSON.stringify(value) ?? String(value);
-	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
-}
-//#endregion
+import { z as z$1 } from "zod";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { assertNever } from "@deepseek-ai/dsh-util-values";
 //#region lib/types/request-zone.js
 /** Browser-zone derivation and model-facing policy text for one open request turn. */
 const IANA_TIME_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/;
@@ -275,8 +99,16 @@ function formatTimestamp(now, formatter, timeZone) {
 */
 /** Cordis plugin name used by loader diagnostics. */
 const name = "time-context";
+const timeContextStateSchema = z$1.object({
+	/** Time of the latest model-visible event (user/assistant message, tool result), or null. */
+	lastMessageTime: z$1.number().nullable(),
+	/** Time of this plugin's latest durable injection, or null. */
+	lastInjectionTime: z$1.number().nullable(),
+	/** Latest injection time in the open turn, or null before that turn receives one. */
+	lastTurnInjectionTime: z$1.number().nullable()
+});
 /** The agent registry that owns pre-step processing. */
-const inject = ["agents"];
+const inject = ["agents", "sessionProjections"];
 /** Schemastery validation for {@link Config}. */
 const Config = z.object({
 	timeZone: z.string(),
@@ -298,26 +130,6 @@ function formatDuration(elapsedMs) {
 	parts.push(`${seconds}s`);
 	return parts.join(" ");
 }
-/** Find the latest model-visible event, excluding this plugin's pending append. */
-function precedingMessageTime(agent) {
-	for (const event of [...agent.session.events].reverse()) switch (event.type) {
-		case "user/message":
-		case "assistant/message":
-		case "tool/result": return event.time;
-		default: break;
-	}
-}
-/** Find the preceding time-context event within the open turn. */
-function precedingStepContextTime(agent, turn) {
-	for (const event of [...agent.session.events].reverse()) {
-		if (event.type === "turn/start" && event.data.turn === turn) return void 0;
-		if (event.type === "user/message" && event.data.source.kind === "plugin" && event.data.source.plugin === "time-context") return event.time;
-	}
-}
-/** Find this plugin's latest durable injection, including a shadowed surface event. */
-function latestInjectionTime(agent) {
-	for (const event of [...agent.session.events].reverse()) if (event.type === "user/message" && event.data.source.kind === "plugin" && event.data.source.plugin === "time-context") return event.time;
-}
 /** Collect already-entered and proposed user messages belonging to one open turn. */
 function requestMessages(agent, turn, proposed) {
 	const start = agent.session.events.findLastIndex((event) => event.type === "turn/start" && event.data.turn === turn);
@@ -360,20 +172,56 @@ function apply(ctx, config) {
 		formatters.set(selectedTimeZone, created);
 		return created;
 	};
+	ctx.sessionProjections.register({
+		key: "timeContext",
+		stateVersion: 2,
+		stateSchema: timeContextStateSchema,
+		init: () => ({
+			lastMessageTime: null,
+			lastInjectionTime: null,
+			lastTurnInjectionTime: null
+		}),
+		apply: (state, event) => {
+			if (event.type === "turn/start" || event.type === "turn/end") return state.lastTurnInjectionTime === null ? state : {
+				...state,
+				lastTurnInjectionTime: null
+			};
+			if (event.type === "user/message") {
+				const injected = event.data.source.kind === "plugin" && event.data.source.plugin === "time-context";
+				const withMessage = state.lastMessageTime === event.time ? state : {
+					...state,
+					lastMessageTime: event.time
+				};
+				if (!injected) return withMessage;
+				return {
+					...withMessage,
+					lastInjectionTime: event.time,
+					lastTurnInjectionTime: event.time
+				};
+			}
+			if (event.type === "assistant/message" || event.type === "tool/result") return state.lastMessageTime === event.time ? state : {
+				...state,
+				lastMessageTime: event.time
+			};
+			return state;
+		}
+	});
 	ctx.on("agent/pre-step", async ({ agent, turn, step, signal }, next) => {
 		const decision = await next();
 		if (decision.kind === "reject" || signal.aborted) return decision;
 		const now = Date.now();
+		const state = ctx.sessionProjections.stateOf(agent.session, "timeContext");
 		if (refreshIntervalMs !== void 0 && refreshIntervalMs > 0) {
-			const lastInjection = latestInjectionTime(agent);
-			if (lastInjection !== void 0 && now >= lastInjection && now - lastInjection < refreshIntervalMs) return decision;
+			const lastInjection = state.lastInjectionTime;
+			if (lastInjection != null && now >= lastInjection && now - lastInjection < refreshIntervalMs) return decision;
 		}
-		const previous = step === 1 ? precedingMessageTime(agent) : precedingStepContextTime(agent, turn);
+		/* v8 ignore next 6 -- every later step follows a recorded injection in the same turn */
+		const previous = step === 1 ? state.lastMessageTime ?? void 0 : state.lastTurnInjectionTime ?? void 0;
 		const browser = deriveBrowserTimeZoneContext(requestMessages(agent, turn, decision.messages));
 		const selectedTimeZone = browser.kind === "resolved" ? browser.timeZone : fallbackTimeZone;
 		const text = renderText(now, turn, step, previous, formatterFor(selectedTimeZone), selectedTimeZone, browser);
 		return {
-			kind: "enter",
+			...decision,
 			messages: [...decision.messages, createUserMessage({
 				content: [{
 					type: "text",

package/lib/invariant.js

@@ -1,93 +1,4 @@
-import { createRequire } from "node:module";
-import "@deepseek-ai/cordis";
-import z from "@deepseek-ai/schemastery";
-//#region ../../util/timeout/src/index.ts
-/** Largest delay Node schedules without clamping it to one millisecond. */
-const MAX_TIMER_DELAY_MS = 2147483647;
-//#endregion
-//#region ../../llm/llm/src/error.ts
-/**
-* Canonical provider-neutral code for a response that completed normally but
-* carried no content blocks at all. Providers occasionally emit a degenerate
-* completion (a terminal stop with zero output); adapters classify it as this
-* failure instead of yielding an empty assistant message, because an empty
-* message silently ends the turn with nothing for the user or the loop to act
-* on. The attempt produced nothing durable, so retry policy treats it as safe
-* to repeat.
-*/
-const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
-new RegExp(String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]` + String.raw`(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, "i");
-new RegExp(String.raw`\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?` + String.raw`too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?` + String.raw`(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, "i");
-new RegExp(String.raw`\b(?:input|prompt|request|messages?)\b.{0,40}` + String.raw`\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}` + String.raw`\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, "i");
-//#endregion
-//#region ../../llm/llm/src/retry-policy.ts
-/**
-* Provider-owned request-retry policy configuration and resolution.
-*
-* Adapters expose one resolved policy per registered provider route; the
-* optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
-*
-* @module @deepseek-ai/dsh-llm/retry-policy
-*/
-const DEFAULT_MAX_RETRIES = 5;
-const DEFAULT_INITIAL_DELAY_MS = 500;
-const DEFAULT_MAX_DELAY_MS = 1e4;
-const DEFAULT_JITTER_RATIO = .1;
-const DEFAULT_RETRYABLE_CODES = Object.freeze([
-	EMPTY_RESPONSE_CODE,
-	"RATE_LIMIT",
-	"SERVER",
-	"TIMEOUT",
-	"TRANSPORT"
-]);
-const backoffSchema = z.object({
-	initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
-	maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
-	jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO)
-});
-const normalPolicySchema = z.object({
-	mode: z.const("normal").required(),
-	maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
-	retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
-	backoff: backoffSchema
-});
-const alwaysPolicySchema = z.object({
-	mode: z.const("always").required(),
-	backoff: backoffSchema
-});
-z.union([normalPolicySchema, alwaysPolicySchema]);
-//#endregion
-//#region ../../llm/llm/src/attribution.ts
-/**
-* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
-* adapters from drifting. See
-* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
-*
-* App-attribution vocabulary for provider requests.
-* @module @deepseek-ai/dsh-llm/attribution
-*/
-const { version } = createRequire(import.meta.url)("../package.json");
-//#endregion
-//#region ../../llm/llm/src/never.ts
-/**
-* Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
-* new variant fails compilation at every required handler. Do not use it for declaration-merged
-* unions such as session events or content blocks: handle known variants and explicitly fall
-* through because plugins may add valid unknown cases.
-* @module @deepseek-ai/dsh-llm/never
-*/
-/**
-* Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
-* a value that escaped its type throws with diagnostics at runtime.
-* @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
-* @param context - optional label (e.g. the switch site) prefixed into the throw message.
-* @returns never — it always throws, with the offending value JSON-rendered in the message.
-*/
-function assertNever(value, context) {
-	const rendered = JSON.stringify(value) ?? String(value);
-	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
-}
-//#endregion
+import { assertNever } from "@deepseek-ai/dsh-util-values";
 //#region lib/types/request-zone.js
 /** Browser-zone derivation and model-facing policy text for one open request turn. */
 const IANA_TIME_ZONE = /^[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)+$/;

package/lib/types/index.d.ts

@@ -6,8 +6,22 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "time-context";
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** Latest time-context readings. */
+        timeContext: TimeContextProjection;
+    }
+}
+declare const timeContextStateSchema: zod.ZodObject<{
+    lastMessageTime: zod.ZodNullable<zod.ZodNumber>;
+    lastInjectionTime: zod.ZodNullable<zod.ZodNumber>;
+    lastTurnInjectionTime: zod.ZodNullable<zod.ZodNumber>;
+}, zod.core.$strip>;
+/** Folded time-context readings. */
+type TimeContextProjection = zod.infer<typeof timeContextStateSchema>;
 /** The agent registry that owns pre-step processing. */
 export declare const inject: string[];
 /** Request-preparation clock formatting and append scheduling. Invalid values fail plugin load. */
@@ -26,4 +40,5 @@ export declare const Config: z<Config>;
  * @throws when the refresh interval is invalid or the configured or process time zone cannot be resolved.
  */
 export declare function apply(ctx: Context, config: Config): void;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-time-context",
   "description": "Opt-in durable per-step context with the current time and elapsed time",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -32,24 +32,34 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "zod": "^4.4.3",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.3",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-app-boot": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-bash-local": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3"
   }
 }