@danypops/jittor 0.3.0 → 0.5.0

package/README.md

@@ -31,7 +31,7 @@ The initial service scaffold is split into domain, ports, and adapters:
 
 SQLite runs in WAL mode with versioned migrations, JSON validation, bounded queries, chronological indexes, pruning, and checkpoints. The database follows `XDG_DATA_HOME`; private authentication state follows `XDG_STATE_HOME`; the daemon handle follows `XDG_RUNTIME_DIR`.
 
-Operations currently include `metrics.record`, `metrics.query`, `metrics.prune`, and `service.checkpoint`.
+Operations currently include `metrics.record`, `metrics.query`, `metrics.prune`, `context.assess`, and `service.checkpoint`.
 
 Provider adapters currently include official OpenRouter key/usage/model telemetry and an explicitly experimental Codex subscription adapter. The Codex adapter follows the pinned open-source CLI `/wham/usage` payload and `x-codex-*` response-header contracts, accepts additional metered limits, and fails closed on malformed windows or impossible percentages. File credentials must be explicitly configured and private (`0600`); Jittor reads only the access token and account ID, never refreshes credentials, and never logs or persists OAuth secrets.
 
@@ -54,10 +54,22 @@ The on/off choice persists privately in `$XDG_CONFIG_HOME/jittor/extension.json`
 
 Jittor observes finalized Codex assistant errors through Pi's public message lifecycle, classifies only bounded error metadata, and waits for `agent_settled` before acting. That boundary guarantees Pi's built-in retry, compaction retry, and queued follow-up work has finished. A transient concurrency, rate-limit, overload, or transport failure then schedules one hidden follow-up with Retry-After-aware capped jitter. Recovery is limited to three attempts per ten-minute window, never overlaps pending Pi messages, resets after success, and is canceled by human input or session shutdown. Quota, authentication, invalid-request, unknown, and aborted failures remain terminal. Raw provider payloads are never retained or injected.
 
+### Settings
+
+Run `/jittor settings` for one keyboard-navigable TUI covering routing enforcement, the informational footer, Codex recovery, and all four token-budget thresholds. It uses explicit ON/OFF and configured/not-configured labels, remains bounded on narrow terminals, confirms weaker enforcement and recovery changes, and applies enforcement enablement through the same readiness checks as `/jittor on`. Existing non-TUI commands remain available for automation.
+
+### Usage graphs
+
 Run `/jittor usage` for a colored Unicode cumulative token graph with X/Y axes, provider/model series, input/output/cache totals, refresh, and explicit **Hourly**, **Daily**, **Weekly**, and **Monthly** periods. Left/Right changes period and `r` refreshes. Usage is persisted by the daemon from finalized Pi assistant messages.
 
 Token-budget thresholds are optional and must be configured by the user; Jittor never infers a token allowance from Codex or another provider's subscription percentage. Configure or clear one period with `/jittor usage budget <hourly|daily|weekly|monthly> <positive-tokens|off>`, and inspect all four with `/jittor usage budget`. A configured budget appears as a horizontal threshold on the cumulative graph with explicit remaining or **OVER BUDGET** state. These private settings persist in `$XDG_CONFIG_HOME/jittor/extension.json` (or `~/.config/jittor/extension.json`).
 
