@sayknow-cli/coding-agent 0.3.12 → 0.3.15

package/src/session/cache-economics.ts

@@ -0,0 +1,275 @@
+import type { Usage } from "@sayknow-cli/ai";
+
+const TOKENS_PER_MILLION = 1_000_000;
+const MATERIAL_COST_USD = 0.01;
+const MATERIAL_CACHE_TOKENS = 10_000;
+const EXPENSIVE_MISS_COST_USD = 0.05;
+const LARGE_INPUT_TOKENS = 20_000;
+const LARGE_CACHE_WRITE_TOKENS = 25_000;
+const TRANSCRIPT_WARNING_CAP = 3;
+
+export interface CacheEconomicsPricing {
+	input: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+export interface CacheEconomicsModelCost extends CacheEconomicsPricing {
+	output: number;
+}
+
+export type CacheEconomicsBasis =
+	| { kind: "persisted-aggregate"; costBreakdown: Usage["cost"] }
+	| { kind: "current-model-estimate"; pricing: CacheEconomicsPricing };
+
+export interface CacheEconomicsUsage {
+	input: number;
+	output?: number;
+	cacheRead: number;
+	cacheWrite: number;
+	total?: number;
+	cost?: {
+		input?: number;
+		output?: number;
+		cacheRead?: number;
+		cacheWrite?: number;
+		total?: number;
+	};
+}
+
+export interface CacheMissCostSummary {
+	inputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	inputCostUsd: number;
+	cacheReadCostUsd: number;
+	cacheWriteCostUsd: number;
+	cacheHitRate: number | undefined;
+	missPremiumUsd: number | undefined;
+}
+
+/**
+ * How a detected cache-miss pattern is attributed, per issue #2020.
+ *
+ * - `actionable`: usage evidence points to a user-controllable cause and SKC
+ *   has a concrete remediation.
+ * - `diagnostic-only`: a miss pattern is observed but the cause is not
+ *   determinable from usage alone; describe what is unknown, assert no cause.
+ * - `provider-side-suspected`: the provider returned no cache activity, so the
+ *   miss cannot be attributed to the user's prompt; not user-actionable.
+ */
+export type CacheMissAttribution = "actionable" | "diagnostic-only" | "provider-side-suspected";
+
+export interface CacheBehaviorWarning {
+	code: "expensive_cache_miss" | "cache_write_spike" | "provider_side_cache_miss";
+	attribution: CacheMissAttribution;
+	reason: string;
+	/** Concrete remediation — present only when `attribution` is `actionable`. */
+	nextStep?: string;
+	/** What SKC cannot determine — present for non-actionable attributions. */
+	unknown?: string;
+	costUsd: number;
+}
+
+export interface CacheWarningBuildState {
+	warningsEmitted: number;
+}
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function positiveFinite(value: number | undefined): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function currentModelBucketCost(
+	tokens: number,
+	persistedCostUsd: number | undefined,
+	pricePerMillionTokens: number | undefined,
+): number | undefined {
+	if (persistedCostUsd !== undefined) {
+		return finiteNonNegative(persistedCostUsd) ? persistedCostUsd : undefined;
+	}
+	if (!positiveFinite(tokens) || !positiveFinite(pricePerMillionTokens)) return 0;
+	return (tokens / TOKENS_PER_MILLION) * pricePerMillionTokens;
+}
+
+function persistedAggregateCosts(costBreakdown: Usage["cost"] | undefined): [number, number, number] | undefined {
+	if (!costBreakdown) return undefined;
+	const { input, cacheRead, cacheWrite, output, total } = costBreakdown;
+	if (![input, cacheRead, cacheWrite, output, total].every(finiteNonNegative)) return undefined;
+	return [input, cacheRead, cacheWrite];
+}
+
+function hasMaterialEvidence(usage: CacheEconomicsUsage, costs: readonly number[]): boolean {
+	const tokenEvidence = usage.input + usage.cacheRead + usage.cacheWrite >= MATERIAL_CACHE_TOKENS;
+	const costEvidence = costs.some(cost => cost >= MATERIAL_COST_USD);
+	return tokenEvidence || costEvidence;
+}
+
+export function computeCacheMissCostSummary(
+	usage: CacheEconomicsUsage | undefined,
+	basis: CacheEconomicsBasis,
+): CacheMissCostSummary | undefined {
+	if (!usage) return undefined;
+
+	const costs =
+		basis.kind === "persisted-aggregate"
+			? persistedAggregateCosts(basis.costBreakdown)
+			: [
+					currentModelBucketCost(usage.input, usage.cost?.input, basis.pricing.input),
+					currentModelBucketCost(usage.cacheRead, usage.cost?.cacheRead, basis.pricing.cacheRead),
+					currentModelBucketCost(usage.cacheWrite, usage.cost?.cacheWrite, basis.pricing.cacheWrite),
+				];
+	if (!costs) return undefined;
+	const [inputCostUsd, cacheReadCostUsd, cacheWriteCostUsd] = costs;
+	if (inputCostUsd === undefined || cacheReadCostUsd === undefined || cacheWriteCostUsd === undefined)
+		return undefined;
+	if (usage.input <= 0 && cacheWriteCostUsd <= 0) return undefined;
+	if (!hasMaterialEvidence(usage, [inputCostUsd, cacheReadCostUsd, cacheWriteCostUsd])) return undefined;
+	if (inputCostUsd <= 0 && cacheWriteCostUsd <= 0) return undefined;
+
+	const totalReusableInput = usage.input + usage.cacheRead;
+	const cacheHitRate = totalReusableInput > 0 ? usage.cacheRead / totalReusableInput : undefined;
+	const missPremiumUsd =
+		basis.kind === "current-model-estimate" &&
+		positiveFinite(basis.pricing.input) &&
+		positiveFinite(basis.pricing.cacheRead) &&
+		basis.pricing.input > basis.pricing.cacheRead &&
+		usage.input > 0
+			? ((basis.pricing.input - basis.pricing.cacheRead) * usage.input) / TOKENS_PER_MILLION
+			: undefined;
+
+	return {
+		inputTokens: usage.input,
+		cacheReadTokens: usage.cacheRead,
+		cacheWriteTokens: usage.cacheWrite,
+		inputCostUsd,
+		cacheReadCostUsd,
+		cacheWriteCostUsd,
+		cacheHitRate,
+		missPremiumUsd: positiveFinite(missPremiumUsd) ? missPremiumUsd : undefined,
+	};
+}
+
+function formatUsd(cost: number): string {
+	return cost < 0.01 ? `$${cost.toFixed(4)}` : `$${cost.toFixed(2)}`;
+}
+
+function formatPercent(value: number): string {
+	return `${(value * 100).toFixed(1)}%`;
+}
+
+export function formatCacheMissSummaryLines(summary: CacheMissCostSummary): string[] {
+	const lines = [`Uncached Input Cost: ${formatUsd(summary.inputCostUsd)}`];
+	if (summary.missPremiumUsd !== undefined) {
+		lines.push(`Estimated Miss Premium: ${formatUsd(summary.missPremiumUsd)} vs cache-read pricing`);
+	}
+	if (summary.cacheHitRate !== undefined) {
+		lines.push(`Cache Hit Rate: ${formatPercent(summary.cacheHitRate)}`);
+	}
+	if (summary.cacheWriteCostUsd >= MATERIAL_COST_USD) {
+		lines.push(`Cache Write Cost: ${formatUsd(summary.cacheWriteCostUsd)}`);
+	}
+	return lines;
+}
+
+export function buildCacheBehaviorWarning(
+	usage: Usage | undefined,
+	model: { cost: CacheEconomicsModelCost } | undefined | null,
+): CacheBehaviorWarning | undefined {
+	const summary = model
+		? computeCacheMissCostSummary(usage, { kind: "current-model-estimate", pricing: model.cost })
+		: undefined;
+	if (!summary) return undefined;
+	if (
+		summary.inputTokens >= LARGE_INPUT_TOKENS &&
+		(summary.cacheHitRate === undefined || summary.cacheHitRate < 0.25) &&
+		summary.inputCostUsd >= EXPENSIVE_MISS_COST_USD
+	) {
+		// Attribute by observable cache activity rather than asserting a cause (#2020).
+		const noCacheActivity = summary.cacheReadTokens <= 0 && summary.cacheWriteTokens <= 0;
+		if (noCacheActivity) {
+			// The provider returned zero cache read/write tokens for a large, costly
+			// prompt: the miss cannot be traced to the user's prefix, and keeping a
+			// stable prefix cannot help when nothing is being cached at all.
+			return {
+				code: "provider_side_cache_miss",
+				attribution: "provider-side-suspected",
+				reason: `large uncached input with no cache activity (${formatUsd(summary.inputCostUsd)})`,
+				unknown:
+					"the provider reported no cache reads or writes, so SKC cannot tell whether prompt caching is unsupported, missing cache-control fields, or provider-side eviction",
+				costUsd: summary.inputCostUsd,
+			};
+		}
+		if (summary.cacheWriteTokens > 0) {
+			// Writes are landing but reuse is low: the cacheable prefix is churning
+			// between turns, which is user-controllable.
+			return {
+				code: "expensive_cache_miss",
+				attribution: "actionable",
+				reason: `large uncached input with low cache reuse (${formatUsd(summary.inputCostUsd)})`,
+				nextStep: "keep the stable prefix; avoid rereading unchanged context before the next turn",
+				costUsd: summary.inputCostUsd,
+			};
+		}
+		// Reads happened but no writes this turn: part of the prefix was reused, yet
+		// the large new input was not cached. From usage alone SKC cannot tell new
+		// content apart from a provider-side gap, so it reports without asserting.
+		return {
+			code: "expensive_cache_miss",
+			attribution: "diagnostic-only",
+			reason: `large uncached input with partial cache reuse (${formatUsd(summary.inputCostUsd)})`,
+			unknown:
+				"the uncached tokens may be genuinely new content or a provider-side gap; usage alone cannot attribute a single cause",
+			costUsd: summary.inputCostUsd,
+		};
+	}
+	if (
+		summary.cacheWriteTokens >= LARGE_CACHE_WRITE_TOKENS &&
+		summary.cacheWriteCostUsd >= EXPENSIVE_MISS_COST_USD &&
+		// Only claim reuse is insufficient when reads actually fail to cover the
+		// writes; a large write that is being read back is healthy, not a spike.
+		summary.cacheReadTokens < summary.cacheWriteTokens
+	) {
+		return {
+			code: "cache_write_spike",
+			attribution: "actionable",
+			reason: `large cache write without enough matching reads (${formatUsd(summary.cacheWriteCostUsd)})`,
+			nextStep: "make the next turn reuse the same context; avoid changing system or tool prefixes",
+			costUsd: summary.cacheWriteCostUsd,
+		};
+	}
+	return undefined;
+}
+
+/**
+ * Render a cache warning as a single transcript line. Actionable attributions
+ * carry a concrete next step; non-actionable ones state what is unknown and,
+ * for provider-side patterns, that the miss is not user-actionable — never
+ * asserting a cause or blaming the provider (#2020).
+ */
+export function formatCacheWarningLine(warning: CacheBehaviorWarning): string {
+	if (warning.attribution === "actionable" && warning.nextStep) {
+		return `Cache warning: ${warning.reason}; next step: ${warning.nextStep}.`;
+	}
+	if (warning.attribution === "provider-side-suspected") {
+		const detail = warning.unknown ? ` — ${warning.unknown}` : "";
+		return `Cache notice: ${warning.reason}; provider-side suspected / not user-actionable${detail}.`;
+	}
+	const detail = warning.unknown ? `; ${warning.unknown}` : "";
+	return `Cache notice: ${warning.reason}${detail}.`;
+}
+
+export function buildCacheEconomicsWarning(
+	usage: Usage | undefined,
+	model: { cost: CacheEconomicsModelCost } | undefined | null,
+	state: CacheWarningBuildState,
+): string | undefined {
+	if (state.warningsEmitted >= TRANSCRIPT_WARNING_CAP) return undefined;
+	const warning = buildCacheBehaviorWarning(usage, model);
+	if (!warning) return undefined;
+	state.warningsEmitted += 1;
+	return formatCacheWarningLine(warning);
+}

package/src/session/context-estimation.ts

@@ -0,0 +1,91 @@
+/**
+ * Session-neutral fixed-context (non-message) token estimation.
+ *
+ * Lives in the session layer so load-bearing session/compaction behavior
+ * (`AgentSession` context estimates) never depends on a presentation module.
+ * UI surfaces (`modes/utils/context-usage.ts`, status line) import from here
+ * as well, so every surface reports the same numbers.
+ */
+import { estimateTextTokensHeuristic } from "@sayknow-cli/agent-core/compaction";
+import type { Skill } from "../extensibility/skills";
+import type { Tool } from "../tools";
+import type { AgentSession } from "./agent-session";
+
+export function estimateSkillsTokens(skills: readonly Skill[]): number {
+	const fragments: string[] = [];
+	for (const skill of skills) {
+		// "- name: description\n" wire framing tokenizes ~identically to the
+		// concatenated form, so encode each piece separately and sum.
+		fragments.push(skill.name, skill.description);
+	}
+	return estimateTextTokensHeuristic(fragments);
+}
+
+export function estimateToolSchemaTokens(
+	tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>,
+): number {
+	const fragments: string[] = [];
+	for (const tool of tools) {
+		fragments.push(tool.name, tool.description);
+		try {
+			fragments.push(JSON.stringify(tool.parameters ?? {}));
+		} catch {
+			// Schema may contain functions or cycles; ignore.
+		}
+	}
+	return estimateTextTokensHeuristic(fragments);
+}
+
+/**
+ * Compute just the NON-MESSAGE token total: system prompt (with its skills
+ * section subtracted, since skills are tokenized separately) + system context
+ * (the rest of the system-prompt array) + tools + skills.
+ *
+ * Exposed so callers like `StatusLineComponent` can cache the non-message
+ * total separately from the message total. Non-message inputs (skills,
+ * tools, system prompt) change rarely; the message list grows on every
+ * streaming turn. Splitting the two lets the caller refresh each on its own
+ * cadence — non-message recomputed only when the inputs identity changes,
+ * messages walked incrementally as new entries append.
+ */
+export function computeNonMessageTokens(session: AgentSession): number {
+	const parts = computeNonMessageBreakdown(session);
+	return (
+		parts.systemPromptTokens + parts.systemContextTokens + parts.rulesTokens + parts.toolsTokens + parts.skillsTokens
+	);
+}
+
+/**
+ * Shared helper for the four non-message token totals. Single source of truth
+ * for `computeNonMessageTokens` (session estimates + status-line incremental
+ * cache) and `computeContextBreakdown` (/context panel). The split avoids
+ * drift between the surfaces — they MUST report the same numbers.
+ */
+export function computeNonMessageBreakdown(session: AgentSession): {
+	rulesTokens: number;
+	skillsTokens: number;
+	toolsTokens: number;
+	systemContextTokens: number;
+	systemPromptTokens: number;
+} {
+	const skillsTokens = estimateSkillsTokens(session.skills ?? []);
+	const toolsTokens = estimateToolSchemaTokens(session.agent?.state?.tools ?? []);
+	const systemPromptParts = session.systemPrompt ?? [];
+	const rulesTokens = estimateRulesTokens(systemPromptParts);
+	const systemContextTokens = estimateTextTokensHeuristic(systemPromptParts.slice(1));
+	const systemPromptTokens = Math.max(
+		0,
+		estimateTextTokensHeuristic(systemPromptParts[0] ?? "") - skillsTokens - rulesTokens,
+	);
+	return { rulesTokens, skillsTokens, toolsTokens, systemContextTokens, systemPromptTokens };
+}
+
+function estimateRulesTokens(systemPromptParts: readonly string[]): number {
+	const fragments: string[] = [];
+	for (const part of systemPromptParts) {
+		for (const match of part.matchAll(/<rules>[\s\S]*?<\/rules>/g)) {
+			fragments.push(match[0]);
+		}
+	}
+	return fragments.length === 0 ? 0 : estimateTextTokensHeuristic(fragments);
+}

package/src/session/provider-safety-stop.ts

@@ -0,0 +1,9 @@
+/**
+ * Recognizes legacy provider safety-stop labels persisted before `errorKind`.
+ * Keep this anchored and conservative so incidental transient-error prose stays retryable.
+ */
+export function isLegacyProviderSafetyStopMessage(errorMessage: string): boolean {
+	return /^(?:refusal(?: \([^()\s\r\n](?:[^()\r\n]*[^()\s\r\n])?\))?(?:: \S(?:[^\r\n]*\S)?)?|content flagged by safety filters|blocked under anthropic's usage policy\.|provider finish_reason: content_filter)[ \t]*(?![\s\S])/i.test(
+		errorMessage,
+	);
+}

package/src/session/session-dump-format.ts

@@ -4,6 +4,7 @@
 import type { AgentMessage, ThinkingLevel } from "@sayknow-cli/agent-core";
 import { INTENT_FIELD } from "@sayknow-cli/agent-core";
 import type { AssistantMessage, Model } from "@sayknow-cli/ai";
+import { buildCacheEconomicsWarning, type CacheWarningBuildState } from "./cache-economics";
 import {
 	type BashExecutionMessage,
 	type BranchSummaryMessage,
@@ -137,6 +138,7 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 		lines.push("\n");
 	}
 
+	const cacheWarningState: CacheWarningBuildState = { warningsEmitted: 0 };
 	for (const msg of options.messages) {
 		if (msg.role === "user" || msg.role === "developer") {
 			lines.push(msg.role === "developer" ? "## Developer\n" : "## User\n");
@@ -172,6 +174,10 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 					lines.push("<" + "/invoke>\n");
 				}
 			}
+			const cacheWarning = buildCacheEconomicsWarning(assistantMsg.usage, model, cacheWarningState);
+			if (cacheWarning) {
+				lines.push(cacheWarning);
+			}
 			lines.push("");
 		} else if (msg.role === "toolResult") {
 			lines.push(`### Tool Result: ${msg.toolName}`);