gsd-pi 2.78.0 → 2.78.1-dev.8a893322c

package/packages/pi-coding-agent/dist/tests/token-telemetry.test.js

@@ -0,0 +1,181 @@
+// @gsd/pi-coding-agent + token-telemetry.test — coverage for #5023.
+// Verifies the env-gated emitter:
+//   - is silent by default (no behavior change for existing users)
+//   - emits a single valid JSON line when PI_TOKEN_TELEMETRY=1
+//   - record shape captures the cache breakdown the providers already extract
+//   - cacheHitRatio math is correct, including the no-input edge case
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { buildTokenTelemetryRecord, emitTokenTelemetry } from "../core/token-telemetry.js";
+function makeAssistantMessage(overrides = {}) {
+    return {
+        role: "assistant",
+        content: [],
+        api: "anthropic-messages",
+        provider: "anthropic",
+        model: "claude-sonnet-4-6",
+        usage: {
+            input: 100,
+            output: 50,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 150,
+            cost: { input: 0.3, output: 0.75, cacheRead: 0, cacheWrite: 0, total: 1.05 },
+        },
+        stopReason: "stop",
+        timestamp: 1700000000000,
+        ...overrides,
+    };
+}
+// ─── buildTokenTelemetryRecord ─────────────────────────────────────────────
+describe("buildTokenTelemetryRecord", () => {
+    test("captures all fields from a typical message", () => {
+        const msg = makeAssistantMessage();
+        const record = buildTokenTelemetryRecord(msg);
+        assert.deepEqual(record, {
+            ts: 1700000000000,
+            model: "claude-sonnet-4-6",
+            stopReason: "stop",
+            input: 100,
+            output: 50,
+            cacheRead: 0,
+            cacheWrite: 0,
+            costTotal: 1.05,
+            cacheHitRatio: 0,
+        });
+    });
+    test("cacheHitRatio = read / (read + input) when both present", () => {
+        const msg = makeAssistantMessage({
+            usage: {
+                input: 200,
+                output: 50,
+                cacheRead: 800,
+                cacheWrite: 0,
+                totalTokens: 1050,
+                cost: { input: 0.6, output: 0.75, cacheRead: 0.24, cacheWrite: 0, total: 1.59 },
+            },
+        });
+        const record = buildTokenTelemetryRecord(msg);
+        assert.equal(record.cacheRead, 800);
+        assert.equal(record.input, 200);
+        assert.equal(record.cacheHitRatio, 0.8);
+    });
+    test("cacheHitRatio = 0 when both read and input are 0 (no division-by-zero)", () => {
+        const msg = makeAssistantMessage({
+            usage: {
+                input: 0,
+                output: 50,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 50,
+                cost: { input: 0, output: 0.75, cacheRead: 0, cacheWrite: 0, total: 0.75 },
+            },
+        });
+        const record = buildTokenTelemetryRecord(msg);
+        assert.equal(record.cacheHitRatio, 0);
+    });
+    test("cacheHitRatio = 1 when only cacheRead present (full hit)", () => {
+        const msg = makeAssistantMessage({
+            usage: {
+                input: 0,
+                output: 50,
+                cacheRead: 5000,
+                cacheWrite: 0,
+                totalTokens: 5050,
+                cost: { input: 0, output: 0.75, cacheRead: 1.5, cacheWrite: 0, total: 2.25 },
+            },
+        });
+        const record = buildTokenTelemetryRecord(msg);
+        assert.equal(record.cacheHitRatio, 1);
+    });
+    test("cacheWrite is captured (the cache-miss-with-cache-control case from #5019)", () => {
+        const msg = makeAssistantMessage({
+            usage: {
+                input: 50,
+                output: 100,
+                cacheRead: 0,
+                cacheWrite: 5000,
+                totalTokens: 5150,
+                cost: { input: 0.15, output: 1.5, cacheRead: 0, cacheWrite: 18.75, total: 20.4 },
+            },
+        });
+        const record = buildTokenTelemetryRecord(msg);
+        assert.equal(record.cacheWrite, 5000);
+        assert.equal(record.cacheHitRatio, 0, "no read = ratio 0 even when write is large");
+    });
+    test("error stopReason is captured verbatim", () => {
+        const msg = makeAssistantMessage({ stopReason: "error", errorMessage: "rate_limit" });
+        assert.equal(buildTokenTelemetryRecord(msg).stopReason, "error");
+    });
+});
+// ─── emitTokenTelemetry ────────────────────────────────────────────────────
+describe("emitTokenTelemetry", () => {
+    let captured;
+    let originalWrite;
+    let originalEnv;
+    beforeEach(() => {
+        captured = [];
+        originalWrite = process.stderr.write.bind(process.stderr);
+        // Replace stderr.write with a capture; preserve the same return contract.
+        process.stderr.write = ((chunk) => {
+            captured.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+            return true;
+        });
+        originalEnv = process.env.PI_TOKEN_TELEMETRY;
+    });
+    afterEach(() => {
+        process.stderr.write = originalWrite;
+        if (originalEnv === undefined) {
+            delete process.env.PI_TOKEN_TELEMETRY;
+        }
+        else {
+            process.env.PI_TOKEN_TELEMETRY = originalEnv;
+        }
+    });
+    test("silent by default (env var unset)", () => {
+        delete process.env.PI_TOKEN_TELEMETRY;
+        emitTokenTelemetry(makeAssistantMessage());
+        assert.equal(captured.length, 0);
+    });
+    test("silent when env var has any non-'1' value", () => {
+        process.env.PI_TOKEN_TELEMETRY = "true"; // not literally "1"
+        emitTokenTelemetry(makeAssistantMessage());
+        assert.equal(captured.length, 0, "only literal '1' should enable telemetry");
+    });
+    test("emits a single JSON line when PI_TOKEN_TELEMETRY=1", () => {
+        process.env.PI_TOKEN_TELEMETRY = "1";
+        emitTokenTelemetry(makeAssistantMessage());
+        assert.equal(captured.length, 1);
+        assert.ok(captured[0].endsWith("\n"), "line must terminate with newline");
+        const parsed = JSON.parse(captured[0].trimEnd());
+        assert.equal(parsed.model, "claude-sonnet-4-6");
+        assert.equal(parsed.input, 100);
+        assert.equal(parsed.output, 50);
+    });
+    test("emitted JSON has the documented shape", () => {
+        process.env.PI_TOKEN_TELEMETRY = "1";
+        emitTokenTelemetry(makeAssistantMessage());
+        const parsed = JSON.parse(captured[0].trimEnd());
+        const keys = Object.keys(parsed).sort();
+        assert.deepEqual(keys, [
+            "cacheHitRatio",
+            "cacheRead",
+            "cacheWrite",
+            "costTotal",
+            "input",
+            "model",
+            "output",
+            "stopReason",
+            "ts",
+        ]);
+    });
+    test("never throws — telemetry must not break the agent loop", () => {
+        process.env.PI_TOKEN_TELEMETRY = "1";
+        // Force a write failure to exercise the swallow path.
+        process.stderr.write = (() => {
+            throw new Error("simulated stderr failure");
+        });
+        assert.doesNotThrow(() => emitTokenTelemetry(makeAssistantMessage()));
+    });
+});
+//# sourceMappingURL=token-telemetry.test.js.map