+### Context pressure
+
+Papyrus emits content-free prompt-injection observations through Pi's shared extension event bus. Jittor validates and records their exact Rule/Task character sizes, prompt share, fingerprint repetition, and explicitly estimated token size. Jittor also records completed, aborted, and unmatched Pi compactions with duration, reason, retry state, pre-compaction context usage, and bounded turns/injection/provider/cache usage since the previous compaction.
+
+Run `/jittor context` for the in-session summary, or `jittor context [--since <epoch-ms>] [--until <epoch-ms>] [--json]` through the authenticated daemon client. The assessment reports bounded average/p95/max injection, Rule/Task mix, unchanged rate, compaction frequency/duration/reasons, and between-compaction provider/cache facts. Repeated prompt content is not labeled billed waste: provider-reported input/cache usage and an injection-disabled control are required before making cost or compaction-causality claims.
+
 See [`docs/CALIBRATION.md`](docs/CALIBRATION.md) for thresholds and rollback, and [`docs/USAGE_PRIOR_ART.md`](docs/USAGE_PRIOR_ART.md) for the chart design research.
 
 ```bash

package/extension/src/index.ts

@@ -9,8 +9,11 @@ import {
 	MAX_DYNAMIC_ROUTES,
 	MILLISECONDS_PER_MINUTE,
 	MILLISECONDS_PER_SECOND,
+	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
+	CONTEXT_EVENT_DEDUP_LIMIT,
 } from "../../src/constants.ts";
 import { CodexRecoveryPolicy, classifyCodexFailure, type CodexFailureKind, type CodexFailureMetadata } from "../../src/domain/codex-recovery.ts";
+import { CompactionTelemetry, papyrusContextMetric, validatePapyrusContextInjection } from "../../src/domain/context-telemetry.ts";
 import type { MetricObservation, StoredMetricObservation } from "../../src/domain/metric.ts";
 import { USAGE_PERIODS, type UsagePeriod } from "../../src/domain/usage.ts";
 import type { PolicyDecision, Route } from "../../src/policy.ts";
@@ -19,6 +22,7 @@ import { parseCodexRateLimitHeaders } from "../../src/providers/codex.ts";
 import { installIntegratedFooter, type IntegratedFooterState } from "./footer.ts";
 import { callJittor } from "./service-client.ts";
 import { persistentEnforcementControl, type CodexRecoveryControl, type EnforcementControl, type UsageBudgetControl } from "./settings.ts";
+import { showSettingsPanel } from "./settings-tui.ts";
 import { buildFooterBudget, formatFooterStatus, showJittorPanel } from "./tui.ts";
 import { showUsagePanel } from "./usage.ts";
 
@@ -226,6 +230,21 @@ export function registerJittorExtension(
 ): void {
 	const footerState: IntegratedFooterState = { providerBudget: null };
 	const usageBudgets = usageBudgetControl(enforcement);
+	let compactionTelemetry = new CompactionTelemetry();
+	const contextObservations = new Set<string>();
+	const stopPapyrusContext = pi.events?.on?.(PAPYRUS_CONTEXT_INJECTION_CHANNEL, (payload) => {
+		try {
+			const observation = validatePapyrusContextInjection(payload);
+			const observationKey = `${observation.producerId}:${observation.sequence}`;
+			if (contextObservations.has(observationKey)) return;
+			contextObservations.add(observationKey);
+			if (contextObservations.size > CONTEXT_EVENT_DEDUP_LIMIT) contextObservations.delete(contextObservations.values().next().value!);
+			compactionTelemetry.observeInjection(observation.injected.characters, observation.estimatedTokens);
+			void recordMetrics(client, [papyrusContextMetric(observation)]).catch(() => undefined);
+		} catch {
+			// Reject malformed or stale cross-extension observations without retaining payloads.
+		}
+	});
 	const recoveryPolicy = new CodexRecoveryPolicy({
 		baseDelayMs: CODEX_RECOVERY_BASE_DELAY_MS,
 		maxDelayMs: CODEX_RECOVERY_MAX_DELAY_MS,
@@ -286,22 +305,22 @@ export function registerJittorExtension(
 		}, plan.delayMs);
 	};
 	let compactionTimer: ReturnType<typeof setInterval> | undefined;
-	const finishCompaction = (): void => {
+	const finishCompactionUi = (): void => {
 		if (compactionTimer) clearInterval(compactionTimer);
 		compactionTimer = undefined;
 		footerState.compaction = undefined;
 		footerState.requestRender?.();
 	};
-	const beginCompaction = (ctx: ExtensionContext, signal: AbortSignal): void => {
-		finishCompaction();
+	const beginCompactionUi = (ctx: ExtensionContext, signal: AbortSignal): void => {
+		finishCompactionUi();
 		const usage = ctx.getContextUsage();
 		footerState.compaction = {
 			startedAt: Date.now(),
 			initialFraction: usage?.percent === null || usage?.percent === undefined ? 1 : usage.percent / 100,
 		};
 		compactionTimer = setInterval(() => footerState.requestRender?.(), FOOTER_COMPACTION_RENDER_INTERVAL_MS);
-		signal.addEventListener("abort", finishCompaction, { once: true });
-		if (signal.aborted) finishCompaction();
+		signal.addEventListener("abort", finishCompactionUi, { once: true });
+		if (signal.aborted) finishCompactionUi();
 		else footerState.requestRender?.();
 	};
 	const showFooter = (ctx: ExtensionContext): void => {
@@ -372,6 +391,33 @@ export function registerJittorExtension(
 				ctx.ui.notify("Jittor informational footer enabled; routing enforcement is unchanged.", "info");
 				return;
 			}
+			if (action === "context") {
+				const summary = await client.call("context.assess", {}) as import("../../src/domain/context-telemetry.ts").ContextAssessment;
+				const average = summary.injection.averageCharacters === null ? "unknown" : Math.round(summary.injection.averageCharacters).toLocaleString();
+				const p95 = summary.injection.p95Characters === null ? "unknown" : Math.round(summary.injection.p95Characters).toLocaleString();
+				ctx.ui.notify([
+					`Papyrus injection: ${summary.injection.runs} runs · avg ${average} chars · p95 ${p95} chars · unchanged ${summary.injection.unchangedRate === null ? "unknown" : `${(summary.injection.unchangedRate * 100).toFixed(1)}%`}`,
+					`Mix: rules ${summary.injection.ruleCharacters.toLocaleString()} chars · tasks ${summary.injection.taskCharacters.toLocaleString()} chars · estimated ${summary.injection.estimatedTokens.toLocaleString()} tokens`,
+					`Compactions: ${summary.compaction.completed} completed · ${summary.compaction.aborted} aborted · ${summary.compaction.perRun === null ? "unknown" : summary.compaction.perRun.toFixed(3)} per agent run · ${summary.compaction.perTurn === null ? "unknown" : summary.compaction.perTurn.toFixed(3)} per turn`,
+					`Completeness: ${summary.completeness}`,
+				].join("\n"), "info");
+				return;
+			}
+			if (action === "settings") {
+				await showSettingsPanel(ctx, enforcement, codexRecovery, usageBudgets, {
+					setEnforcement: async (enabled) => enabled ? enable(ctx) : disable(ctx),
+					setFooter: async (enabled) => {
+						enforcement.setFooterEnabled(enabled);
+						showFooter(ctx);
+						if (enabled) await refreshFooter(client, footerState).catch(() => undefined);
+					},
+					setRecovery: (enabled) => {
+						if (!enabled) cancelRecovery(true);
+						codexRecovery.setCodexRecoveryEnabled(enabled);
+					},
+				});
+				return;
+			}
 			if (action === "usage budget" || action.startsWith("usage budget ")) {
 				const [, , periodText, valueText] = action.split(/\s+/);
 				const period = USAGE_PERIODS.some((candidate) => candidate.id === periodText) ? periodText as UsagePeriod : undefined;
@@ -411,7 +457,8 @@ export function registerJittorExtension(
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
-		finishCompaction();
+		finishCompactionUi();
+		compactionTelemetry = new CompactionTelemetry();
 		cancelRecovery(true);
 		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);
@@ -427,16 +474,28 @@ export function registerJittorExtension(
 		}
 	});
 
-	pi.on("session_before_compact", (event, ctx) => {
-		beginCompaction(ctx, event.signal);
+	pi.on("session_before_compact", async (event, ctx) => {
+		beginCompactionUi(ctx, event.signal);
+		const usage = ctx.getContextUsage();
+		const metric = compactionTelemetry.begin({
+			reason: event.reason,
+			willRetry: event.willRetry,
+			...(usage?.percent === null || usage?.percent === undefined ? {} : { contextPercent: usage.percent }),
+			...(usage?.tokens === null || usage?.tokens === undefined ? {} : { contextTokens: usage.tokens }),
+		});
+		await recordMetrics(client, [metric]).catch(() => undefined);
 	});
 
-	pi.on("session_compact", () => {
-		finishCompaction();
+	pi.on("session_compact", async (event) => {
+		finishCompactionUi();
+		await recordMetrics(client, [compactionTelemetry.complete({ reason: event.reason, willRetry: event.willRetry })]).catch(() => undefined);
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {
-		if (footerState.compaction) finishCompaction();
+		if (footerState.compaction) {
+			finishCompactionUi();
+			if (compactionTelemetry.hasOpenCompaction()) await recordMetrics(client, [compactionTelemetry.abort(Date.now(), "agent-settled-without-completion")]).catch(() => undefined);
+		}
 		scheduleCodexRecovery(ctx);
 		if (!enforcement.isFooterEnabled()) return;
 		try {
@@ -475,6 +534,7 @@ export function registerJittorExtension(
 	});
 
 	pi.on("turn_start", async (_event, ctx) => {
+		compactionTelemetry.observeTurn();
 		lastCodexResponse = {};
 		if (!enforcement.isEnabled()) return;
 		try {
@@ -513,12 +573,18 @@ export function registerJittorExtension(
 			lastCodexResponse = {};
 		}
 		const metrics = assistantUsageMetrics(event.message, Date.now());
-		if (metrics.length > 0) await recordMetrics(client, metrics).catch(() => undefined);
+		if (metrics.length > 0) {
+			const amount = (name: string): number => metrics.filter((metric) => metric.metric === name && typeof metric.value === "number").reduce((sum, metric) => sum + (metric.value ?? 0), 0);
+			compactionTelemetry.observeProviderUsage({ input: amount("input-tokens"), output: amount("output-tokens"), cacheRead: amount("cache-read-tokens"), cacheWrite: amount("cache-write-tokens") });
+			await recordMetrics(client, metrics).catch(() => undefined);
+		}
 		if (enforcement.isFooterEnabled()) await refreshFooter(client, footerState).catch(() => undefined);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
-		finishCompaction();
+		finishCompactionUi();
+		if (compactionTelemetry.hasOpenCompaction()) await recordMetrics(client, [compactionTelemetry.abort(Date.now(), "session-shutdown")]).catch(() => undefined);
+		stopPapyrusContext?.();
 		cancelRecovery(true);
 		lastCodexResponse = {};
 		ctx.ui.setStatus("jittor", undefined);

package/extension/src/settings-tui.ts

@@ -0,0 +1,153 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { USAGE_PERIODS, type UsagePeriod } from "../../src/domain/usage.ts";
+import type { CodexRecoveryControl, EnforcementControl, UsageBudgetControl } from "./settings.ts";
+
+export interface SettingsSnapshot {
+	enforcementEnabled: boolean;
+	footerEnabled: boolean;
+	codexRecoveryEnabled: boolean;
+	usageTokenBudgets: Partial<Record<UsagePeriod, number>>;
+}
+
+interface SettingsTheme {
+	fg(color: "accent" | "success" | "warning" | "error" | "muted" | "dim" | "borderMuted", text: string): string;
+	bold(text: string): string;
+}
+
+type SettingsKey = "enforcement" | "footer" | "recovery" | `budget-${UsagePeriod}`;
+type SettingsAction = { kind: "activate"; key: SettingsKey } | { kind: "close" };
+
+export interface SettingsEffects {
+	setEnforcement(enabled: boolean): void | Promise<void>;
+	setFooter(enabled: boolean): void | Promise<void>;
+	setRecovery(enabled: boolean): void | Promise<void>;
+}
+
+const SETTINGS_KEYS: SettingsKey[] = [
+	"enforcement",
+	"footer",
+	"recovery",
+	...USAGE_PERIODS.map(({ id }) => `budget-${id}` as const),
+];
+
+function state(enabled: boolean, theme: SettingsTheme): string {
+	return enabled ? theme.fg("success", "ON") : theme.fg("muted", "OFF");
+}
+
+function budgetLabel(period: UsagePeriod, snapshot: SettingsSnapshot): string {
+	const value = snapshot.usageTokenBudgets[period];
+	return value === undefined ? "not configured" : `${value.toLocaleString()} tokens`;
+}
+
+function rowText(key: SettingsKey, snapshot: SettingsSnapshot, theme: SettingsTheme): string {
+	if (key === "enforcement") return `Routing enforcement  ${state(snapshot.enforcementEnabled, theme)}`;
+	if (key === "footer") return `Informational footer  ${state(snapshot.footerEnabled, theme)}`;
+	if (key === "recovery") return `Codex recovery  ${state(snapshot.codexRecoveryEnabled, theme)}`;
+	const period = key.slice("budget-".length) as UsagePeriod;
+	return `${USAGE_PERIODS.find((candidate) => candidate.id === period)!.label} token budget  ${budgetLabel(period, snapshot)}`;
+}
+
+export function settingsSnapshot(
+	enforcement: EnforcementControl,
+	recovery: CodexRecoveryControl,
+	budgets: UsageBudgetControl,
+): SettingsSnapshot {
+	return {
+		enforcementEnabled: enforcement.isEnabled(),
+		footerEnabled: enforcement.isFooterEnabled(),
+		codexRecoveryEnabled: recovery.isCodexRecoveryEnabled(),
+		usageTokenBudgets: Object.fromEntries(USAGE_PERIODS.map(({ id }) => [id, budgets.getUsageTokenBudget(id)])),
+	};
+}
+
+export function renderSettingsView(snapshot: SettingsSnapshot, selected: number, width: number, theme: SettingsTheme): string[] {
+	const safeWidth = Math.max(20, width);
+	const lines = [
+		theme.bold("Jittor Settings"),
+		theme.fg("dim", "Token budgets are user values; provider quotas remain separate."),
+		"",
+	];
+	for (let index = 0; index < SETTINGS_KEYS.length; index += 1) {
+		const selectedRow = index === selected;
+		const prefix = selectedRow ? theme.fg("accent", "› ") : "  ";
+		lines.push(`${prefix}${rowText(SETTINGS_KEYS[index]!, snapshot, theme)}`);
+	}
+	lines.push("", theme.fg("dim", "↑/↓ select · Enter edit · Esc close"));
+	return lines.map((line) => visibleWidth(line) <= safeWidth ? line : truncateToWidth(line, safeWidth, "…"));
+}
+
+function plainTheme(): SettingsTheme {
+	return { fg: (_color, text) => text, bold: (text) => text };
+}
+
+async function editBudget(ctx: ExtensionCommandContext, budgets: UsageBudgetControl, period: UsagePeriod): Promise<void> {
+	const label = USAGE_PERIODS.find((candidate) => candidate.id === period)!.label;
+	const current = budgets.getUsageTokenBudget(period);
+	const input = await ctx.ui.input(`${label} token budget`, current?.toLocaleString() ?? "positive token count or off");
+	if (input === undefined) return;
+	const normalized = input.trim().toLowerCase();
+	if (normalized === "off" || normalized === "clear") {
+		budgets.setUsageTokenBudget(period, undefined);
+		ctx.ui.notify(`${label} token budget cleared.`, "info");
+		return;
+	}
+	const tokens = Number(normalized.replaceAll(",", ""));
+	if (!Number.isFinite(tokens) || tokens <= 0) {
+		ctx.ui.notify("Enter a positive token count, or `off` to clear this threshold.", "warning");
+		return;
+	}
+	budgets.setUsageTokenBudget(period, tokens);
+	ctx.ui.notify(`${label} token budget set to ${tokens.toLocaleString()} tokens.`, "info");
+}
+
+export async function showSettingsPanel(
+	ctx: ExtensionCommandContext,
+	enforcement: EnforcementControl,
+	recovery: CodexRecoveryControl,
+	budgets: UsageBudgetControl,
+	effects: SettingsEffects = {
+		setEnforcement: (enabled) => enforcement.setEnabled(enabled),
+		setFooter: (enabled) => enforcement.setFooterEnabled(enabled),
+		setRecovery: (enabled) => recovery.setCodexRecoveryEnabled(enabled),
+	},
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(renderSettingsView(settingsSnapshot(enforcement, recovery, budgets), -1, 100, plainTheme()).slice(0, -2).join("\n"), "info");
+		return;
+	}
+	for (;;) {
+		const snapshot = settingsSnapshot(enforcement, recovery, budgets);
+		const action = await ctx.ui.custom<SettingsAction>((tui, theme, _keybindings, done) => {
+			let selected = 0;
+			return {
+				invalidate() {},
+				render(width: number): string[] { return renderSettingsView(snapshot, selected, width, theme); },
+				handleInput(data: string): void {
+					if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "q") done({ kind: "close" });
+					else if (matchesKey(data, "up")) { selected = (selected - 1 + SETTINGS_KEYS.length) % SETTINGS_KEYS.length; tui.requestRender(); }
+					else if (matchesKey(data, "down")) { selected = (selected + 1) % SETTINGS_KEYS.length; tui.requestRender(); }
+					else if (matchesKey(data, "return") || matchesKey(data, "enter") || matchesKey(data, "space")) done({ kind: "activate", key: SETTINGS_KEYS[selected]! });
+				},
+			};
+		});
+		if (!action || action.kind === "close") return;
+		if (action.key === "enforcement") {
+			if (enforcement.isEnabled()) {
+				if (await ctx.ui.confirm("Disable routing enforcement?", "Jittor will remain monitor-only and will no longer block unsafe provider requests.")) await effects.setEnforcement(false);
+			} else await effects.setEnforcement(true);
+			continue;
+		}
+		if (action.key === "footer") {
+			await effects.setFooter(!enforcement.isFooterEnabled());
+			continue;
+		}
+		if (action.key === "recovery") {
+			if (!recovery.isCodexRecoveryEnabled()) {
+				if (await ctx.ui.confirm("Enable Codex recovery?", "Jittor may start bounded hidden retries only after transient Codex failures fully settle.")) await effects.setRecovery(true);
+			} else await effects.setRecovery(false);
+			continue;
+		}
+		await editBudget(ctx, budgets, action.key.slice("budget-".length) as UsagePeriod);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Just-in-Time Token Optimizing Router for Pi",
   "type": "module",
   "keywords": ["pi-package", "llm-router", "token-budget"],

package/src/cli.ts

@@ -5,7 +5,9 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SYSTEMD_UNIT_NAME } from "./constants.ts";
+import { connectJittorClient } from "./client.ts";
 import { serveMain } from "./daemon.ts";
+import type { ContextAssessment } from "./domain/context-telemetry.ts";
 import { resolveJittorPaths } from "./state.ts";
 
 export interface SystemdUnitOptions {
@@ -33,6 +35,19 @@ WantedBy=default.target
 `;
 }
 
