@deepseek-ai/dsh-time-context 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.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 packages/context/time-context/README.md
+README.md: 9956918c63b49de8ec5e739bc3d9887e269930a8
+README.zh.md: 3a9bb1012fc0639d9c3f6b104cea5a64d4b187d6

package/README.md

@@ -0,0 +1,70 @@
+# @deepseek-ai/dsh-time-context
+
+English | [中文](README.zh.md)
+
+Opt-in durable context with the current zoned time and elapsed time sampled during model-request preparation. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the durable time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md).
+
+## Config
+
+```yaml
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+  config:
+    timeZone: Asia/Shanghai  # optional IANA override; omit for the process zone
+    refreshIntervalMs: 60000 # optional; omit or set to 0 for every eligible attempt
+```
+
+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. 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 have elapsed since the latest injection.
+
+## Timing semantics
+
+The plugin prepends an `agent/pre-step` listener. When an injection is due and the downstream decision enters the proposed step, it adds one sourced `UserMessage` to the returned batch. AgentLoop records that context after `step/start` and before ordinary automatic compaction with source `{ kind: 'plugin', plugin: 'time-context' }`. A suppressed, rejected, or failed pre-step records nothing.
+
+Positive-interval scheduling scans the raw durable session events for the latest `user/message` with that source, including a reading shadowed by compaction. The schedule therefore applies across turns and resumed processes without process-local cache state. It reduces append frequency and history growth but never removes an existing reading, and sessions schedule independently.
+
+Step 1 measures from the latest preceding model-visible message, including the prompt that opened the turn. Later steps measure from the preceding time-context event in the same turn. Both baselines use durable session-event timestamps; backward wall-clock movement clamps elapsed time to zero. A missing first-step baseline, or a later step with no earlier same-turn reading because interval suppression skipped it, reports `unavailable`.
+
+A time reading records an entered pre-step batch, not a completed step or transmitted request. A later request-preparation failure can therefore leave the reading in history, but a downstream pre-step listener that rejects or fails prevents it from being recorded.
+
+The separately published `./invariant` companion checks each plugin-attributed reading against the open turn, next pre-step position, elapsed baseline, and durable event time. Its rendered timestamp must parse and cannot postdate the event; process suspension between sampling and append does not invalidate the reading.
+
+The time reading stays in derived conversation history until a later compaction shadows it. Request headers contain no time-context state. Request reconstruction uses the complete durable surface prefix after each `step/start`, so transmitted requests need not map one-to-one to readings: request preparation can fail after step entry, while interval suppression can let a request reuse existing history without adding one.
+
+## Model Experience
+
+### Preparation-time temporal context
+
+#### What the model sees
+
+On each preparation attempt that injects, one source-tagged context message containing the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; durations use compact whole-second units. Positive intervals can leave an attempted step without a new reading.
+
+##### First step
+
+```markdown
+Time sampled while preparing turn <turn>, step 1: <timestamp>
+Elapsed since the preceding model-visible message: <duration-or-unavailable>.
+```
+
+##### Later steps
+
+```markdown
+Time sampled while preparing turn <turn>, step <step>: <timestamp>
+Elapsed since the preceding step context: <duration-or-unavailable>.
+```
+
+#### Token effect
+
+Each injected two-line message accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one for every eligible preparation attempt.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Whole-second display** — timestamps and durations omit sub-second precision even though durable event times retain milliseconds.
+- **Session-event baseline** — elapsed time starts from durable append timestamps, 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.
+- **History cost between compactions** — omission or `0` retains one reading for every eligible preparation attempt, including attempts later cancelled or failed; a positive interval reduces but does not eliminate this cost.

package/README.zh.md