package/packages/pi-coding-agent/dist/tests/token-telemetry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-telemetry.test.js","sourceRoot":"","sources":["../../src/tests/token-telemetry.test.ts"],"names":[],"mappings":"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","sourcesContent":["// @gsd/pi-coding-agent + token-telemetry.test — coverage for #5023.\n// Verifies the env-gated emitter:\n//   - is silent by default (no behavior change for existing users)\n//   - emits a single valid JSON line when PI_TOKEN_TELEMETRY=1\n//   - record shape captures the cache breakdown the providers already extract\n//   - cacheHitRatio math is correct, including the no-input edge case\n\nimport { describe, test, beforeEach, afterEach } from \"node:test\";\nimport assert from \"node:assert/strict\";\n\nimport type { AssistantMessage } from \"@gsd/pi-ai\";\n\nimport { buildTokenTelemetryRecord, emitTokenTelemetry } from \"../core/token-telemetry.js\";\n\nfunction makeAssistantMessage(overrides: Partial<AssistantMessage> = {}): AssistantMessage {\n\treturn {\n\t\trole: \"assistant\",\n\t\tcontent: [],\n\t\tapi: \"anthropic-messages\",\n\t\tprovider: \"anthropic\",\n\t\tmodel: \"claude-sonnet-4-6\",\n\t\tusage: {\n\t\t\tinput: 100,\n\t\t\toutput: 50,\n\t\t\tcacheRead: 0,\n\t\t\tcacheWrite: 0,\n\t\t\ttotalTokens: 150,\n\t\t\tcost: { input: 0.3, output: 0.75, cacheRead: 0, cacheWrite: 0, total: 1.05 },\n\t\t},\n\t\tstopReason: \"stop\",\n\t\ttimestamp: 1700000000000,\n\t\t...overrides,\n\t};\n}\n\n// ─── buildTokenTelemetryRecord ─────────────────────────────────────────────\n\ndescribe(\"buildTokenTelemetryRecord\", () => {\n\ttest(\"captures all fields from a typical message\", () => {\n\t\tconst msg = makeAssistantMessage();\n\t\tconst record = buildTokenTelemetryRecord(msg);\n\t\tassert.deepEqual(record, {\n\t\t\tts: 1700000000000,\n\t\t\tmodel: \"claude-sonnet-4-6\",\n\t\t\tstopReason: \"stop\",\n\t\t\tinput: 100,\n\t\t\toutput: 50,\n\t\t\tcacheRead: 0,\n\t\t\tcacheWrite: 0,\n\t\t\tcostTotal: 1.05,\n\t\t\tcacheHitRatio: 0,\n\t\t});\n\t});\n\n\ttest(\"cacheHitRatio = read / (read + input) when both present\", () => {\n\t\tconst msg = makeAssistantMessage({\n\t\t\tusage: {\n\t\t\t\tinput: 200,\n\t\t\t\toutput: 50,\n\t\t\t\tcacheRead: 800,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 1050,\n\t\t\t\tcost: { input: 0.6, output: 0.75, cacheRead: 0.24, cacheWrite: 0, total: 1.59 },\n\t\t\t},\n\t\t});\n\t\tconst record = buildTokenTelemetryRecord(msg);\n\t\tassert.equal(record.cacheRead, 800);\n\t\tassert.equal(record.input, 200);\n\t\tassert.equal(record.cacheHitRatio, 0.8);\n\t});\n\n\ttest(\"cacheHitRatio = 0 when both read and input are 0 (no division-by-zero)\", () => {\n\t\tconst msg = makeAssistantMessage({\n\t\t\tusage: {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 50,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 50,\n\t\t\t\tcost: { input: 0, output: 0.75, cacheRead: 0, cacheWrite: 0, total: 0.75 },\n\t\t\t},\n\t\t});\n\t\tconst record = buildTokenTelemetryRecord(msg);\n\t\tassert.equal(record.cacheHitRatio, 0);\n\t});\n\n\ttest(\"cacheHitRatio = 1 when only cacheRead present (full hit)\", () => {\n\t\tconst msg = makeAssistantMessage({\n\t\t\tusage: {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 50,\n\t\t\t\tcacheRead: 5000,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 5050,\n\t\t\t\tcost: { input: 0, output: 0.75, cacheRead: 1.5, cacheWrite: 0, total: 2.25 },\n\t\t\t},\n\t\t});\n\t\tconst record = buildTokenTelemetryRecord(msg);\n\t\tassert.equal(record.cacheHitRatio, 1);\n\t});\n\n\ttest(\"cacheWrite is captured (the cache-miss-with-cache-control case from #5019)\", () => {\n\t\tconst msg = makeAssistantMessage({\n\t\t\tusage: {\n\t\t\t\tinput: 50,\n\t\t\t\toutput: 100,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 5000,\n\t\t\t\ttotalTokens: 5150,\n\t\t\t\tcost: { input: 0.15, output: 1.5, cacheRead: 0, cacheWrite: 18.75, total: 20.4 },\n\t\t\t},\n\t\t});\n\t\tconst record = buildTokenTelemetryRecord(msg);\n\t\tassert.equal(record.cacheWrite, 5000);\n\t\tassert.equal(record.cacheHitRatio, 0, \"no read = ratio 0 even when write is large\");\n\t});\n\n\ttest(\"error stopReason is captured verbatim\", () => {\n\t\tconst msg = makeAssistantMessage({ stopReason: \"error\", errorMessage: \"rate_limit\" });\n\t\tassert.equal(buildTokenTelemetryRecord(msg).stopReason, \"error\");\n\t});\n});\n\n// ─── emitTokenTelemetry ────────────────────────────────────────────────────\n\ndescribe(\"emitTokenTelemetry\", () => {\n\tlet captured: string[];\n\tlet originalWrite: typeof process.stderr.write;\n\tlet originalEnv: string | undefined;\n\n\tbeforeEach(() => {\n\t\tcaptured = [];\n\t\toriginalWrite = process.stderr.write.bind(process.stderr);\n\t\t// Replace stderr.write with a capture; preserve the same return contract.\n\t\tprocess.stderr.write = ((chunk: string | Uint8Array): boolean => {\n\t\t\tcaptured.push(typeof chunk === \"string\" ? chunk : Buffer.from(chunk).toString());\n\t\t\treturn true;\n\t\t}) as typeof process.stderr.write;\n\t\toriginalEnv = process.env.PI_TOKEN_TELEMETRY;\n\t});\n\n\tafterEach(() => {\n\t\tprocess.stderr.write = originalWrite;\n\t\tif (originalEnv === undefined) {\n\t\t\tdelete process.env.PI_TOKEN_TELEMETRY;\n\t\t} else {\n\t\t\tprocess.env.PI_TOKEN_TELEMETRY = originalEnv;\n\t\t}\n\t});\n\n\ttest(\"silent by default (env var unset)\", () => {\n\t\tdelete process.env.PI_TOKEN_TELEMETRY;\n\t\temitTokenTelemetry(makeAssistantMessage());\n\t\tassert.equal(captured.length, 0);\n\t});\n\n\ttest(\"silent when env var has any non-'1' value\", () => {\n\t\tprocess.env.PI_TOKEN_TELEMETRY = \"true\"; // not literally \"1\"\n\t\temitTokenTelemetry(makeAssistantMessage());\n\t\tassert.equal(captured.length, 0, \"only literal '1' should enable telemetry\");\n\t});\n\n\ttest(\"emits a single JSON line when PI_TOKEN_TELEMETRY=1\", () => {\n\t\tprocess.env.PI_TOKEN_TELEMETRY = \"1\";\n\t\temitTokenTelemetry(makeAssistantMessage());\n\t\tassert.equal(captured.length, 1);\n\t\tassert.ok(captured[0].endsWith(\"\\n\"), \"line must terminate with newline\");\n\t\tconst parsed = JSON.parse(captured[0].trimEnd());\n\t\tassert.equal(parsed.model, \"claude-sonnet-4-6\");\n\t\tassert.equal(parsed.input, 100);\n\t\tassert.equal(parsed.output, 50);\n\t});\n\n\ttest(\"emitted JSON has the documented shape\", () => {\n\t\tprocess.env.PI_TOKEN_TELEMETRY = \"1\";\n\t\temitTokenTelemetry(makeAssistantMessage());\n\t\tconst parsed = JSON.parse(captured[0].trimEnd());\n\t\tconst keys = Object.keys(parsed).sort();\n\t\tassert.deepEqual(keys, [\n\t\t\t\"cacheHitRatio\",\n\t\t\t\"cacheRead\",\n\t\t\t\"cacheWrite\",\n\t\t\t\"costTotal\",\n\t\t\t\"input\",\n\t\t\t\"model\",\n\t\t\t\"output\",\n\t\t\t\"stopReason\",\n\t\t\t\"ts\",\n\t\t]);\n\t});\n\n\ttest(\"never throws — telemetry must not break the agent loop\", () => {\n\t\tprocess.env.PI_TOKEN_TELEMETRY = \"1\";\n\t\t// Force a write failure to exercise the swallow path.\n\t\tprocess.stderr.write = (() => {\n\t\t\tthrow new Error(\"simulated stderr failure\");\n\t\t}) as typeof process.stderr.write;\n\t\tassert.doesNotThrow(() => emitTokenTelemetry(makeAssistantMessage()));\n\t});\n});\n"]}

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "2.78.0",
+  "version": "2.78.1",
   "description": "Coding agent CLI (vendored from pi-mono)",
   "type": "module",
   "gsd": {

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -78,6 +78,7 @@ import { getLatestCompactionEntry } from "./session-manager.js";
 import type { SettingsManager } from "./settings-manager.js";
 import { BUILTIN_SLASH_COMMANDS, type SlashCommandInfo, type SlashCommandLocation } from "./slash-commands.js";
 import { buildSystemPrompt } from "./system-prompt.js";
+import { emitTokenTelemetry } from "./token-telemetry.js";
 import type { BashOperations } from "./tools/bash.js";
 import { createAllTools } from "./tools/index.js";
 
@@ -470,6 +471,12 @@ export class AgentSession {
 				this._cumulativeOutputTokens += assistantMsg.usage?.output ?? 0;
 				this._cumulativeToolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
 
+				// Per-call token telemetry (off by default; gated by PI_TOKEN_TELEMETRY=1).
+				// Note: a turn that retries emits one record per attempt — group by
+				// session/turn downstream if you want a deduplicated view. Both records
+				// are valid (each was a billed/attempted API call). #5023
+				emitTokenTelemetry(assistantMsg);
+
 				if (assistantMsg.stopReason !== "error") {
 					this._compactionOrchestrator.clearOverflowRecovery();
 				}

package/packages/pi-coding-agent/src/core/messages.ts

@@ -207,6 +207,10 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
 							{ type: "text" as const, text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX },
 						],
 						timestamp: m.timestamp,
+						// Stable point in the conversation — earn prompt-cache reads on the
+						// summary + kept history block on every post-compaction turn until
+						// the next compaction. (#5027)
+						cacheBreakpoint: true,
 					};
 				case "user":
 				case "assistant":