+interface ContextClient {
+	call(operation: "context.assess", input: { since?: number; until?: number }): Promise<ContextAssessment>;
+}
+
+export interface CliDependencies {
+	client: ContextClient;
+	stdout(line: string): void;
+	stderr(line: string): void;
+	systemctl(...args: string[]): void;
+	installService(): void;
+	serve(): void;
+}
+
 function systemctl(...args: string[]): void {
 	execFileSync("systemctl", ["--user", ...args], { stdio: "inherit" });
 }
@@ -51,23 +66,80 @@ function installService(): void {
 	systemctl("restart", SYSTEMD_UNIT_NAME);
 }
 
-function usage(): never {
-	console.error("Usage: jittor serve | service <install|start|stop|restart|status>");
-	process.exit(2);
+const DEFAULT_DEPENDENCIES: CliDependencies = {
+	get client() { return connectJittorClient(); },
+	stdout: console.log,
+	stderr: console.error,
+	systemctl,
+	installService,
+	serve: serveMain,
+};
+
+function usage(stderr: (line: string) => void): number {
+	stderr("Usage: jittor serve | service <install|start|stop|restart|status> | context [--since <ms>] [--until <ms>] [--json]");
+	return 2;
+}
+
+function parseContextArgs(args: string[]): { input: { since?: number; until?: number }; json: boolean } | null {
+	const input: { since?: number; until?: number } = {};
+	let json = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") { json = true; continue; }
+		if (argument !== "--since" && argument !== "--until") return null;
+		const raw = args[++index];
+		const value = raw === undefined ? Number.NaN : Number(raw);
+		if (!Number.isSafeInteger(value) || value < 0) return null;
+		if (argument === "--since") input.since = value;
+		else input.until = value;
+	}
+	if (input.since !== undefined && input.until !== undefined && input.until < input.since) return null;
+	return { input, json };
 }
 
