@hydraharness/harness-time-context 0.0.0-stage → 0.1.1-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @hydraharness/harness-time-context
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).
+
+Elapsed-time and browser-zone context use events from the selected transcript version.
+
+## Config
+
+```yaml
+- id: time-context
+  name: '@hydraharness/harness-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
+```
+
+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`.
+
+`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
+
+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.
+
+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.
+
+## Timing semantics
+
+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.
+
+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.
+
+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.
+
+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.
+
+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`.
+
+## Model Experience
+
+### Preparation-time temporal context
+
+#### What the model sees
+
+Each injected message contains three lines. `<timestamp>` is an ISO-shaped timestamp with numeric offset and IANA zone; durations use compact whole-second units.
+
+##### First step
+
+```markdown
+Time sampled while preparing turn <turn>, step 1: <timestamp>
+Browser time zone for this request: <iana-zone-or-mixed-or-unavailable-policy>.
+Elapsed since the preceding model-visible message: <duration-or-unavailable>.
+```
+
+##### Later steps
+
+```markdown
+Time sampled while preparing turn <turn>, step <step>: <timestamp>
+Browser time zone for this request: <iana-zone-or-mixed-or-unavailable-policy>.
+Elapsed since the preceding step context: <duration-or-unavailable>.
+```
+
+#### Token effect
+
+Each reading accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one at 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
+
+- **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.

package/lib/index.js

@@ -0,0 +1,398 @@
+import { createRequire } from "node:module";
+import z from "@hydraharness/schemastery";
+import "@hydraharness/cordis";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#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 @hydraharness/harness-llm-retry plugin executes it on the agent's failed-step extension point.
+*
+* @module @hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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}`);
+}
+new AsyncLocalStorage();
+//#endregion
+//#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_+.-]+)+$/;
+/** Read and validate a Host-canonicalized browser zone from one ordinary user-rpc message. */
+function browserTimeZone(message) {
+	const source = message.source;
+	const value = source.kind === "user" && "rpcId" in source && typeof source.rpcId === "string" && "clientTimeZone" in source && typeof source.clientTimeZone === "string" ? source.clientTimeZone : void 0;
+	if (value === void 0) return void 0;
+	if (value !== "UTC" && !IANA_TIME_ZONE.test(value)) throw new TypeError(`browser time zone must be canonical UTC or IANA Area/Location: ${JSON.stringify(value)}`);
+	let canonical;
+	try {
+		canonical = new Intl.DateTimeFormat("en-US", { timeZone: value }).resolvedOptions().timeZone;
+	} catch (error) {
+		throw new TypeError(`browser time zone is unsupported: ${JSON.stringify(value)}`, { cause: error });
+	}
+	if (canonical !== value) throw new TypeError(`browser time zone must be canonical: ${JSON.stringify(value)}`);
+	return value;
+}
+/**
+* Derive the unique, mixed, or missing browser zone for one open turn.
+* @param messages - Entered and proposed user messages belonging to the turn.
+* @returns Sorted, duplicate-free browser-zone facts.
+* @throws TypeError when a user-rpc source carries an invalid or noncanonical zone.
+*/
+function deriveBrowserTimeZoneContext(messages) {
+	const timeZones = [...new Set(messages.flatMap((message) => {
+		const timeZone = browserTimeZone(message);
+		return timeZone === void 0 ? [] : [timeZone];
+	}))].sort();
+	const [timeZone, ...remaining] = timeZones;
+	if (timeZone === void 0) return { kind: "missing" };
+	if (remaining.length === 0) return {
+		kind: "resolved",
+		timeZone
+	};
+	return {
+		kind: "mixed",
+		timeZones
+	};
+}
+/**
+* Render the model instruction for one browser-zone context.
+* @param context - Browser-zone facts for the open turn.
+* @returns One durable policy line.
+*/
+function renderBrowserTimeZoneContext(context) {
+	switch (context.kind) {
+		case "resolved": return `Browser time zone for this request: ${context.timeZone}. Interpret otherwise-unqualified dates and times in this zone.`;
+		case "mixed": return `Browser time zone for this request: mixed ${JSON.stringify(context.timeZones)}. Ask the user to clarify otherwise-unqualified dates and times.`;
+		case "missing": return "Browser time zone for this request: unavailable. Ask the user to clarify otherwise-unqualified dates and times.";
+		/* v8 ignore next 2 -- the closed BrowserTimeZoneContext union is exhausted above. */
+		default: return assertNever(context, "BrowserTimeZoneContext");
+	}
+}
+//#endregion
+//#region lib/types/timestamp.js
+/** ISO-shaped time-context timestamp formatting shared by production and replay validation. */
+/**
+* Create the exact formatter used by durable time-context readings.
+* @param timeZone - Explicit display zone, or `undefined` for the process fallback.
+* @returns A formatter with stable numeric local fields and long numeric offset.
+*/
+function createTimestampFormatter(timeZone) {
+	return 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"
+	});
+}
+/**
+* Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone.
+* @param now - Epoch milliseconds to display.
+* @param formatter - Formatter created for `timeZone`.
+* @param timeZone - Canonical zone label carried in brackets.
+* @returns The durable timestamp text.
+*/
+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}]`;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Opt-in request clock context. Eligible steps add durable,
+* source-attributed time readings to the request history.
+*
+* @module @hydraharness/harness-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 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.activeEvents].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.activeEvents].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.activeEvents].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.activeEvents.findLastIndex((event) => event.type === "turn/start" && event.data.turn === turn);
+	return [...start < 0 ? [] : agent.session.activeEvents.slice(start + 1).flatMap((event) => event.type === "user/message" ? [event.data] : []), ...proposed];
+}
+function renderText(now, turn, step, previous, formatter, timeZone, browserContext) {
+	const elapsed = previous === void 0 ? "unavailable" : formatDuration(now - previous);
+	const baseline = step === 1 ? "model-visible message" : "step context";
+	const browserText = renderBrowserTimeZoneContext(browserContext);
+	return `Time sampled while preparing turn ${turn}, step ${step}: ${formatTimestamp(now, formatter, timeZone)}\n${browserText}\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 fallbackFormatter;
+	try {
+		fallbackFormatter = createTimestampFormatter(timeZone);
+	} 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 fallbackTimeZone = fallbackFormatter.resolvedOptions().timeZone;
+	const formatters = new Map([[fallbackTimeZone, fallbackFormatter]]);
+	/** Resolve and cache one request-local timestamp formatter. */
+	const formatterFor = (selectedTimeZone) => {
+		const existing = formatters.get(selectedTimeZone);
+		if (existing !== void 0) return existing;
+		const created = createTimestampFormatter(selectedTimeZone);
+		formatters.set(selectedTimeZone, created);
+		return created;
+	};
+	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 previous = step === 1 ? precedingMessageTime(agent) : precedingStepContextTime(agent, turn);
+		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",
+			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,302 @@
+import { createRequire } from "node:module";
+import { SessionVersionIndex } from "@hydraharness/harness-session";
+import "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#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 @hydraharness/harness-llm-retry plugin executes it on the agent's failed-step extension point.
+*
+* @module @hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-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}`);
+}
+new AsyncLocalStorage();
+//#endregion
+//#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_+.-]+)+$/;
+/** Read and validate a Host-canonicalized browser zone from one ordinary user-rpc message. */
+function browserTimeZone(message) {
+	const source = message.source;
+	const value = source.kind === "user" && "rpcId" in source && typeof source.rpcId === "string" && "clientTimeZone" in source && typeof source.clientTimeZone === "string" ? source.clientTimeZone : void 0;
+	if (value === void 0) return void 0;
+	if (value !== "UTC" && !IANA_TIME_ZONE.test(value)) throw new TypeError(`browser time zone must be canonical UTC or IANA Area/Location: ${JSON.stringify(value)}`);
+	let canonical;
+	try {
+		canonical = new Intl.DateTimeFormat("en-US", { timeZone: value }).resolvedOptions().timeZone;
+	} catch (error) {
+		throw new TypeError(`browser time zone is unsupported: ${JSON.stringify(value)}`, { cause: error });
+	}
+	if (canonical !== value) throw new TypeError(`browser time zone must be canonical: ${JSON.stringify(value)}`);
+	return value;
+}
+/**
+* Derive the unique, mixed, or missing browser zone for one open turn.
+* @param messages - Entered and proposed user messages belonging to the turn.
+* @returns Sorted, duplicate-free browser-zone facts.
+* @throws TypeError when a user-rpc source carries an invalid or noncanonical zone.
+*/
+function deriveBrowserTimeZoneContext(messages) {
+	const timeZones = [...new Set(messages.flatMap((message) => {
+		const timeZone = browserTimeZone(message);
+		return timeZone === void 0 ? [] : [timeZone];
+	}))].sort();
+	const [timeZone, ...remaining] = timeZones;
+	if (timeZone === void 0) return { kind: "missing" };
+	if (remaining.length === 0) return {
+		kind: "resolved",
+		timeZone
+	};
+	return {
+		kind: "mixed",
+		timeZones
+	};
+}
+/**
+* Render the model instruction for one browser-zone context.
+* @param context - Browser-zone facts for the open turn.
+* @returns One durable policy line.
+*/
+function renderBrowserTimeZoneContext(context) {
+	switch (context.kind) {
+		case "resolved": return `Browser time zone for this request: ${context.timeZone}. Interpret otherwise-unqualified dates and times in this zone.`;
+		case "mixed": return `Browser time zone for this request: mixed ${JSON.stringify(context.timeZones)}. Ask the user to clarify otherwise-unqualified dates and times.`;
+		case "missing": return "Browser time zone for this request: unavailable. Ask the user to clarify otherwise-unqualified dates and times.";
+		/* v8 ignore next 2 -- the closed BrowserTimeZoneContext union is exhausted above. */
+		default: return assertNever(context, "BrowserTimeZoneContext");
+	}
+}
+//#endregion
+//#region lib/types/timestamp.js
+/** ISO-shaped time-context timestamp formatting shared by production and replay validation. */
+/**
+* Create the exact formatter used by durable time-context readings.
+* @param timeZone - Explicit display zone, or `undefined` for the process fallback.
+* @returns A formatter with stable numeric local fields and long numeric offset.
+*/
+function createTimestampFormatter(timeZone) {
+	return 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"
+	});
+}
+/**
+* Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone.
+* @param now - Epoch milliseconds to display.
+* @param formatter - Formatter created for `timeZone`.
+* @param timeZone - Canonical zone label carried in brackets.
+* @returns The durable timestamp text.
+*/
+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}]`;
+}
+//#endregion
+//#region lib/types/invariant.js
+/** Package-owned durable clock-context invariants. @module @hydraharness/harness-time-context/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-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})\\[[^\\]]+\\])\\n(Browser time zone for this request: .+)\\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 open step boundary at which a time-context reading may append. */
+function preparationPosition(history, fail) {
+	let openTurn;
+	let openStep;
+	let requestStarted = false;
+	for (const event of history) switch (event.type) {
+		case "turn/start":
+			openTurn = event.data.turn;
+			openStep = void 0;
+			requestStarted = false;
+			break;
+		case "step/start":
+			openStep = event.data.step;
+			requestStarted = false;
+			break;
+		case "request/header":
+			requestStarted = true;
+			break;
+		case "step/end":
+			openStep = void 0;
+			requestStarted = false;
+			break;
+		case "turn/end":
+			openTurn = void 0;
+			openStep = void 0;
+			requestStarted = false;
+			break;
+		default: break;
+	}
+	if (openTurn === void 0) fail("time-context reading must be appended inside an open turn");
+	if (openStep === void 0) fail("time-context reading must follow step/start");
+	if (requestStarted) fail("time-context reading must precede request/header");
+	return {
+		turn: openTurn,
+		step: openStep
+	};
+}
+/** Collect the entered user messages belonging to one open turn. */
+function requestMessages(history, turn) {
+	const start = history.findLastIndex((event) => event.type === "turn/start" && event.data.turn === turn);
+	return history.slice(start + 1).flatMap((event) => event.type === "user/message" ? [event.data] : []);
+}
+/** Validate one plugin-attributed time reading against its session position and timestamp. */
+function validateReading(history, event, fail) {
+	const blockValue = event.data.content[0];
+	const block = typeof blockValue === "object" && blockValue !== null ? blockValue : void 0;
+	const blockText = block?.text;
+	if (event.data.content.length !== 1 || block === void 0 || Object.keys(block).length !== 2 || block.type !== "text" || typeof blockText !== "string") fail("time-context messages must contain exactly one text block");
+	const match = READING.exec(blockText);
+	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 source = event.data.source;
+	/* v8 ignore next 2 -- replay and dispatch callers select this exact package-owned source before validation. */
+	if (source.kind !== "plugin" || source.plugin !== SOURCE_NAME) fail("time-context source must retain package ownership");
+	const sections = "sections" in source ? source.sections : void 0;
+	const sectionValue = Array.isArray(sections) ? sections[0] : void 0;
+	const section = typeof sectionValue === "object" && sectionValue !== null ? sectionValue : void 0;
+	if (Object.keys(source).length !== 4 || source.form !== "snapshot" || !Array.isArray(sections) || sections.length !== 1 || section === void 0 || Object.keys(section).length !== 2 || section.name !== SOURCE_NAME || section.text !== blockText) fail("time-context source must carry only the exact snapshot text, not request authority");
+	const renderedBrowserContext = match[4];
+	const browserContext = deriveBrowserTimeZoneContext(requestMessages(history, turn));
+	if (renderedBrowserContext !== renderBrowserTimeZoneContext(browserContext)) fail("time-context browser-zone text does not match current-turn user messages");
+	const baseline = match[5];
+	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");
+	if (browserContext.kind === "resolved") {
+		let expectedTimestamp;
+		try {
+			expectedTimestamp = formatTimestamp(renderedTime, createTimestampFormatter(browserContext.timeZone), browserContext.timeZone);
+		} catch (error) {
+			fail(`time-context browser zone cannot format its durable timestamp: ${String(error)}`);
+		}
+		if (rendered !== expectedTimestamp) fail("time-context rendered timestamp does not match the unique browser zone");
+	}
+}
+/** Validate all package-owned readings already present in one session. */
+function validateSession(session, fail) {
+	const versions = new SessionVersionIndex();
+	for (const event of session.events) {
+		versions.append(event);
+		if (event.type !== "user/message" || event.data.source.kind !== "plugin" || event.data.source.plugin !== SOURCE_NAME) continue;
+		validateReading(versions.events().filter((entry) => entry.seq < event.seq), 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("session/created", (session) => {
+		validateSession(session, fail);
+	}, { global: true });
+	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.activeEvents, 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 @hydraharness/harness-time-context
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/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 {
+    /** Fallback display zone when the open turn has no unique browser zone. Omit to use the process zone. */
+    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 @hydraharness/harness-time-context/invariant */
+import type { Context } from '@hydraharness/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/lib/types/request-zone.d.ts

@@ -0,0 +1,26 @@
+/** Browser-zone derivation and model-facing policy text for one open request turn. */
+import type { UserMessage } from '@hydraharness/harness-llm';
+/** Browser-zone facts derived from user-rpc messages in one open turn. */
+export type BrowserTimeZoneContext = {
+    readonly kind: 'resolved';
+    readonly timeZone: string;
+} | {
+    readonly kind: 'mixed';
+    readonly timeZones: readonly string[];
+} | {
+    readonly kind: 'missing';
+};
+/**
+ * Derive the unique, mixed, or missing browser zone for one open turn.
+ * @param messages - Entered and proposed user messages belonging to the turn.
+ * @returns Sorted, duplicate-free browser-zone facts.
+ * @throws TypeError when a user-rpc source carries an invalid or noncanonical zone.
+ */
+export declare function deriveBrowserTimeZoneContext(messages: readonly UserMessage[]): BrowserTimeZoneContext;
+/**
+ * Render the model instruction for one browser-zone context.
+ * @param context - Browser-zone facts for the open turn.
+ * @returns One durable policy line.
+ */
+export declare function renderBrowserTimeZoneContext(context: BrowserTimeZoneContext): string;
+//# sourceMappingURL=request-zone.d.ts.map

package/lib/types/timestamp.d.ts

@@ -0,0 +1,16 @@
+/** ISO-shaped time-context timestamp formatting shared by production and replay validation. */
+/**
+ * Create the exact formatter used by durable time-context readings.
+ * @param timeZone - Explicit display zone, or `undefined` for the process fallback.
+ * @returns A formatter with stable numeric local fields and long numeric offset.
+ */
+export declare function createTimestampFormatter(timeZone?: string): Intl.DateTimeFormat;
+/**
+ * Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone.
+ * @param now - Epoch milliseconds to display.
+ * @param formatter - Formatter created for `timeZone`.
+ * @param timeZone - Canonical zone label carried in brackets.
+ * @returns The durable timestamp text.
+ */
+export declare function formatTimestamp(now: number, formatter: Intl.DateTimeFormat, timeZone: string): string;
+//# sourceMappingURL=timestamp.d.ts.map

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@hydraharness/harness-time-context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Opt-in durable per-step context with the current time and elapsed time",
+  "version": "0.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-session": "^0.1.1-rc.7"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.7",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-llm": "^0.1.1-rc.7",
+    "@hydraharness/harness-session": "^0.1.1-rc.7",
+    "@hydraharness/harness-loader-smoke": "^0.1.1-rc.7",
+    "@hydraharness/harness-tools": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.7"
+  }
 }