@@ -0,0 +1,70 @@
+# @deepseek-ai/dsh-time-context
+
+[English](README.md) | 中文
+
+可选的持久上下文，包含模型请求准备期间采样的带时区的当前时间与经过时长。`dsh-agent-spine-demo` 与随附示例不挂载该插件。决策记录：[持久 time-context Agent Note](../../../.agents/notes/implemented/feature/2026-07-16-durable-per-step-time-context.md)。
+
+## 配置
+
+```yaml
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+  config:
+    timeZone: Asia/Shanghai  # optional IANA override; omit for the process zone
+    refreshIntervalMs: 60000 # optional; omit or set to 0 for every eligible attempt
+```
+
+省略 `timeZone` 时，插件会在加载时解析一次 Node 进程的系统时区。Node 遵循 `TZ`；如果没有该覆盖，时区由宿主或容器提供。显式 `timeZone` 必须是 IANA 标识符，并在插件加载时验证。
+
+`refreshIntervalMs` 必须是非负安全整数。省略或设为 `0` 时，会为每次信号尚未中止且会进入步骤的合格步骤前处理添加上下文。正数值只会在会话没有早先 time-context 注入、挂钟时间倒退，或自最新注入起已经过至少相应毫秒数时添加上下文。
+
+## 时序语义
+
+该插件会前置一个 `agent/pre-step` 监听器。需要注入且下游决策进入拟议步骤时，它会在返回批次中添加一条带来源的 `UserMessage`。AgentLoop 会在 `step/start` 之后、普通自动压缩（compaction）之前记录该上下文，其来源为 `{ kind: 'plugin', plugin: 'time-context' }`。被抑制、拒绝或失败的步骤前处理不会记录任何内容。
+
+正间隔调度会扫描原始持久会话事件，查找最新的上述源 `user/message`，包括已被压缩遮蔽的时间读数。因此，调度可以跨轮次以及进程恢复持续生效，不需要进程本地缓存状态。它会降低追加频率与历史增长，但绝不移除现有时间读数，且每个会话独立调度。
+
+第 1 步从前一条模型可见消息起测量，包括开启轮次的提示词。后续步骤从同一轮次中前一个 time-context 事件起测量。两种基线都使用持久会话事件时间戳；挂钟时间倒退时，经过时长限制为零。如果第一步缺少基线，或者后续步骤因间隔抑制而没有较早的同轮次时间读数，则报告 `unavailable`。
+
+时间读数记录的是一个已进入步骤的步骤前批次，不是已完成步骤或已传输请求。后续请求准备失败时，该读数可能已留在历史中；但下游步骤前监听器拒绝或失败时，该读数不会被记录。
+
+单独发布的 `./invariant` 配套模块会根据当前未结束的轮次、下一个步骤前位置、经过时长基线与持久事件时间检查每个归因于插件的时间读数。其渲染时间戳必须可解析，且不能晚于该事件；采样与追加之间的进程挂起不会使时间读数失效。
+
+时间读数会保留在派生会话历史中，直到后续压缩遮蔽它。请求标头不含 time-context 状态。请求重建会在每个 `step/start` 之后使用完整持久表层前缀，因此已传输请求无需与时间读数一一对应：请求准备可能在进入步骤后失败，而间隔抑制可让请求复用现有历史，无需添加时间读数。
+
+## 模型体验
+
+### 准备期时间上下文
+
+#### 模型看到的内容
+
+每次执行注入的准备尝试都会生成一条带源标记的上下文消息，包含下方两行。`<timestamp>` 是带数字偏移与 IANA 时区、形如 ISO 的本地时间戳；持续时间使用紧凑的整秒单位。正间隔可能使某次步骤尝试没有新时间读数。
+
+##### 第一步
+
+```markdown
+Time sampled while preparing turn <turn>, step 1: <timestamp>
+Elapsed since the preceding model-visible message: <duration-or-unavailable>.
+```
+
+##### 后续步骤
+
+```markdown
+Time sampled while preparing turn <turn>, step <step>: <timestamp>
+Elapsed since the preceding step context: <duration-or-unavailable>.
+```
+
+#### Token 影响
+
+每条注入的两行消息都会累积，直到压缩遮蔽它。正间隔会减少添加；省略或设为 `0` 则会为每次合格准备尝试添加一条。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **整秒显示**：时间戳与持续时间省略亚秒精度，尽管持久事件时间保留毫秒。
+- **会话事件基线**：经过时长从持久追加时间戳起计算，而非客户端传输的原始发送时间戳。
+- **进程本地默认时区**：省略设置时，使用插件加载时捕获的 Node 进程 `TZ`、宿主或容器时区，而非远程用户的时区；两者不同时，请配置显式 IANA 时区。
+- **压缩之间的历史成本**：省略设置或设为 `0` 会为每次合格准备尝试保留一条时间读数，包括后续取消或失败的尝试；正间隔可以降低但无法消除该成本。