-export function main(args: string[] = process.argv.slice(2)): void {
-	const [command, action] = args;
-	if (command === "serve") { serveMain(); return; }
-	if (command !== "service") usage();
+function value(value: number | null, suffix = ""): string {
+	return value === null ? "unknown" : `${Math.round(value).toLocaleString()}${suffix}`;
+}
+
+export function formatContextAssessment(summary: ContextAssessment): string {
+	return [
+		`Context assessment: ${summary.completeness}`,
+		`Papyrus injection: ${summary.injection.runs} runs · avg ${value(summary.injection.averageCharacters, " chars")} · p95 ${value(summary.injection.p95Characters, " chars")} · max ${value(summary.injection.maxCharacters, " chars")}`,
+		`Injection mix: rules ${summary.injection.ruleCharacters.toLocaleString()} chars · tasks ${summary.injection.taskCharacters.toLocaleString()} chars · estimated ${summary.injection.estimatedTokens.toLocaleString()} tokens · unchanged ${summary.injection.unchangedRate === null ? "unknown" : `${(summary.injection.unchangedRate * 100).toFixed(1)}%`}`,
+		`Compactions: ${summary.compaction.completed} completed · ${summary.compaction.aborted} aborted · avg ${value(summary.compaction.averageDurationMs, "ms")} · ${summary.compaction.perRun === null ? "unknown" : summary.compaction.perRun.toFixed(3)} per agent run · ${summary.compaction.perTurn === null ? "unknown" : summary.compaction.perTurn.toFixed(3)} per turn`,
+		`Between compactions: ${value(summary.compaction.averageTurnsBetween, " turns")} · ${value(summary.compaction.averageProviderTokensBetween, " provider tokens")} · ${value(summary.compaction.averageCacheReadTokensBetween, " cache-read tokens")}`,
+		`Reasons: threshold ${summary.compaction.reasons.threshold} · overflow ${summary.compaction.reasons.overflow} · manual ${summary.compaction.reasons.manual}`,
+	].join("\n");
+}
+
+export async function runCli(args: string[], deps: CliDependencies = DEFAULT_DEPENDENCIES): Promise<number> {
+	const [command, action, ...rest] = args;
+	if (command === "serve") { deps.serve(); return 0; }
+	if (command === "context") {
+		const parsed = parseContextArgs([...(action === undefined ? [] : [action]), ...rest]);
+		if (!parsed) return usage(deps.stderr);
+		try {
+			const summary = await deps.client.call("context.assess", parsed.input);
+			deps.stdout(parsed.json ? JSON.stringify(summary) : formatContextAssessment(summary));
+			return 0;
+		} catch (error) {
+			deps.stderr(error instanceof Error ? error.message : String(error));
+			return 1;
+		}
+	}
+	if (command !== "service") return usage(deps.stderr);
 	switch (action) {
-		case "install": installService(); break;
-		case "start": systemctl("start", SYSTEMD_UNIT_NAME); break;
-		case "stop": systemctl("stop", SYSTEMD_UNIT_NAME); break;
-		case "restart": systemctl("restart", SYSTEMD_UNIT_NAME); break;
-		case "status": systemctl("status", SYSTEMD_UNIT_NAME); break;
-		default: usage();
+		case "install": deps.installService(); return 0;
+		case "start": deps.systemctl("start", SYSTEMD_UNIT_NAME); return 0;
+		case "stop": deps.systemctl("stop", SYSTEMD_UNIT_NAME); return 0;
+		case "restart": deps.systemctl("restart", SYSTEMD_UNIT_NAME); return 0;
+		case "status": deps.systemctl("status", SYSTEMD_UNIT_NAME); return 0;
+		default: return usage(deps.stderr);
 	}
 }
 
-if (import.meta.main) main();
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+	process.exitCode = await runCli(args);
+}
+
+if (import.meta.main) await main();

