@danypops/jittor 0.12.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Just-in-Time Token Optimizing Router for Pi -- supervised daemon, router policy, and CLI",
   "type": "module",
   "main": "./src/index.ts",
@@ -16,7 +16,7 @@
     "service:install": "bun src/cli.ts service install"
   },
   "dependencies": {
-    "@danypops/vehicle-server": "^0.2.1",
+    "@danypops/vehicle-server": "^0.3.1",
     "@danypops/vehicle-client": "^0.1.1",
     "google-auth-library": "^10.9.0"
   },

package/src/cli-commands/service-daemon.ts

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
+import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { SYSTEMD_UNIT_NAME } from "../constants.ts";
 import { resolveJittorPaths } from "../state.ts";
 import { callAndPrint, type CliDependencies } from "./support.ts";
@@ -16,23 +17,30 @@ export interface SystemdUnitOptions {
 	openRouterBenchmarks?: boolean;
 }
 
-export function renderSystemdUnit(options: SystemdUnitOptions): string {
-	return `[Unit]
-Description=Jittor token optimizing router
-After=default.target network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=${options.bunBin} ${options.cliPath} serve
-${options.codexAuthFile ? `Environment="JITTOR_CODEX_AUTH_FILE=${options.codexAuthFile.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"\n` : ""}${options.openRouterBenchmarks ? "Environment=JITTOR_OPENROUTER_BENCHMARKS=1\n" : ""}Restart=always
-RestartSec=2
-NoNewPrivileges=true
-PrivateTmp=true
+function jittorServiceSpec(options: SystemdUnitOptions): ServiceSpec {
+	const env: Record<string, string> = {};
+	if (options.codexAuthFile) env["JITTOR_CODEX_AUTH_FILE"] = options.codexAuthFile;
+	if (options.openRouterBenchmarks) env["JITTOR_OPENROUTER_BENCHMARKS"] = "1";
+	return {
+		name: "jittor",
+		displayName: "Jittor token optimizing router",
+		binPath: options.bunBin,
+		args: [options.cliPath, "serve"],
+		env,
+		descriptorPath: resolveJittorPaths().serviceDescriptor,
+		// Jittor's own client (connectJittorClient) never auto-spawns -- systemd's own
+		// supervision is this daemon's only recovery path, same as Lector's.
+		restartOnFailure: true,
+		restartSec: 2,
+		noNewPrivileges: true,
+		privateTmp: true,
+		waitForNetwork: true,
+	};
+}
 
-[Install]
-WantedBy=default.target
-`;
+/** Pure text generator, delegating to vehicle-server's shared generateSystemdUnit -- kept as its own named export since jittor's own tests (and any external caller) call it directly with the same options shape as before. */
+export function renderSystemdUnit(options: SystemdUnitOptions): string {
+	return generateSystemdUnit(jittorServiceSpec(options));
 }
 
 export function systemctl(...args: string[]): void {
@@ -41,17 +49,18 @@ export function systemctl(...args: string[]): void {
 
 /** cliPath is the caller's own entrypoint file -- resolved from the real CLI script's `import.meta.url`, never this module's own, so the installed unit's ExecStart always points at the actual runnable CLI. */
 export function installService(cliPath: string): void {
-	const unitPath = resolveJittorPaths().serviceDescriptor;
-	mkdirSync(dirname(unitPath), { recursive: true });
 	const codexAuthFile = join(process.env["CODEX_HOME"] ?? join(homedir(), ".codex"), "auth.json");
-	writeFileSync(unitPath, renderSystemdUnit({
+	const spec = jittorServiceSpec({
 		bunBin: process.execPath,
 		cliPath,
 		...(existsSync(codexAuthFile) ? { codexAuthFile } : {}),
 		openRouterBenchmarks: process.env["JITTOR_OPENROUTER_BENCHMARKS"] === "1",
-	}));
-	systemctl("daemon-reload");
-	systemctl("enable", SYSTEMD_UNIT_NAME);
+	});
+	const result = installUserService(spec, createNodeServiceInstallDeps());
+	if (!result.installed) throw new Error(`failed to install the Jittor service: ${result.reason}`);
+	// installUserService's Linux path is `enable --now` (starts if not already running) --
+	// an explicit restart on top ensures a re-install after a Jittor upgrade actually picks
+	// up the freshly-generated unit's new ExecStart path, not just re-enables the old one.
 	systemctl("restart", SYSTEMD_UNIT_NAME);
 }
 

package/src/constants.ts

@@ -115,3 +115,25 @@ export const GOOGLE_VERTEX_BUDGET_MAX_MESSAGES_PER_PULL = 20;
  */
 export const GOOGLE_VERTEX_BUDGET_CONFIDENCE = 0.6;
 export const GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS = 60_000;
+/**
+ * Context Hub: the shared, versioned, multi-producer channel any extension can target to
+ * contribute one segment of the context-window breakdown (successor to the single-producer
+ * papyrus.context-injection.v1 shape) -- Papyrus's rules/tasks segment is the first producer.
+ */
+export const CONTEXT_HUB_CONTRIBUTION_CHANNEL = "jittor.context-contribution.v1";
+export const CONTEXT_HUB_CONTRIBUTION_SCHEMA = "jittor.context-contribution/v1";
+export const CONTEXT_HUB_PRODUCER_NAME_MAX_CHARACTERS = 80;
+export const CONTEXT_HUB_SEGMENT_LABEL_MAX_CHARACTERS = 160;
+export const CONTEXT_HUB_SEGMENT_KEY_MAX_CHARACTERS = 80;
+export const CONTEXT_HUB_ITEM_LABEL_MAX_CHARACTERS = 200;
+export const CONTEXT_HUB_MAX_ITEMS_PER_SEGMENT = 500;
+export const CONTEXT_HUB_MAX_ITEM_DEPTH = 6;
+export const CONTEXT_HUB_CONTRIBUTION_MAX_AGE_MS = 5 * MILLISECONDS_PER_MINUTE;
+export const CONTEXT_HUB_CONTRIBUTION_DEDUP_LIMIT = 1_000;
+/** Matches Papyrus's own CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN; kept independent since Jittor does not depend on the Papyrus package. */
+export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
+/** Matches Papyrus's own CONTEXT_TREE_MAX_NODES: a bound on the message-history tree walk, independent of any other producer's own item-count bound (CONTEXT_HUB_MAX_ITEMS_PER_SEGMENT). */
+export const CONTEXT_TREE_MAX_NODES = 50_000;
+/** Pi's own documented compaction-reserve default (docs/compaction.md): headroom kept free for the model's response, subtracted from the model's contextWindow to get the real usable budget. */
+export const CONTEXT_DEFAULT_RESERVE_TOKENS = 16_384;
+export const CONTEXT_HUB_CONFIDENCE_TIERS = ["exact-tool", "exact-structural", "exact-cooperative", "correlated", "audited"] as const;

package/src/domain/context-hub.ts

@@ -0,0 +1,236 @@
+/**
+ * Context Hub: Jittor's cross-extension context-window attribution. Two independent pieces:
+ *
+ * - The tool-schema ledger (computeToolSchemaLedger/toolLedgerSegment): exact, zero-cooperation
+ *   attribution of tool-schema cost (name + description + parameters + guidelines) per owning
+ *   extension, using Pi's own `sourceInfo` on every registered tool -- no other package needs to
+ *   change for this to work.
+ * - The shared contribution channel (validateContextContribution/contextContributionMetric): any
+ *   extension can opt in and contribute one segment of the breakdown (e.g. Papyrus's rules/tasks
+ *   segment) over `CONTEXT_HUB_CONTRIBUTION_CHANNEL`, the same shared-bus pattern already proven
+ *   by papyrus.context-injection.v1, generalized to a human-readable producer name and a nested
+ *   segment/item shape instead of one flat character count.
+ */
+import {
+	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
+	CONTEXT_HUB_CONFIDENCE_TIERS,
+	CONTEXT_HUB_CONTRIBUTION_MAX_AGE_MS,
+	CONTEXT_HUB_CONTRIBUTION_SCHEMA,
+	CONTEXT_HUB_ITEM_LABEL_MAX_CHARACTERS,
+	CONTEXT_HUB_MAX_ITEMS_PER_SEGMENT,
+	CONTEXT_HUB_MAX_ITEM_DEPTH,
+	CONTEXT_HUB_PRODUCER_NAME_MAX_CHARACTERS,
+	CONTEXT_HUB_SEGMENT_KEY_MAX_CHARACTERS,
+	CONTEXT_HUB_SEGMENT_LABEL_MAX_CHARACTERS,
+} from "../constants.ts";
+import type { MetricObservation } from "./metric.ts";
+
+export type ContextConfidenceTier = (typeof CONTEXT_HUB_CONFIDENCE_TIERS)[number];
+
+export interface ContextSegmentItem {
+	label: string;
+	estimatedTokens: number;
+	children?: ContextSegmentItem[];
+}
+
+export interface ContextSegment {
+	key: string;
+	label: string;
+	estimatedTokens: number;
+	confidence: ContextConfidenceTier;
+	items?: ContextSegmentItem[];
+	/**
+	 * True when this segment's size is genuinely unmeasured (not yet observed), as opposed to
+	 * measured-and-actually-zero -- e.g. the base system prompt before the first observed turn.
+	 * A display layer that hides zero-token rows to cut noise must NOT hide an unknown segment
+	 * just because its placeholder value happens to be zero -- that would silently misrepresent
+	 * "we don't know" as "there is nothing here".
+	 */
+	unknown?: boolean;
+}
+
+export interface ContextContribution {
+	schema: typeof CONTEXT_HUB_CONTRIBUTION_SCHEMA;
+	observedAt: number;
+	sequence: number;
+	producerName: string;
+	segment: ContextSegment;
+}
+
+function nonEmptyString(value: unknown, name: string, maxLength: number): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > maxLength) throw new Error(`${name} must be a non-empty string of at most ${maxLength} characters`);
+	return value;
+}
+
+function boundedInteger(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a bounded non-negative integer`);
+	return value;
+}
+
+function countItems(items: ContextSegmentItem[]): number {
+	return items.reduce((sum, item) => sum + 1 + (item.children ? countItems(item.children) : 0), 0);
+}
+
+function validateSegmentItem(value: unknown, depth: number): ContextSegmentItem {
+	if (depth > CONTEXT_HUB_MAX_ITEM_DEPTH) throw new Error(`context segment item nesting exceeds ${CONTEXT_HUB_MAX_ITEM_DEPTH} levels`);
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context segment item must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (key !== "label" && key !== "estimatedTokens" && key !== "children") throw new Error(`context segment item contains unexpected field: ${key}`);
+	}
+	const item: ContextSegmentItem = {
+		label: nonEmptyString(input["label"], "item.label", CONTEXT_HUB_ITEM_LABEL_MAX_CHARACTERS),
+		estimatedTokens: boundedInteger(input["estimatedTokens"], "item.estimatedTokens"),
+	};
+	if (input["children"] !== undefined) {
+		if (!Array.isArray(input["children"])) throw new Error("item.children must be an array");
+		item.children = input["children"].map((child) => validateSegmentItem(child, depth + 1));
+	}
+	return item;
+}
+
+/** Validates a bare segment (no contribution envelope) -- shared by validateContextContribution and Jittor's own directly-computed segments (tool ledger, base prompt, ...). */
+export function validateContextSegment(value: unknown): ContextSegment {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context segment must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) {
+		if (key !== "key" && key !== "label" && key !== "estimatedTokens" && key !== "confidence" && key !== "items" && key !== "unknown") {
+			throw new Error(`context segment contains unexpected field: ${key}`);
+		}
+	}
+	const confidence = input["confidence"];
+	if (typeof confidence !== "string" || !CONTEXT_HUB_CONFIDENCE_TIERS.includes(confidence as ContextConfidenceTier)) {
+		throw new Error(`confidence must be one of ${CONTEXT_HUB_CONFIDENCE_TIERS.join(", ")}`);
+	}
+	if (input["unknown"] !== undefined && typeof input["unknown"] !== "boolean") throw new Error("segment.unknown must be a boolean");
+	const segment: ContextSegment = {
+		key: nonEmptyString(input["key"], "segment.key", CONTEXT_HUB_SEGMENT_KEY_MAX_CHARACTERS),
+		label: nonEmptyString(input["label"], "segment.label", CONTEXT_HUB_SEGMENT_LABEL_MAX_CHARACTERS),
+		estimatedTokens: boundedInteger(input["estimatedTokens"], "segment.estimatedTokens"),
+		confidence: confidence as ContextConfidenceTier,
+		...(input["unknown"] !== undefined ? { unknown: input["unknown"] as boolean } : {}),
+	};
+	if (input["items"] !== undefined) {
+		if (!Array.isArray(input["items"])) throw new Error("segment.items must be an array");
+		const items = input["items"].map((item) => validateSegmentItem(item, 1));
+		if (countItems(items) > CONTEXT_HUB_MAX_ITEMS_PER_SEGMENT) throw new Error(`segment.items exceeds ${CONTEXT_HUB_MAX_ITEMS_PER_SEGMENT} total items`);
+		segment.items = items;
+	}
+	return segment;
+}
+
+const CONTRIBUTION_FIELDS = new Set(["schema", "observedAt", "sequence", "producerName", "segment"]);
+
+/** Validates one contribution posted on CONTEXT_HUB_CONTRIBUTION_CHANNEL. Fails closed on schema drift or an oversized/malformed payload, the same posture as validatePapyrusContextInjection. */
+export function validateContextContribution(value: unknown, now = Date.now()): ContextContribution {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("context contribution must be an object");
+	const input = value as Record<string, unknown>;
+	for (const key of Object.keys(input)) if (!CONTRIBUTION_FIELDS.has(key)) throw new Error(`context contribution contains unexpected field: ${key}`);
+	if (input["schema"] !== CONTEXT_HUB_CONTRIBUTION_SCHEMA) throw new Error("context contribution schema is not supported");
+	const observedAt = boundedInteger(input["observedAt"], "observedAt");
+	if (Math.abs(now - observedAt) > CONTEXT_HUB_CONTRIBUTION_MAX_AGE_MS) throw new Error("context contribution is stale");
+	return {
+		schema: CONTEXT_HUB_CONTRIBUTION_SCHEMA,
+		observedAt,
+		sequence: boundedInteger(input["sequence"], "sequence"),
+		producerName: nonEmptyString(input["producerName"], "producerName", CONTEXT_HUB_PRODUCER_NAME_MAX_CHARACTERS),
+		segment: validateContextSegment(input["segment"]),
+	};
+}
+
+/** Bounded, content-free metric projection for storage/history -- mirrors papyrusContextMetric's shape. */
+export function contextContributionMetric(contribution: ContextContribution): MetricObservation {
+	return {
+		source: "context-hub",
+		scope: contribution.producerName,
+		metric: "segment-tokens",
+		value: contribution.segment.estimatedTokens,
+		unit: "count",
+		observedAt: contribution.observedAt,
+		attributes: {
+			sequence: contribution.sequence,
+			segmentKey: contribution.segment.key,
+			segmentLabel: contribution.segment.label,
+			confidence: contribution.segment.confidence,
+			itemCount: contribution.segment.items ? countItems(contribution.segment.items) : 0,
+		},
+	};
+}
+
+/**
+ * Exact, zero-cooperation attribution of tool-schema cost: every registered tool's `sourceInfo`
+ * (populated by Pi's own resource loader from the extension that registered it, never guessed)
+ * identifies its owning extension. Tool schemas are fixed overhead paid on every single turn
+ * regardless of whether the tool is ever called, so this is the walking-skeleton signal --
+ * buildable without any other package changing.
+ */
+export interface ToolLedgerEntry {
+	name: string;
+	description?: string;
+	parameters?: unknown;
+	promptGuidelines?: string[];
+	promptSnippet?: string;
+	sourceInfo?: { source?: string; path?: string };
+}
+
+export interface ToolLedgerToolUsage {
+	name: string;
+	characters: number;
+	estimatedTokens: number;
+}
+
+export interface ToolLedgerSourceUsage {
+	source: string;
+	toolCount: number;
+	characters: number;
+	estimatedTokens: number;
+	tools: ToolLedgerToolUsage[];
+}
+
+function toolCharacters(tool: ToolLedgerEntry): number {
+	const parameterCharacters = tool.parameters === undefined ? 0 : JSON.stringify(tool.parameters).length;
+	const guidelineCharacters = (tool.promptGuidelines ?? []).reduce((sum, guideline) => sum + guideline.length, 0);
+	return tool.name.length + (tool.description?.length ?? 0) + parameterCharacters + guidelineCharacters + (tool.promptSnippet?.length ?? 0);
+}
+
+/** Groups every registered tool's serialized schema size by its owning extension (`sourceInfo.source`), sorted heaviest-first at both the source and tool level. A tool with no sourceInfo (e.g. an SDK-supplied custom tool) is grouped under "unknown" rather than dropped. */
+export function computeToolSchemaLedger(tools: readonly ToolLedgerEntry[]): ToolLedgerSourceUsage[] {
+	const bySource = new Map<string, ToolLedgerToolUsage[]>();
+	for (const tool of tools) {
+		const source = tool.sourceInfo?.source && tool.sourceInfo.source.length > 0 ? tool.sourceInfo.source : "unknown";
+		const characters = toolCharacters(tool);
+		const usage: ToolLedgerToolUsage = { name: tool.name, characters, estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) };
+		const existing = bySource.get(source);
+		if (existing) existing.push(usage);
+		else bySource.set(source, [usage]);
+	}
+	return [...bySource.entries()]
+		.map(([source, toolUsages]) => {
+			const sorted = [...toolUsages].sort((left, right) => right.characters - left.characters);
+			return {
+				source,
+				toolCount: sorted.length,
+				characters: sorted.reduce((sum, tool) => sum + tool.characters, 0),
+				estimatedTokens: sorted.reduce((sum, tool) => sum + tool.estimatedTokens, 0),
+				tools: sorted,
+			};
+		})
+		.sort((left, right) => right.characters - left.characters);
+}
+
+/** Projects the tool-schema ledger into one ContextSegment (`toolDefinitions`), ready to merge alongside any contributed segment. */
+export function toolLedgerSegment(tools: readonly ToolLedgerEntry[]): ContextSegment {
+	const ledger = computeToolSchemaLedger(tools);
+	const items: ContextSegmentItem[] = ledger.map((sourceUsage) => ({
+		label: `${sourceUsage.source} (${sourceUsage.toolCount} tool${sourceUsage.toolCount === 1 ? "" : "s"})`,
+		estimatedTokens: sourceUsage.estimatedTokens,
+		children: sourceUsage.tools.map((tool) => ({ label: tool.name, estimatedTokens: tool.estimatedTokens })),
+	}));
+	return {
+		key: "toolDefinitions",
+		label: "Tool definitions",
+		estimatedTokens: items.reduce((sum, item) => sum + item.estimatedTokens, 0),
+		confidence: "exact-tool",
+		items,
+	};
+}

package/src/index.ts

@@ -32,6 +32,20 @@ export {
 	applyTaskFocusEvent,
 	validateTaskFocusEvent,
 } from "./domain/task-focus.ts";
+export {
+	type ContextConfidenceTier,
+	type ContextContribution,
+	type ContextSegment,
+	type ContextSegmentItem,
+	type ToolLedgerEntry,
+	type ToolLedgerSourceUsage,
+	type ToolLedgerToolUsage,
+	computeToolSchemaLedger,
+	contextContributionMetric,
+	toolLedgerSegment,
+	validateContextContribution,
+	validateContextSegment,
+} from "./domain/context-hub.ts";
 export {
 	METRIC_UNITS,
 	type MetricObservation,