package/lib/index.js

@@ -0,0 +1,286 @@
+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 = 2;
+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 lib/types/index.js
+/**
+* Opt-in request clock context. Eligible steps add durable,
+* source-attributed time readings to the request history.
+*
+* @module @deepseek-ai/dsh-time-context
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "time-context";
+/** The agent registry that owns pre-step processing. */
+const inject = ["agents"];
+/** Schemastery validation for {@link Config}. */
+const Config = z.object({
+	timeZone: z.string(),
+	refreshIntervalMs: z.number()
+});
+/** Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone. */
+function formatTimestamp(now, formatter, timeZone) {
+	const parts = Object.fromEntries(formatter.formatToParts(now).map((part) => [part.type, part.value]));
+	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) {
+	let seconds = Math.floor(Math.max(0, elapsedMs) / 1e3);
+	const days = Math.floor(seconds / 86400);
+	seconds %= 86400;
+	const hours = Math.floor(seconds / 3600);
+	seconds %= 3600;
+	const minutes = Math.floor(seconds / 60);
+	seconds %= 60;
+	const parts = [];
+	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(" ");
+}
+/** 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;
+}
+function renderText(now, turn, step, previous, formatter, timeZone) {
+	const elapsed = previous === void 0 ? "unavailable" : formatDuration(now - previous);
+	const baseline = step === 1 ? "model-visible message" : "step context";
+	return `Time sampled while preparing turn ${turn}, step ${step}: ${formatTimestamp(now, formatter, timeZone)}\nElapsed since the preceding ${baseline}: ${elapsed}.`;
+}
+/** Reject refresh intervals that cannot represent an exact elapsed-millisecond threshold. */
+function validateRefreshInterval(refreshIntervalMs) {
+	if (refreshIntervalMs !== void 0 && (!Number.isSafeInteger(refreshIntervalMs) || refreshIntervalMs < 0)) throw new TypeError(`time-context: refreshIntervalMs must be a non-negative safe integer, got ${String(refreshIntervalMs)}`);
+}
+/**
+* Register a prepended pre-step listener for the lifetime of `ctx`.
+* @param ctx - plugin context; the listener is disposed with it.
+* @param config - time zone and durable refresh scheduling configuration.
+* @throws when the refresh interval is invalid or the configured or process time zone cannot be resolved.
+*/
+function apply(ctx, config) {
+	const timeZone = config.timeZone;
+	const refreshIntervalMs = config.refreshIntervalMs;
+	validateRefreshInterval(refreshIntervalMs);
+	let formatter;
+	try {
+		formatter = new Intl.DateTimeFormat("en-US", {
+			...timeZone === void 0 ? {} : { timeZone },
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			hourCycle: "h23",
+			timeZoneName: "longOffset"
+		});
+	} catch (error) {
+		const message = timeZone === void 0 ? "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;
+	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();
+		if (refreshIntervalMs !== void 0 && refreshIntervalMs > 0) {
+			const lastInjection = latestInjectionTime(agent);
+			if (lastInjection !== void 0 && now >= lastInjection && now - lastInjection < refreshIntervalMs) return decision;
+		}
+		const text = renderText(now, turn, step, step === 1 ? precedingMessageTime(agent) : precedingStepContextTime(agent, turn), formatter, resolvedTimeZone);
+		return {
+			kind: "enter",
+			messages: [...decision.messages, createUserMessage({
+				content: [{
+					type: "text",
+					text
+				}],
+				source: {
+					kind: "plugin",
+					plugin: name,
+					form: "snapshot",
+					sections: [{
+						name,
+						text
+					}]
+				}
+			})]
+		};
+	}, { prepend: true });
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,74 @@
+//#region lib/types/invariant.js
+/** Package-owned durable clock-context invariants. @module @deepseek-ai/dsh-time-context/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-time-context";
+const SOURCE_NAME = "time-context";
+const READING = /* @__PURE__ */ new RegExp("^Time sampled while preparing turn (\\d+), step (\\d+): (\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2})\\[[^\\]]+\\])\\nElapsed since the preceding (model-visible message|step context): (?:unavailable|(?:(?:\\d+d )?(?:\\d+h )?(?:\\d+m )?\\d+s))\\.$");
+/** Cordis companion plugin name. */
+const name = "time-context-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Derive the entered step boundary at which a time-context reading may append. */
+function preparationPosition(history, fail) {
+	for (const event of history.slice().reverse()) switch (event.type) {
+		case "step/start": return {
+			turn: event.data.turn,
+			step: event.data.step
+		};
+		case "turn/start":
+		case "step/end":
+		case "turn/end":
+		case "request/header":
+		case "assistant/chunk":
+		case "assistant/message":
+		case "tool/call":
+		case "tool/result":
+			fail("time-context reading must be appended during prompt assembly");
+			break;
+		default: break;
+	}
+	fail("time-context reading must be appended during prompt assembly");
+}
+/** Validate one plugin-attributed time reading against its session position and timestamp. */
+function validateReading(history, event, fail) {
+	const [block] = event.data.content;
+	if (event.data.content.length !== 1 || block?.type !== "text") fail("time-context messages must contain exactly one text block");
+	const match = READING.exec(block.text);
+	if (match === null) fail("time-context message does not match the durable reading format");
+	const turn = Number(match[1]);
+	const step = Number(match[2]);
+	if (!Number.isSafeInteger(turn) || turn < 1 || !Number.isSafeInteger(step) || step < 1) fail("time-context turn and step must be positive safe integers");
+	const expected = preparationPosition(history, fail);
+	if (turn !== expected.turn || step !== expected.step) fail(`time-context reading names turn ${turn}/step ${step}, expected turn ${expected.turn}/step ${expected.step}`);
+	const baseline = match[4];
+	if (step === 1 !== (baseline === "model-visible message")) fail(`time-context step ${step} uses the wrong elapsed-time baseline ${JSON.stringify(baseline)}`);
+	const rendered = match[3];
+	/* v8 ignore next -- the preceding fixed regexp always supplies capture group three. */
+	if (rendered === void 0) fail("time-context reading omitted its rendered timestamp");
+	const renderedTime = Date.parse(rendered.replace(/\[[^\]]+\]$/, ""));
+	if (!Number.isFinite(renderedTime) || !Number.isSafeInteger(event.time) || event.time < renderedTime) fail("time-context rendered timestamp must parse and not postdate its durable event");
+}
+/** Validate all package-owned readings already present in one session. */
+function validateSession(session, fail) {
+	for (const [index, event] of session.events.entries()) {
+		if (event.type !== "user/message" || event.data.source.kind !== "plugin" || event.data.source.plugin !== SOURCE_NAME) continue;
+		validateReading(session.events.slice(0, index), event, fail);
+	}
+}
+/** Install validation for loaded and newly appended context readings. */
+const install = Object.assign((ctx, fail) => {
+	for (const session of ctx.sessions.list()) validateSession(session, fail);
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		if (event.type !== "user/message" || event.data.source.kind !== "plugin" || event.data.source.plugin !== SOURCE_NAME) return;
+		validateReading(session.events, event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the time-context invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Opt-in request clock context. Eligible steps add durable,
+ * source-attributed time readings to the request history.
+ *
+ * @module @deepseek-ai/dsh-time-context
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "time-context";
+/** 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. */
+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;
+    /** Minimum milliseconds between durable injections in one session. Omit or set to 0 to inject at every eligible step. */
+    refreshIntervalMs?: number;
+}
+/** Schemastery validation for {@link Config}. */
+export declare const Config: z<Config>;
+/**
+ * Register a prepended pre-step listener for the lifetime of `ctx`.
+ * @param ctx - plugin context; the listener is disposed with it.
+ * @param config - time zone and durable refresh scheduling configuration.
+ * @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;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned durable clock-context invariants. @module @deepseek-ai/dsh-time-context/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "time-context-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the time-context invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@deepseek-ai/dsh-time-context",
+  "description": "Opt-in durable per-step context with the current time and elapsed time",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/context/time-context"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}