@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/session/prompt-cache.ts

@@ -0,0 +1,140 @@
+import {
+	type BackendCacheVerdict,
+	type BackendCompletionTimings,
+	type CacheVerdictCounts,
+	emptyCacheVerdictCounts,
+	uncachedPrefillTokens,
+} from "../../core/cache-telemetry.js";
+import type { SessionEntry } from "./entries.js";
+
+/** Durable prompt-cache facts folded across assistant calls in one ledger slice. */
+export interface PromptCacheTelemetry {
+	/** Sum of authoritative backend prefill work, or null when no call reported cache reads. */
+	uncachedPrefillTokens: number | null;
+	/** Calls contributing to `uncachedPrefillTokens`; distinguishes no evidence from a measured zero. */
+	uncachedPrefillCalls: number;
+	/** Counts of the verdict persisted on each assistant call. */
+	verdictCounts: CacheVerdictCounts;
+	/** Number of assistant calls carrying a recognized persisted verdict. */
+	verdictCalls: number;
+	/** How often each expected cache disturbance was stamped. */
+	expectedColdReasonCounts: Readonly<Record<string, number>>;
+}
+
+export interface ExpectedColdReasonCount {
+	reason: string;
+	count: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function backendTimings(value: unknown): BackendCompletionTimings | null {
+	if (!isRecord(value)) return null;
+	if (
+		!finiteNonNegative(value.promptTokens) ||
+		!finiteNonNegative(value.predictedTokens) ||
+		!finiteNonNegative(value.promptMs) ||
+		!finiteNonNegative(value.predictedMs) ||
+		(value.source !== "llamacpp-timings" && value.source !== "lmstudio-timings")
+	) {
+		return null;
+	}
+	const cachedTokens = value.cachedTokens;
+	if (cachedTokens !== null && !finiteNonNegative(cachedTokens)) return null;
+	if (typeof cachedTokens === "number" && cachedTokens > value.promptTokens) return null;
+	return {
+		promptTokens: value.promptTokens,
+		cachedTokens,
+		predictedTokens: value.predictedTokens,
+		promptMs: value.promptMs,
+		predictedMs: value.predictedMs,
+		source: value.source,
+	};
+}
+
+function cacheVerdict(value: unknown): BackendCacheVerdict | null {
+	switch (value) {
+		case "hot":
+		case "partial":
+		case "cold":
+		case "small":
+			return value;
+		default:
+			return null;
+	}
+}
+
+/** True when the fold contains at least one durable cache fact. */
+export function hasPromptCacheTelemetry(telemetry: PromptCacheTelemetry): boolean {
+	return (
+		telemetry.verdictCalls > 0 ||
+		telemetry.uncachedPrefillCalls > 0 ||
+		Object.keys(telemetry.expectedColdReasonCounts).length > 0
+	);
+}
+
+/** Most frequent expected disturbance, with deterministic lexical tie-breaking. */
+export function topExpectedColdReason(telemetry: PromptCacheTelemetry): ExpectedColdReasonCount | null {
+	const ranked = Object.entries(telemetry.expectedColdReasonCounts).sort(
+		([leftReason, leftCount], [rightReason, rightCount]) =>
+			rightCount - leftCount || leftReason.localeCompare(rightReason),
+	);
+	const first = ranked[0];
+	return first === undefined ? null : { reason: first[0], count: first[1] };
+}
+
+/**
+ * Fold persisted assistant `promptCache` payloads without reclassifying them.
+ * Callers provide the ledger slice they mean, such as one active branch or one
+ * report window, so every surface shares parsing while retaining its own scope.
+ */
+export function foldPromptCacheTelemetry(entries: ReadonlyArray<SessionEntry>): PromptCacheTelemetry {
+	const verdictCounts = emptyCacheVerdictCounts();
+	const expectedColdReasonCounts: Record<string, number> = {};
+	let verdictCalls = 0;
+	let uncachedTotal = 0;
+	let uncachedPrefillCalls = 0;
+
+	for (const entry of entries) {
+		if (entry.kind !== "message" || entry.role !== "assistant" || !isRecord(entry.payload)) continue;
+		const promptCache = entry.payload.promptCache;
+		if (!isRecord(promptCache)) continue;
+
+		const verdict = cacheVerdict(promptCache.backendVerdict);
+		if (verdict !== null) {
+			verdictCounts[verdict] += 1;
+			verdictCalls += 1;
+		}
+
+		const backend = backendTimings(promptCache.backend);
+		const uncached = uncachedPrefillTokens(backend);
+		if (uncached !== null) {
+			uncachedTotal += uncached;
+			uncachedPrefillCalls += 1;
+		}
+
+		if (!Array.isArray(promptCache.expectedColdReasons)) continue;
+		const reasons = new Set(
+			promptCache.expectedColdReasons.filter(
+				(reason): reason is string => typeof reason === "string" && reason.trim().length > 0,
+			),
+		);
+		for (const reason of reasons) {
+			expectedColdReasonCounts[reason] = (expectedColdReasonCounts[reason] ?? 0) + 1;
+		}
+	}
+
+	return {
+		uncachedPrefillTokens: uncachedPrefillCalls > 0 ? uncachedTotal : null,
+		uncachedPrefillCalls,
+		verdictCounts,
+		verdictCalls,
+		expectedColdReasonCounts,
+	};
+}

package/src/domains/session/prompt-manifest.ts

@@ -14,6 +14,21 @@ import type { SessionMeta } from "./contract.js";
  * stay diffable without recompiling anything.
  */
 
+/**
+ * Layout version of the compiled prompt these records describe.
+ *
+ * 1: the order shipped through 0.3.8.
+ * 2: stable-prefix-first ordering with one `# Memory` header, and
+ *    `contextWindowSource` recorded alongside the window the prompt states
+ *    (issue #249).
+ *
+ * A record without a `version` field predates the field and is read as 1, so a
+ * 0.3.8 manifest still parses. Bump this whenever the compiled text moves for a
+ * reason other than its inputs: a resumed session then has the version in hand
+ * to explain the one `promptRecompiled` entry its first compile writes.
+ */
+export const PROMPT_MANIFEST_VERSION = 2;
+
 export interface PromptManifestSection {
 	id: string;
 	tokenEstimate: number;
@@ -27,6 +42,8 @@ export interface PromptManifestFragment {
 }
 
 export interface SessionPromptCompileRecord {
+	/** Prompt layout version; see `PROMPT_MANIFEST_VERSION`. Absent on pre-0.3.9 records. */
+	version?: number;
 	/** ISO timestamp of the compile. */
 	at: string;
 	/** Hash of the previously served prompt, null on the first compile. */
@@ -35,6 +52,14 @@ export interface SessionPromptCompileRecord {
 	tokenEstimate: number;
 	/** Thinking dial applied to the live agent when this prompt was compiled. */
 	thinkingLevel: string | null;
+	/**
+	 * The window the prompt's `Context window: N` states, and the layer that
+	 * answered it. `loaded` is what the backend has this model open at; anything
+	 * else means the figure can still move once a loaded window is observed, and
+	 * a later recompile is then explained rather than mysterious.
+	 */
+	contextWindow?: number | null;
+	contextWindowSource?: string | null;
 	projectPreload: ProjectPreloadClass | null;
 	sections: PromptManifestSection[];
 	fragments: PromptManifestFragment[];
@@ -102,9 +127,21 @@ function isProjectPreloadClass(value: unknown): value is ProjectPreloadClass {
 	);
 }
 
+/** Optional fields added after 0.3.8: absent is valid, present must be well-typed. */
+function isOptional<T>(value: unknown, guard: (candidate: unknown) => candidate is T): boolean {
+	return value === undefined || guard(value);
+}
+
 function isSessionPromptCompileRecord(value: unknown): value is SessionPromptCompileRecord {
 	if (!isRecord(value)) return false;
 	return (
+		isOptional(value.version, isNonNegativeInteger) &&
+		isOptional(value.contextWindow, (candidate): candidate is number | null =>
+			candidate === null ? true : isNonNegativeInteger(candidate),
+		) &&
+		isOptional(value.contextWindowSource, (candidate): candidate is string | null =>
+			candidate === null ? true : typeof candidate === "string",
+		) &&
 		isCanonicalUtcTimestamp(value.at) &&
 		(value.previousHash === null || isSha256(value.previousHash)) &&
 		isSha256(value.systemPromptHash) &&
@@ -118,6 +155,11 @@ function isSessionPromptCompileRecord(value: unknown): value is SessionPromptCom
 	);
 }
 
+/** A record written before the field existed describes the 0.3.8 layout. */
+export function promptManifestVersion(record: SessionPromptCompileRecord): number {
+	return record.version ?? 1;
+}
+
 export function getPromptManifestFilePath(meta: SessionMeta, stateDir?: string): string {
 	const safeMeta = {
 		...meta,

package/src/domains/toolchain/archive.ts

@@ -0,0 +1,175 @@
+import { gunzipSync, inflateRawSync } from "node:zlib";
+
+/**
+ * Just enough zip and tar.gz reading to unpack a pinned release asset.
+ *
+ * Node ships neither reader, and the alternatives were a dependency or shelling
+ * out to `unzip` and `tar`. A dependency for two hundred lines of well-specified
+ * format is a poor trade, and shelling out makes the install fail on a machine
+ * that has one of the two but not the other, which is exactly the machine a
+ * vendored-tool installer exists to serve. Both readers are deliberately narrow:
+ * they read the members the registry names and refuse anything they do not
+ * understand rather than guessing.
+ *
+ * The bytes reaching here have already been checksum-verified against the pin,
+ * so these are not parsing hostile input. The size cap and the path checks are
+ * belt and braces for the day a pin is updated carelessly.
+ */
+
+/** One file read out of an archive. */
+export interface ArchiveEntry {
+	path: string;
+	data: Buffer;
+	/** Unix mode when the archive records one, otherwise null. */
+	mode: number | null;
+}
+
+/** Refuse to materialize more than this from one asset. */
+const MAX_TOTAL_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+
+const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_CENTRAL_SIGNATURE = 0x02014b50;
+const ZIP_LOCAL_SIGNATURE = 0x04034b50;
+const ZIP_STORED = 0;
+const ZIP_DEFLATED = 8;
+
+/** Every regular file in a zip, keyed by its path inside the archive. */
+export function readZipEntries(buffer: Buffer): Map<string, ArchiveEntry> {
+	const eocd = findEndOfCentralDirectory(buffer);
+	if (eocd < 0) throw new Error("not a zip archive: end-of-central-directory record not found");
+	const entryCount = buffer.readUInt16LE(eocd + 10);
+	let cursor = buffer.readUInt32LE(eocd + 16);
+	const entries = new Map<string, ArchiveEntry>();
+	let total = 0;
+
+	for (let i = 0; i < entryCount; i += 1) {
+		if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== ZIP_CENTRAL_SIGNATURE) {
+			throw new Error(`zip central directory is malformed at entry ${i}`);
+		}
+		const method = buffer.readUInt16LE(cursor + 10);
+		const compressedSize = buffer.readUInt32LE(cursor + 20);
+		const uncompressedSize = buffer.readUInt32LE(cursor + 24);
+		const nameLength = buffer.readUInt16LE(cursor + 28);
+		const extraLength = buffer.readUInt16LE(cursor + 30);
+		const commentLength = buffer.readUInt16LE(cursor + 32);
+		const externalAttributes = buffer.readUInt32LE(cursor + 38);
+		const localOffset = buffer.readUInt32LE(cursor + 42);
+		const name = buffer.toString("utf8", cursor + 46, cursor + 46 + nameLength);
+		cursor += 46 + nameLength + extraLength + commentLength;
+
+		if (name.endsWith("/")) continue;
+		assertSafeMember(name);
+		total += uncompressedSize;
+		if (total > MAX_TOTAL_UNCOMPRESSED_BYTES) throw new Error("zip archive expands beyond the size cap");
+
+		if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== ZIP_LOCAL_SIGNATURE) {
+			throw new Error(`zip local header is malformed for ${name}`);
+		}
+		const localNameLength = buffer.readUInt16LE(localOffset + 26);
+		const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+		const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+		const raw = buffer.subarray(dataStart, dataStart + compressedSize);
+		const data =
+			method === ZIP_STORED
+				? Buffer.from(raw)
+				: method === ZIP_DEFLATED
+					? inflateRawSync(raw)
+					: (() => {
+							throw new Error(`unsupported zip compression method ${method} for ${name}`);
+						})();
+		// The high 16 bits of the external attributes carry the unix mode when the
+		// archive was produced on a unix host, which is where the executable bit
+		// on a release binary lives.
+		const unixMode = (externalAttributes >>> 16) & 0o7777;
+		entries.set(name, { path: name, data, mode: unixMode === 0 ? null : unixMode });
+	}
+	return entries;
+}
+
+/** Every regular file in a gzipped tar, keyed by its path inside the archive. */
+export function readTarGzEntries(buffer: Buffer): Map<string, ArchiveEntry> {
+	const tar = gunzipSync(buffer);
+	const entries = new Map<string, ArchiveEntry>();
+	let offset = 0;
+	let total = 0;
+	let pendingLongName: string | null = null;
+
+	while (offset + 512 <= tar.length) {
+		const header = tar.subarray(offset, offset + 512);
+		// Two consecutive zero blocks end the archive; one is enough to stop.
+		if (header.every((byte) => byte === 0)) break;
+		const rawName = readTarString(header, 0, 100);
+		const prefix = readTarString(header, 345, 155);
+		const size = readTarOctal(header, 124, 12);
+		const mode = readTarOctal(header, 100, 8);
+		const typeFlag = String.fromCharCode(header[156] ?? 0);
+		const dataStart = offset + 512;
+		const padded = Math.ceil(size / 512) * 512;
+		offset = dataStart + padded;
+
+		// GNU long-name extension: this block's payload is the next block's name.
+		if (typeFlag === "L") {
+			pendingLongName = tar.toString("utf8", dataStart, dataStart + size).replace(/\0+$/, "");
+			continue;
+		}
+		// PAX headers and directories carry no file content Clio wants.
+		if (typeFlag === "x" || typeFlag === "g" || typeFlag === "5") {
+			pendingLongName = null;
+			continue;
+		}
+		if (typeFlag !== "0" && typeFlag !== "\0") {
+			pendingLongName = null;
+			continue;
+		}
+
+		const name = pendingLongName ?? (prefix.length > 0 ? `${prefix}/${rawName}` : rawName);
+		pendingLongName = null;
+		if (name.length === 0 || name.endsWith("/")) continue;
+		assertSafeMember(name);
+		total += size;
+		if (total > MAX_TOTAL_UNCOMPRESSED_BYTES) throw new Error("tar archive expands beyond the size cap");
+		entries.set(name, {
+			path: name,
+			data: Buffer.from(tar.subarray(dataStart, dataStart + size)),
+			mode: mode === 0 ? null : mode & 0o7777,
+		});
+	}
+	return entries;
+}
+
+function findEndOfCentralDirectory(buffer: Buffer): number {
+	// The record is at the very end unless a zip comment follows it, and the
+	// comment length field is 16 bits, so 22 + 65535 bytes is the whole search.
+	const start = Math.max(0, buffer.length - (22 + 0xffff));
+	for (let i = buffer.length - 22; i >= start; i -= 1) {
+		if (buffer.readUInt32LE(i) === ZIP_EOCD_SIGNATURE) return i;
+	}
+	return -1;
+}
+
+function readTarString(header: Buffer, offset: number, length: number): string {
+	const slice = header.subarray(offset, offset + length);
+	const end = slice.indexOf(0);
+	return slice.toString("utf8", 0, end === -1 ? slice.length : end);
+}
+
+function readTarOctal(header: Buffer, offset: number, length: number): number {
+	const text = readTarString(header, offset, length).trim();
+	if (text.length === 0) return 0;
+	const value = Number.parseInt(text, 8);
+	return Number.isNaN(value) ? 0 : value;
+}
+
+/**
+ * An archive member's path is used to look up a registry-named member, never to
+ * build a write path, but a member escaping the archive root still means the
+ * asset is not what the pin says it is.
+ */
+function assertSafeMember(name: string): void {
+	if (name.startsWith("/") || name.startsWith("\\") || /^[A-Za-z]:/.test(name)) {
+		throw new Error(`archive member has an absolute path: ${name}`);
+	}
+	if (name.split(/[/\\]/).includes("..")) {
+		throw new Error(`archive member escapes the archive root: ${name}`);
+	}
+}

package/src/domains/toolchain/contract.ts

@@ -0,0 +1,28 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type { ToolInstallOptions, ToolInstallResult } from "./install.js";
+import type { ToolRemoveOptions, ToolRemoveResult } from "./remove.js";
+import type { PinnedTool, ToolResolution, ToolStatus } from "./types.js";
+
+export interface ToolchainContract extends DomainContract {
+	/** The pinned table, in registry order. */
+	list(): ReadonlyArray<PinnedTool>;
+	/** One row by id. */
+	get(id: string): PinnedTool | null;
+	/** Resolve an executable name through PATH, then the vendored pin, then none. */
+	resolve(name: string): ToolResolution;
+	/** Per-entry state for one row. */
+	status(id: string): ToolStatus | null;
+	/** Per-entry state for every row. */
+	statuses(): ToolStatus[];
+	/**
+	 * Download and vendor one tool. Only ever called from an explicit operator
+	 * command; nothing on a startup path may reach it.
+	 */
+	install(id: string, options?: ToolInstallOptions): Promise<ToolInstallResult>;
+	/**
+	 * Delete every vendored version of one tool. Nothing outside
+	 * `<data>/tools/<id>` is reachable, and a tool with nothing installed is a
+	 * successful no-op rather than an error.
+	 */
+	remove(id: string, options?: ToolRemoveOptions): ToolRemoveResult;
+}

package/src/domains/toolchain/extension.ts

@@ -0,0 +1,47 @@
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import type { ToolchainContract } from "./contract.js";
+import type { ToolInstallOptions } from "./install.js";
+import { findPinnedTool, PINNED_TOOLS } from "./registry.js";
+import { removeTool, type ToolRemoveOptions } from "./remove.js";
+import { resolveToolBinary, toolStatus, toolStatuses } from "./resolve.js";
+
+export function createToolchainBundle(_context: DomainContext): DomainBundle<ToolchainContract> {
+	const extension: DomainExtension = {
+		start() {
+			// Nothing to start. Resolution is on demand and installs are operator
+			// commands, so loading the domain touches neither the network nor disk.
+			return undefined;
+		},
+	};
+	const contract: ToolchainContract = {
+		list() {
+			return PINNED_TOOLS;
+		},
+		get(id) {
+			return findPinnedTool(id);
+		},
+		resolve(name) {
+			return resolveToolBinary(name);
+		},
+		status(id) {
+			const entry = findPinnedTool(id);
+			return entry === null ? null : toolStatus(entry);
+		},
+		statuses() {
+			return toolStatuses();
+		},
+		async install(id: string, options: ToolInstallOptions = {}) {
+			// Imported lazily so the installer's archive readers stay out of every
+			// graph that only ever resolves a binary.
+			const { installTool } = await import("./install.js");
+			return installTool(id, options);
+		},
+		remove(id: string, options: ToolRemoveOptions = {}) {
+			// Statically imported, unlike install: removal is a readdir and an
+			// unlink, so it carries none of the archive readers that keep the
+			// installer off graphs which only ever resolve a binary.
+			return removeTool(id, options);
+		},
+	};
+	return { extension, contract };
+}

package/src/domains/toolchain/index.ts

@@ -0,0 +1,39 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import type { ToolchainContract } from "./contract.js";
+import { createToolchainBundle } from "./extension.js";
+import { ToolchainManifest } from "./manifest.js";
+
+export const ToolchainDomainModule: DomainModule<ToolchainContract> = {
+	manifest: ToolchainManifest,
+	createExtension: createToolchainBundle,
+};
+
+export type { ToolchainContract } from "./contract.js";
+export type { ToolFetcher, ToolInstallOptions, ToolInstallResult } from "./install.js";
+export { installPinnedTool, installTool } from "./install.js";
+export { ToolchainManifest } from "./manifest.js";
+export { toolchainRoot, toolVersionDir, vendoredBinaryPath } from "./paths.js";
+export { currentToolPlatform, findPinnedTool, findPinnedToolByBinary, PINNED_TOOLS } from "./registry.js";
+export type { ToolRemoveOptions, ToolRemoveResult } from "./remove.js";
+export { installedToolVersions, pruneSupersededVersions, removeTool, STALE_STAGING_MS } from "./remove.js";
+export {
+	describeFloorRejection,
+	describeResolution,
+	installRemedy,
+	resolveEntryBinary,
+	resolveToolBinary,
+	toolStatus,
+	toolStatuses,
+} from "./resolve.js";
+export type {
+	PinnedTool,
+	PinnedToolDocument,
+	PinnedToolDownload,
+	ToolArchiveKind,
+	ToolPathCandidate,
+	ToolPlatform,
+	ToolResolution,
+	ToolSource,
+	ToolStatus,
+} from "./types.js";
+export { compareVersions, parseVersion, resetVersionProbeCache, satisfiesMinimum } from "./version.js";