package/packages/pi-coding-agent/src/core/model-registry-auth-mode.test.ts

@@ -5,14 +5,17 @@ import { getApiProvider } from "@gsd/pi-ai";
 import { AuthStorage, type AuthStorageData } from "./auth-storage.js";
 import { ModelRegistry } from "./model-registry.js";
 
-function createRegistry(hasAuthFn?: (provider: string) => boolean): ModelRegistry {
+function createRegistry(
+	hasAuthFn?: (provider: string) => boolean,
+	getApiKeyFn?: (provider: string) => Promise<string | undefined>,
+): ModelRegistry {
 	const authStorage = {
 		setFallbackResolver: () => {},
 		onCredentialChange: () => {},
 		getOAuthProviders: () => [],
 		get: () => undefined,
 		hasAuth: hasAuthFn ?? (() => false),
-		getApiKey: async () => undefined,
+		getApiKey: async (provider: string) => getApiKeyFn ? getApiKeyFn(provider) : undefined,
 	} as unknown as AuthStorage;
 
 	return new ModelRegistry(authStorage, "");
@@ -311,6 +314,12 @@ describe("ModelRegistry authMode — isProviderRequestReady", () => {
 		const registry = createRegistry(() => true);
 		assert.equal(registry.isProviderRequestReady("anthropic"), true);
 	});
+
+	it("returns false for denylisted providers even when auth exists", () => {
+		const registry = createRegistry(() => true);
+		registry.setDisabledModelProviders(["anthropic"]);
+		assert.equal(registry.isProviderRequestReady("anthropic"), false);
+	});
 });
 
 // ─── isReady callback ─────────────────────────────────────────────────────────