package/src/constants.ts

@@ -17,6 +17,13 @@ export const FOOTER_COMPACTION_DRAIN_STEP_MS = 3_000;
 export const MILLISECONDS_PER_SECOND = 1_000;
 export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
 export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
+export const PAPYRUS_CONTEXT_INJECTION_CHANNEL = "papyrus.context-injection.v1";
+export const PAPYRUS_CONTEXT_INJECTION_SCHEMA = "papyrus.context-injection/v1";
+export const CONTEXT_OBSERVATION_MAX_CHARACTERS = 10_000_000;
+export const CONTEXT_OBSERVATION_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
+export const CONTEXT_ASSESSMENT_QUERY_LIMIT = 10_000;
+export const CONTEXT_EVENT_DEDUP_LIMIT = 1_000;
+export const CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS = 24 * MILLISECONDS_PER_HOUR;
 export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
 export const LOOPBACK_HOST = "127.0.0.1";
 export const JITTOR_STATE_DIRECTORY = "jittor";

package/src/domain/context-telemetry.ts

@@ -0,0 +1,280 @@
+import {
+	CONTEXT_OBSERVATION_MAX_AGE_MS,
+	CONTEXT_OBSERVATION_MAX_CHARACTERS,
+	MILLISECONDS_PER_HOUR,
+	PAPYRUS_CONTEXT_INJECTION_SCHEMA,
+} from "../constants.ts";
+import type { MetricObservation, StoredMetricObservation } from "./metric.ts";
+
+interface PayloadSize { characters: number; bytes: number }
+
+export interface PapyrusContextInjection {
+	schema: typeof PAPYRUS_CONTEXT_INJECTION_SCHEMA;
+	observedAt: number;
+	sequence: number;
+	producerId: string;
+	before: PayloadSize;
+	rules: PayloadSize & { count: number };
+	tasks: PayloadSize;
+	injected: PayloadSize;
+	after: PayloadSize;
+	estimatedTokens: number;
+	share: number;
+	fingerprint: string;
+	unchanged: boolean;
+}
+
+const TOP_LEVEL_FIELDS = new Set(["schema", "observedAt", "sequence", "producerId", "before", "rules", "tasks", "injected", "after", "estimatedTokens", "share", "fingerprint", "unchanged"]);
+const SIZE_FIELDS = new Set(["characters", "bytes"]);
+const RULE_SIZE_FIELDS = new Set(["characters", "bytes", "count"]);
+
+function record(value: unknown, name: string, fields: Set<string>): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${name} must be an object`);
+	const result = value as Record<string, unknown>;
+	for (const key of Object.keys(result)) if (!fields.has(key)) throw new Error(`${name} contains unexpected field: ${key}`);
+	return result;
+}
+
+function integer(value: unknown, name: string, maximum = Number.MAX_SAFE_INTEGER): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum) throw new Error(`${name} must be a bounded non-negative integer`);
+	return value;
+}
+
+function size(value: unknown, name: string, fields = SIZE_FIELDS): PayloadSize {
+	const input = record(value, name, fields);
+	return {
+		characters: integer(input["characters"], `${name}.characters`, CONTEXT_OBSERVATION_MAX_CHARACTERS),
+		bytes: integer(input["bytes"], `${name}.bytes`, CONTEXT_OBSERVATION_MAX_CHARACTERS * 4),
+	};
+}
+
+export function validatePapyrusContextInjection(value: unknown, now = Date.now()): PapyrusContextInjection {
+	const input = record(value, "context injection", TOP_LEVEL_FIELDS);
+	if (input["schema"] !== PAPYRUS_CONTEXT_INJECTION_SCHEMA) throw new Error("context injection schema is not supported");
+	const observedAt = integer(input["observedAt"], "observedAt");
+	if (Math.abs(now - observedAt) > CONTEXT_OBSERVATION_MAX_AGE_MS) throw new Error("context injection observation is stale");
+	const producerId = input["producerId"];
+	if (typeof producerId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(producerId)) throw new Error("producerId must be a UUID");
+	const before = size(input["before"], "before");
+	const rulesInput = record(input["rules"], "rules", RULE_SIZE_FIELDS);
+	const rules = { ...size(rulesInput, "rules", RULE_SIZE_FIELDS), count: integer(rulesInput["count"], "rules.count") };
+	const tasks = size(input["tasks"], "tasks");
+	const injected = size(input["injected"], "injected");
+	const after = size(input["after"], "after");
+	if (injected.characters !== rules.characters + tasks.characters || after.characters !== before.characters + injected.characters) {
+		throw new Error("context injection sizes are inconsistent");
+	}
+	const estimatedTokens = integer(input["estimatedTokens"], "estimatedTokens", CONTEXT_OBSERVATION_MAX_CHARACTERS);
+	const share = input["share"];
+	if (typeof share !== "number" || !Number.isFinite(share) || share < 0 || share > 1) throw new Error("share must be a ratio");
+	const fingerprint = input["fingerprint"];
+	if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(fingerprint)) throw new Error("fingerprint must be a SHA-256 hex digest");
+	if (typeof input["unchanged"] !== "boolean") throw new Error("unchanged must be boolean");
+	return {
+		schema: PAPYRUS_CONTEXT_INJECTION_SCHEMA,
+		observedAt,
+		sequence: integer(input["sequence"], "sequence"),
+		producerId,
+		before,
+		rules,
+		tasks,
+		injected,
+		after,
+		estimatedTokens,
+		share,
+		fingerprint,
+		unchanged: input["unchanged"],
+	};
+}
+
+export function papyrusContextMetric(observation: PapyrusContextInjection): MetricObservation {
+	return {
+		source: "papyrus-context",
+		scope: "system-prompt",
+		metric: "injected-characters",
+		value: observation.injected.characters,
+		unit: "count",
+		observedAt: observation.observedAt,
+		attributes: {
+			sequence: observation.sequence,
+			producerId: observation.producerId,
+			beforeCharacters: observation.before.characters,
+			afterCharacters: observation.after.characters,
+			injectedBytes: observation.injected.bytes,
+			ruleCharacters: observation.rules.characters,
+			taskCharacters: observation.tasks.characters,
+			ruleCount: observation.rules.count,
+			estimatedTokens: observation.estimatedTokens,
+			share: observation.share,
+			fingerprint: observation.fingerprint,
+			unchanged: observation.unchanged,
+		},
+	};
+}
+
+export interface CompactionStart {
+	reason: "manual" | "threshold" | "overflow";
+	willRetry: boolean;
+	contextPercent?: number;
+	contextTokens?: number;
+}
+
+interface OpenCompaction extends CompactionStart { startedAt: number }
+interface UsageCounters {
+	turns: number;
+	injectedCharacters: number;
+	estimatedInjectedTokens: number;
+	providerTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+}
+
+function emptyCounters(): UsageCounters {
+	return { turns: 0, injectedCharacters: 0, estimatedInjectedTokens: 0, providerTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+}
+
+export class CompactionTelemetry {
+	private open: OpenCompaction | undefined;
+	private counters = emptyCounters();
+	private previousCompletedAt: number | undefined;
+
+	hasOpenCompaction(): boolean { return this.open !== undefined; }
+	observeTurn(): void { this.counters.turns += 1; }
+	observeInjection(characters: number, estimatedTokens: number): void {
+		this.counters.injectedCharacters += Math.max(0, characters);
+		this.counters.estimatedInjectedTokens += Math.max(0, estimatedTokens);
+	}
+	observeProviderUsage(usage: { input: number; output: number; cacheRead: number; cacheWrite: number }): void {
+		this.counters.providerTokens += Math.max(0, usage.input) + Math.max(0, usage.output);
+		this.counters.cacheReadTokens += Math.max(0, usage.cacheRead);
+		this.counters.cacheWriteTokens += Math.max(0, usage.cacheWrite);
+	}
+
+	begin(input: CompactionStart, now = Date.now()): MetricObservation {
+		this.open = { ...input, startedAt: now };
+		return { source: "pi-context", scope: "compaction", metric: "compaction-started", value: 1, unit: "count", observedAt: now, attributes: { ...input } };
+	}
+
+	complete(input: Pick<CompactionStart, "reason" | "willRetry">, now = Date.now()): MetricObservation {
+		if (!this.open) return { source: "pi-context", scope: "compaction", metric: "compaction-unmatched", value: 1, unit: "count", observedAt: now, attributes: { ...input } };
+		const open = this.open;
+		this.open = undefined;
+		const attributes = this.intervalAttributes(open, now);
+		this.previousCompletedAt = now;
+		this.counters = emptyCounters();
+		return { source: "pi-context", scope: "compaction", metric: "compaction-duration", value: Math.max(0, now - open.startedAt), unit: "milliseconds", observedAt: now, attributes: { ...attributes, reason: input.reason, willRetry: input.willRetry } };
+	}
+
+	abort(now = Date.now(), abortReason = "aborted"): MetricObservation {
+		const open = this.open;
+		this.open = undefined;
+		if (!open) return { source: "pi-context", scope: "compaction", metric: "compaction-unmatched", value: 1, unit: "count", observedAt: now, attributes: { abortReason } };
+		const attributes = this.intervalAttributes(open, now);
+		this.counters = emptyCounters();
+		return { source: "pi-context", scope: "compaction", metric: "compaction-aborted", value: 1, unit: "count", observedAt: now, attributes: { ...attributes, reason: open.reason, abortReason, durationMs: Math.max(0, now - open.startedAt) } };
+	}
+
+	private intervalAttributes(open: OpenCompaction, now: number): Record<string, unknown> {
+		return {
+			reason: open.reason,
+			willRetry: open.willRetry,
+			...(open.contextPercent === undefined ? {} : { contextPercent: open.contextPercent }),
+			...(open.contextTokens === undefined ? {} : { contextTokens: open.contextTokens }),
+			turnsSincePrevious: this.counters.turns,
+			injectedCharactersSincePrevious: this.counters.injectedCharacters,
+			estimatedInjectedTokensSincePrevious: this.counters.estimatedInjectedTokens,
+			providerTokensSincePrevious: this.counters.providerTokens,
+			cacheReadTokensSincePrevious: this.counters.cacheReadTokens,
+			cacheWriteTokensSincePrevious: this.counters.cacheWriteTokens,
+			...(this.previousCompletedAt === undefined ? {} : { elapsedSincePreviousMs: Math.max(0, now - this.previousCompletedAt) }),
+		};
+	}
+}
+
+export interface ContextAssessment {
+	window: { since: number; until: number };
+	completeness: "complete" | "truncated";
+	injection: {
+		runs: number;
+		averageCharacters: number | null;
+		p95Characters: number | null;
+		maxCharacters: number | null;
+		estimatedTokens: number;
+		unchangedRate: number | null;
+		averageShare: number | null;
+		ruleCharacters: number;
+		taskCharacters: number;
+	};
+	compaction: {
+		completed: number;
+		aborted: number;
+		averageDurationMs: number | null;
+		perRun: number | null;
+		perTurn: number | null;
+		perHour: number | null;
+		averageTurnsBetween: number | null;
+		averageElapsedMsBetween: number | null;
+		averageProviderTokensBetween: number | null;
+		averageCacheReadTokensBetween: number | null;
+		reasons: Record<"manual" | "threshold" | "overflow", number>;
+	};
+}
+
+function numericAttribute(row: StoredMetricObservation, key: string): number | null {
+	const value = row.attributes[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function average(values: number[]): number | null { return values.length === 0 ? null : values.reduce((sum, value) => sum + value, 0) / values.length; }
+function sum(values: number[]): number { return values.reduce((total, value) => total + value, 0); }
+function percentile(values: number[], percentage: number): number | null {
+	if (values.length === 0) return null;
+	const sorted = [...values].sort((left, right) => left - right);
+	return sorted[Math.max(0, Math.ceil(sorted.length * percentage) - 1)]!;
+}
+
+export function assessContextTelemetry(
+	injections: StoredMetricObservation[],
+	compactions: StoredMetricObservation[],
+	options: { since: number; until: number; truncated: boolean },
+): ContextAssessment {
+	const injectionValues = injections.flatMap((row) => typeof row.value === "number" ? [row.value] : []);
+	const shares = injections.flatMap((row) => numericAttribute(row, "share") ?? []);
+	const unchanged = injections.filter((row) => row.attributes["unchanged"] === true).length;
+	const completed = compactions.filter((row) => row.metric === "compaction-duration" && typeof row.value === "number");
+	const aborted = compactions.filter((row) => row.metric === "compaction-aborted");
+	const reasons = { manual: 0, threshold: 0, overflow: 0 };
+	for (const row of completed) {
+		const reason = row.attributes["reason"];
+		if (reason === "manual" || reason === "threshold" || reason === "overflow") reasons[reason] += 1;
+	}
+	const windowMs = Math.max(0, options.until - options.since);
+	const turnsBetween = completed.flatMap((row) => numericAttribute(row, "turnsSincePrevious") ?? []);
+	return {
+		window: { since: options.since, until: options.until },
+		completeness: options.truncated ? "truncated" : "complete",
+		injection: {
+			runs: injections.length,
+			averageCharacters: average(injectionValues),
+			p95Characters: percentile(injectionValues, 0.95),
+			maxCharacters: injectionValues.length === 0 ? null : Math.max(...injectionValues),
+			estimatedTokens: sum(injections.flatMap((row) => numericAttribute(row, "estimatedTokens") ?? [])),
+			unchangedRate: injections.length === 0 ? null : unchanged / injections.length,
+			averageShare: average(shares),
+			ruleCharacters: sum(injections.flatMap((row) => numericAttribute(row, "ruleCharacters") ?? [])),
+			taskCharacters: sum(injections.flatMap((row) => numericAttribute(row, "taskCharacters") ?? [])),
+		},
+		compaction: {
+			completed: completed.length,
+			aborted: aborted.length,
+			averageDurationMs: average(completed.map((row) => row.value as number)),
+			perRun: injections.length === 0 ? null : completed.length / injections.length,
+			perTurn: sum(turnsBetween) === 0 ? null : completed.length / sum(turnsBetween),
+			perHour: completed.length === 0 || windowMs === 0 ? null : completed.length / (windowMs / MILLISECONDS_PER_HOUR),
+			averageTurnsBetween: average(turnsBetween),
+			averageElapsedMsBetween: average(completed.flatMap((row) => numericAttribute(row, "elapsedSincePreviousMs") ?? [])),
+			averageProviderTokensBetween: average(completed.flatMap((row) => numericAttribute(row, "providerTokensSincePrevious") ?? [])),
+			averageCacheReadTokensBetween: average(completed.flatMap((row) => numericAttribute(row, "cacheReadTokensSincePrevious") ?? [])),
+			reasons,
+		},
+	};
+}

package/src/service.ts

@@ -1,6 +1,7 @@
-import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS, CONTEXT_ASSESSMENT_QUERY_LIMIT, SERVICE_MAX_BODY_BYTES } from "./constants.ts";
 import { VERSION } from "./version.ts";
 import { validateMetricObservation, type MetricObservation, type MetricQuery, type StoredMetricObservation } from "./domain/metric.ts";
+import { assessContextTelemetry, type ContextAssessment } from "./domain/context-telemetry.ts";
 import type { MetricStore } from "./ports/metric-store.ts";
 import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
 import type { PolicyDecision, Route } from "./policy.ts";
@@ -9,6 +10,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"metrics.record",
 	"metrics.query",
 	"metrics.prune",
+	"context.assess",
 	"service.checkpoint",
 	"telemetry.poll",
 	"router.status",
@@ -26,6 +28,7 @@ export interface OperationInputs {
 	"metrics.record": MetricObservation;
 	"metrics.query": MetricQuery;
 	"metrics.prune": { before: number };
+	"context.assess": { since?: number; until?: number };
 	"service.checkpoint": Record<string, never>;
 	"telemetry.poll": Record<string, never>;
 	"router.status": Record<string, never>;
@@ -41,6 +44,7 @@ export interface OperationOutputs {
 	"metrics.record": StoredMetricObservation;
 	"metrics.query": StoredMetricObservation[];
 	"metrics.prune": { deleted: number };
+	"context.assess": ContextAssessment;
 	"service.checkpoint": { ok: true };
 	"telemetry.poll": TelemetryPollResult;
 	"router.status": RouterStatus;
@@ -89,6 +93,19 @@ export class JittorService {
 				if (typeof before !== "number") throw new Error("before is required");
 				return { deleted: this.metrics.pruneBefore(before) };
 			}
+			case "context.assess": {
+				const until = input["until"] === undefined ? Date.now() : input["until"];
+				const since = input["since"] === undefined && typeof until === "number" ? Math.max(0, until - CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS) : input["since"];
+				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) throw new Error("context assessment requires non-negative ordered integer bounds");
+				const query = { since: since as number, until: until as number, order: "asc" as const, limit: CONTEXT_ASSESSMENT_QUERY_LIMIT };
+				const injections = this.metrics.query({ ...query, source: "papyrus-context", metric: "injected-characters" });
+				const compactions = this.metrics.query({ ...query, source: "pi-context" });
+				return assessContextTelemetry(injections, compactions, {
+					since: since as number,
+					until: until as number,
+					truncated: injections.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT || compactions.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT,
+				});
+			}
 			case "service.checkpoint": this.metrics.checkpoint(); return { ok: true };
 			case "telemetry.poll": return this.router.poll();
 			case "router.status": return this.router.status();