@@ -414,6 +423,17 @@ describe("ModelRegistry authMode — getAvailable", () => {
 		assert.equal(available.length, 0);
 	});
 
+	it("excludes denylisted providers from available models", () => {
+		const registry = createRegistry(() => true);
+		registry.setDisabledModelProviders(["google-gemini-cli"]);
+		const available = registry.getAvailable();
+		assert.equal(
+			available.some((m) => m.provider === "google-gemini-cli"),
+			false,
+			"google-gemini-cli models must be hidden when provider is denylisted",
+		);
+	});
+
 	it("prunes Codex models removed from ChatGPT-backed openai-codex OAuth", () => {
 		const registry = createInMemoryRegistry({
 			"openai-codex": {
@@ -481,6 +501,16 @@ describe("ModelRegistry authMode — getApiKey", () => {
 		const key = await registry.getApiKeyForProvider("anthropic");
 		assert.equal(key, undefined);
 	});
+
+	it("still resolves provider keys for denylisted providers", async () => {
+		const registry = createRegistry(
+			() => true,
+			async (provider: string) => provider === "google-gemini-cli" ? "ya29.test-token" : undefined,
+		);
+		registry.setDisabledModelProviders(["google-gemini-cli"]);
+		const key = await registry.getApiKeyForProvider("google-gemini-cli");
+		assert.equal(key, "ya29.test-token");
+	});
 });
 
 // ─── streamSimple apiKey stripping ────────────────────────────────────────────

package/packages/pi-coding-agent/src/core/model-registry.ts

@@ -247,6 +247,7 @@ export class ModelRegistry {
 	private discoveryCache: ModelDiscoveryCache;
 	private customProviderApiKeys: Map<string, string> = new Map();
 	private registeredProviders: Map<string, ProviderConfigInput> = new Map();
+	private disabledModelProviders: Set<string> = new Set();
 	private loadError: string | undefined = undefined;
 
 	constructor(
@@ -553,6 +554,25 @@ export class ModelRegistry {
 		return this.models.filter((m) => this.isProviderRequestReady(m.provider));
 	}
 
+	/**
+	 * Set provider IDs that should be excluded from model selection/routing.
+	 * This does not affect direct tool auth flows that resolve provider keys.
+	 */
+	setDisabledModelProviders(providers: string[]): void {
+		this.disabledModelProviders = new Set(
+			providers
+				.map((provider) => provider.trim().toLowerCase())
+				.filter((provider) => provider.length > 0),
+		);
+	}
+
+	/**
+	 * Get current provider denylist used for model selection/routing.
+	 */
+	getDisabledModelProviders(): string[] {
+		return Array.from(this.disabledModelProviders);
+	}
+
 	/**
 	 * Get auth mode for a provider.
 	 * Defaults to "apiKey" for built-ins and providers without explicit mode.
@@ -570,6 +590,7 @@ export class ModelRegistry {
 	 * Whether a provider can be used for requests/fallback without hard auth gating.
 	 */
 	isProviderRequestReady(provider: string): boolean {
+		if (this.disabledModelProviders.has(provider.trim().toLowerCase())) return false;
 		const config = this.registeredProviders.get(provider);
 		if (config?.isReady) return config.isReady();
 		const authMode = this.getProviderAuthMode(provider);

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -55,6 +55,19 @@ export interface BuildSystemPromptOptions {
 	 * exception and the session stays consistent.
 	 */
 	skillFilter?: (skill: Skill) => boolean;
+	/**
+	 * Append a `Current date and time: <toLocaleString>` line to the system
+	 * prompt. Default: `false`.
+	 *
+	 * Anthropic prompt caching matches on byte-for-byte prefix equality.
+	 * Embedding a per-call timestamp in the system prompt invalidates the
+	 * cache on every request, forcing a full re-write that costs *more*
+	 * than an uncached call (cache-write premium). Most agentic flows do
+	 * not need wall-clock awareness in the system prompt — opt in only
+	 * when the consumer genuinely needs it (e.g. a clock-sensitive agent),
+	 * and inject it via a non-cached channel (user message) when possible.
+	 */
+	includeDateTime?: boolean;
 }
 
 /** Build the system prompt with tools, guidelines, and context */
@@ -69,20 +82,25 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		contextFiles: providedContextFiles,
 		skills: providedSkills,
 		skillFilter,
+		includeDateTime = false,
 	} = options;
 	const resolvedCwd = toPosixPath(cwd ?? process.cwd());
 
-	const now = new Date();
-	const dateTime = now.toLocaleString("en-US", {
-		weekday: "long",
-		year: "numeric",
-		month: "long",
-		day: "numeric",
-		hour: "2-digit",
-		minute: "2-digit",
-		second: "2-digit",
-		timeZoneName: "short",
-	});
+	// Per-call timestamps invalidate Anthropic prompt caching (the cache
+	// matches on byte-for-byte prefix equality). Compute lazily and only
+	// when explicitly opted in via `includeDateTime`.
+	const dateTimeLine = includeDateTime
+		? `\nCurrent date and time: ${new Date().toLocaleString("en-US", {
+			weekday: "long",
+			year: "numeric",
+			month: "long",
+			day: "numeric",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			timeZoneName: "short",
+		})}`
+		: "";
 
 	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
 
@@ -124,8 +142,8 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 			prompt += formatSkillsForPrompt(skills);
 		}
 
-		// Add date/time and working directory last
-		prompt += `\nCurrent date and time: ${dateTime}`;
+		// Add date/time (only when opted in — see includeDateTime docs) and working directory last
+		prompt += dateTimeLine;
 		prompt += `\nCurrent working directory: ${resolvedCwd}`;
 
 		// Append promptGuidelines from extension-registered tools.
@@ -272,8 +290,8 @@ Pi documentation (read only when the user asks about pi itself, its SDK, extensi
 		prompt += formatSkillsForPrompt(skills);
 	}
 
-	// Add date/time and working directory last
-	prompt += `\nCurrent date and time: ${dateTime}`;
+	// Add date/time (only when opted in — see includeDateTime docs) and working directory last
+	prompt += dateTimeLine;
 	prompt += `\nCurrent working directory: ${resolvedCwd}`;
 
 	return prompt;

package/packages/pi-coding-agent/src/core/token-telemetry.ts

@@ -0,0 +1,77 @@
+// @gsd/pi-coding-agent + token-telemetry — opt-in per-call token observability
+//
+// Emits a single JSON line per assistant message to stderr when
+// `PI_TOKEN_TELEMETRY=1` is set. Captures the cache_read_input_tokens and
+// cache_creation_input_tokens fields the providers already extract — so we
+// can empirically measure prompt-cache effectiveness (e.g. for #5019 and
+// future cache strategy work). Off by default — no behavior change.
+//
+// Capture pattern: `PI_TOKEN_TELEMETRY=1 npm start 2> token-telemetry.jsonl`
+
+import type { AssistantMessage } from "@gsd/pi-ai";
+
+/** Schema of one telemetry line. JSON-stable for downstream ingestion. */
+export interface TokenTelemetryRecord {
+	ts: number;
+	model: string;
+	stopReason: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	/**
+	 * `usage.cost.total` from the provider. `0` when the provider's cost
+	 * registry has no rates for this model (e.g. unknown third-party providers)
+	 * — distinguish from a true zero-cost call by checking your model registry.
+	 */
+	costTotal: number;
+	/**
+	 * Fraction of new prompt tokens served from cache:
+	 * `cacheRead / (cacheRead + input)`. Range [0, 1].
+	 * - `0` when neither cacheRead nor input is present (no division by zero).
+	 * - `1` on a full cache hit (input = 0, cacheRead > 0).
+	 * Note: `input` here is `input_tokens` from the API, which already excludes
+	 * cache reads/writes — the denominator is total prompt tokens consumed.
+	 */
+	cacheHitRatio: number;
+}
+
+/** Build a telemetry record from a finished assistant message. */
+export function buildTokenTelemetryRecord(msg: AssistantMessage): TokenTelemetryRecord {
+	const input = msg.usage?.input ?? 0;
+	const output = msg.usage?.output ?? 0;
+	const cacheRead = msg.usage?.cacheRead ?? 0;
+	const cacheWrite = msg.usage?.cacheWrite ?? 0;
+	const costTotal = msg.usage?.cost?.total ?? 0;
+	const denom = cacheRead + input;
+	const cacheHitRatio = denom > 0 ? cacheRead / denom : 0;
+
+	return {
+		ts: msg.timestamp,
+		model: msg.model,
+		stopReason: msg.stopReason,
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		costTotal,
+		cacheHitRatio,
+	};
+}
+
+/**
+ * Emit a token-telemetry line if `PI_TOKEN_TELEMETRY=1`. No-op otherwise.
+ *
+ * Writes to stderr so it doesn't interfere with TUI/stdout. One JSON object
+ * per line. Errors during emission are swallowed — telemetry must never
+ * break the agent loop.
+ */
+export function emitTokenTelemetry(msg: AssistantMessage): void {
+	if (process.env.PI_TOKEN_TELEMETRY !== "1") return;
+	try {
+		const record = buildTokenTelemetryRecord(msg);
+		process.stderr.write(`${JSON.stringify(record)}\n`);
+	} catch {
+		// Telemetry must never break the agent loop. Swallow.
+	}
+}