@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/observability/cost.ts

@@ -127,6 +127,7 @@ export interface UsageBreakdown {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	apiCalls?: number;
@@ -151,6 +152,7 @@ export interface CostEntry {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	apiCalls?: number;
 	/** Absent on an ordinary turn's call. */
@@ -215,6 +217,7 @@ export function createCostTracker(): CostTracker {
 				output,
 				cacheRead,
 				cacheWrite,
+				...(breakdown?.cacheWrite1h === undefined ? {} : { cacheWrite1h: breakdown.cacheWrite1h }),
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
 				...(label !== undefined ? { label } : {}),
@@ -224,6 +227,7 @@ export function createCostTracker(): CostTracker {
 			totals.output += output;
 			totals.cacheRead += cacheRead;
 			totals.cacheWrite += cacheWrite;
+			if (breakdown?.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + breakdown.cacheWrite1h;
 			totals.reasoningTokens += reasoningTokens;
 			totals.totalTokens += tokens;
 			return resolvedUsd;
@@ -247,6 +251,7 @@ export function createCostTracker(): CostTracker {
 			totals.output = 0;
 			totals.cacheRead = 0;
 			totals.cacheWrite = 0;
+			delete totals.cacheWrite1h;
 			totals.reasoningTokens = 0;
 			totals.totalTokens = 0;
 		},

package/src/domains/observability/extension.ts

@@ -64,6 +64,7 @@ function recordDispatchCost(
 			output: payload.outputTokenCount ?? 0,
 			cacheRead: payload.cacheReadTokenCount ?? 0,
 			cacheWrite: payload.cacheWriteTokenCount ?? 0,
+			...(payload.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1h: payload.cacheWrite1hTokenCount }),
 			reasoningTokens: payload.reasoningTokenCount ?? 0,
 			totalTokens: payload.tokenCount,
 		},

package/src/domains/observability/out-of-turn-usage.ts

@@ -78,6 +78,7 @@ export interface OutOfTurnUsage {
 	output: number | null;
 	cacheRead: number | null;
 	cacheWrite: number | null;
+	cacheWrite1h?: number | null;
 	reasoning: number | null;
 	totalTokens: number | null;
 	costUsd: number | null;
@@ -253,6 +254,7 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 			output: reading(usage.output),
 			cacheRead: reading(usage.cacheRead),
 			cacheWrite: reading(usage.cacheWrite),
+			...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: nullableNumber(usage.cacheWrite1h) }),
 			reasoning: reading(usage.reasoning),
 			totalTokens: reading(usage.totalTokens),
 			costUsd: reading(usage.costUsd),

package/src/domains/observability/trace-store.ts

@@ -202,6 +202,7 @@ export interface TraceSpendInput {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	inputCostUsd?: number | null;
@@ -234,6 +235,7 @@ export interface SessionTurnUsage {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd?: number | null;
@@ -363,6 +365,7 @@ export interface TracePhaseRow {
 	output_tokens: number | null;
 	cache_read_tokens: number | null;
 	cache_write_tokens: number | null;
+	cache_write_1h_tokens?: number | null;
 	reasoning_tokens: number | null;
 	total_tokens: number | null;
 	input_cost_usd: number | null;
@@ -443,7 +446,7 @@ CREATE TABLE phases (
   error TEXT,
   started_at TEXT,
   ended_at TEXT,
-  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER,
+  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER, cache_write_1h_tokens INTEGER,
   reasoning_tokens INTEGER, total_tokens INTEGER,
   input_cost_usd REAL, output_cost_usd REAL, cache_read_cost_usd REAL, cache_write_cost_usd REAL,
   total_cost_usd REAL,
@@ -544,6 +547,13 @@ function ensureRunSourceColumn(db: DatabaseSync): void {
 	db.prepare("UPDATE runs SET source = 'session' WHERE assignment_id = ?").run(SESSION_TRACE_ASSIGNMENT_ID);
 }
 
+/** Missing lifetime detail stays NULL in older traces; it cannot be reconstructed. */
+function ensureCacheWriteLifetimeColumn(db: DatabaseSync): void {
+	const columns = db.prepare("PRAGMA table_info(phases)").all() as { name: string }[];
+	if (!columns.some((column) => column.name === "cache_write_1h_tokens"))
+		db.exec("ALTER TABLE phases ADD COLUMN cache_write_1h_tokens INTEGER;");
+}
+
 /**
  * Finalize `running` rows whose recorded owner is on this host and provably
  * dead (pid gone, or alive under a different birth token, i.e. reused). Rows
@@ -591,6 +601,7 @@ export class TraceStore {
 		this.transaction(() => {
 			ensureProcessOwnerColumns(this.db);
 			ensureRunSourceColumn(this.db);
+			ensureCacheWriteLifetimeColumn(this.db);
 			reconcileAbandonedRuns(this.db);
 		});
 	}
@@ -799,7 +810,7 @@ export class TraceStore {
 	recordSpend(input: TraceSpendInput): void {
 		this.transaction(() => {
 			this.db
-				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?,
+				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?,
           reasoning_tokens=?, total_tokens=?, input_cost_usd=?, output_cost_usd=?, cache_read_cost_usd=?,
           cache_write_cost_usd=?, total_cost_usd=?, context_tokens=?, context_window=? WHERE phase_id=? AND run_id=?`)
 				.run(
@@ -807,6 +818,7 @@ export class TraceStore {
 					input.outputTokens,
 					input.cacheReadTokens,
 					input.cacheWriteTokens,
+					input.cacheWrite1hTokens ?? null,
 					input.reasoningTokens,
 					input.totalTokens,
 					input.inputCostUsd ?? null,
@@ -982,7 +994,7 @@ export class TraceStore {
 				);
 			this.db
 				.prepare(`UPDATE phases SET status=?, attempt=?, retries=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					success ? "success" : "fail",
@@ -994,6 +1006,7 @@ export class TraceStore {
 					input.outputTokenCount ?? null,
 					input.cacheReadTokenCount ?? null,
 					input.cacheWriteTokenCount ?? null,
+					input.cacheWrite1hTokenCount ?? null,
 					input.reasoningTokenCount ?? null,
 					input.tokenCount ?? null,
 					input.costUsd ?? null,
@@ -1113,7 +1126,7 @@ export class TraceStore {
 				.run(input.status, input.at, usage?.totalTokens ?? null, usage?.costUsd ?? null, input.runId);
 			this.db
 				.prepare(`UPDATE phases SET status=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					input.status,
@@ -1123,6 +1136,7 @@ export class TraceStore {
 					usage?.outputTokens ?? null,
 					usage?.cacheReadTokens ?? null,
 					usage?.cacheWriteTokens ?? null,
+					usage?.cacheWrite1hTokens ?? null,
 					usage?.reasoningTokens ?? null,
 					usage?.totalTokens ?? null,
 					usage?.costUsd ?? null,
@@ -1186,13 +1200,24 @@ function traceDatabaseFootprintBytes(path: string): number {
 	return total;
 }
 
+export interface TraceRunCursor {
+	startedAt: string;
+	runId: string;
+}
+
+export interface TraceRunsPageOptions {
+	before?: TraceRunCursor;
+	limit?: number;
+	filter?: { source?: TraceRunRow["source"]; status?: TraceRunRow["status"]; q?: string };
+}
+
 export class TraceReader {
 	readonly db: DatabaseSync;
 	/**
 	 * `runs.source` is an additive column (see ensureRunSourceColumn) a
 	 * TraceStore writer backfills in place. A read-only reader can open a
 	 * database no writer has touched since before the column existed — the
-	 * trace viewer opening a dormant install's trace.sqlite fresh is the
+	 * web application opening a dormant install's trace.sqlite fresh is the
 	 * realistic case — and cannot ALTER TABLE to fix that itself, so it
 	 * derives the same value the migration would have written instead.
 	 */
@@ -1223,6 +1248,40 @@ export class TraceReader {
 			.all(clampInt(limit, 1, 500)) as unknown as TraceRunRow[];
 	}
 
+	/** Stable keyset pagination, including read-only databases predating runs.source. */
+	runsPage({ before, limit = 50, filter = {} }: TraceRunsPageOptions = {}): {
+		runs: TraceRunRow[];
+		nextBefore: TraceRunCursor | null;
+	} {
+		const size = clampInt(limit, 1, 500);
+		const where: string[] = [],
+			args: SQLInputValue[] = [];
+		if (before) {
+			where.push("(started_at < ? OR (started_at = ? AND run_id < ?))");
+			args.push(before.startedAt, before.startedAt, before.runId);
+		}
+		if (filter.source) {
+			where.push("source = ?");
+			args.push(filter.source);
+		}
+		if (filter.status) {
+			where.push("status = ?");
+			args.push(filter.status);
+		}
+		if (filter.q) {
+			where.push("(run_id LIKE ? OR agent LIKE ? OR model LIKE ? OR status LIKE ? OR request LIKE ?)");
+			args.push(...Array<string>(5).fill(`%${filter.q}%`));
+		}
+		const rows = this.db
+			.prepare(
+				`SELECT * FROM (SELECT ${this.runsSourceExpr} FROM runs) ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY started_at DESC, run_id DESC LIMIT ?`,
+			)
+			.all(...args, size + 1) as unknown as TraceRunRow[];
+		const runs = rows.slice(0, size),
+			last = runs.at(-1);
+		return { runs, nextBefore: rows.length > size && last ? { startedAt: last.started_at, runId: last.run_id } : null };
+	}
+
 	run(runId: string): TraceRunRow | null {
 		return (
 			(this.db.prepare(`SELECT ${this.runsSourceExpr} FROM runs WHERE run_id=?`).get(runId) as unknown as
@@ -1567,6 +1626,7 @@ function terminalUsage(input: DispatchCompletedPayload | DispatchFailedPayload):
 		output: input.outputTokenCount ?? 0,
 		cache_read: input.cacheReadTokenCount ?? 0,
 		cache_write: input.cacheWriteTokenCount ?? 0,
+		...(input.cacheWrite1hTokenCount === undefined ? {} : { cache_write_1h: input.cacheWrite1hTokenCount }),
 		reasoning_tokens: input.reasoningTokenCount ?? 0,
 		total_tokens: input.tokenCount,
 	};

package/src/domains/plugins/catalog.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { buildSafeToolEnv } from "../../core/safe-exec.js";
+import { isSemanticVersion } from "../extensions/compatibility.js";
+import {
+	isLibraryKind,
+	isLibraryResourceKind,
+	LIBRARY_PROVIDES_LIMITS,
+	type LibraryPackageEntry,
+	type LibraryProvidedResource,
+	type LibraryRequirementRef,
+} from "../resources/library-types.js";
+import { isPluginId } from "./discovery.js";
+
+export type PluginCatalogEntry = LibraryPackageEntry;
+
+export interface PluginSource {
+	root: string;
+	cleanup: () => void;
+}
+
+/** Explicit GitHub tree URLs identify both the revision and the bundle directory. */
+export function parsePluginGithubSource(source: string): { url: string; ref: string; subdir: string } | undefined {
+	const match =
+		/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/tree\/([A-Za-z0-9_.-]+)(?:\/(.*?))?\/?$/.exec(source);
+	if (!match?.[1] || !match[2] || !match[3]) return undefined;
+	const subdir = match[4] ?? "";
+	if (subdir.split("/").some((part) => part === ".." || part === ".") || subdir.includes("\\") || subdir.includes("\0"))
+		return undefined;
+	return { url: `https://github.com/${match[1]}/${match[2]}.git`, ref: match[3], subdir };
+}
+
+export function pluginLocalPath(source: string, cwd = process.cwd()): string {
+	return path.resolve(cwd, source.startsWith("~/") ? path.join(homedir(), source.slice(2)) : source);
+}
+
+/** The same bounded, vector-only Git transport used by the skill installer. */
+export function fetchPluginSource(source: string, cwd = process.cwd()): PluginSource {
+	const local = pluginLocalPath(source, cwd);
+	if (existsSync(local)) return { root: local, cleanup: () => {} };
+	const remote = parsePluginGithubSource(source);
+	if (!remote)
+		throw new Error(
+			`unsupported plugin source: ${source}; use a local directory or https://github.com/owner/repo/tree/ref/path`,
+		);
+	const temp = mkdtempSync(path.join(tmpdir(), "clio-coder-plugin-"));
+	const cleanup = (): void => rmSync(temp, { recursive: true, force: true });
+	try {
+		execFileSync(
+			"git",
+			["-c", "core.hooksPath=/dev/null", "clone", "--depth", "1", "--branch", remote.ref, "--", remote.url, temp],
+			{
+				stdio: "pipe",
+				timeout: 120_000,
+				maxBuffer: 1_000_000,
+				env: buildSafeToolEnv({ GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" }),
+			},
+		);
+		const root = path.join(temp, remote.subdir);
+		if (!existsSync(root) || !statSync(root).isDirectory())
+			throw new Error(`plugin source has no directory ${remote.subdir || "."}: ${source}`);
+		const relative = path.relative(realpathSync(temp), realpathSync(root));
+		if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+			throw new Error("plugin source escapes repository");
+		// Repository metadata is transport state, not part of a root-level package.
+		if (!remote.subdir) rmSync(path.join(temp, ".git"), { recursive: true, force: true });
+		return { root, cleanup };
+	} catch (error) {
+		cleanup();
+		throw error;
+	}
+}
+
+const PROVIDED_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/**
+ * Parse optional `provides` hints. A malformed hint list is dropped with a
+ * diagnostic and the row stays valid: hints support discovery, never admission,
+ * so a bad hint must not hide an otherwise installable package.
+ */
+function providedResources(value: unknown, name: string, diagnostics: string[]): LibraryProvidedResource[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.length > LIBRARY_PROVIDES_LIMITS.entries) {
+		diagnostics.push(`library index provides ignored (not a bounded list): ${name}`);
+		return undefined;
+	}
+	const hints: LibraryProvidedResource[] = [];
+	const seen = new Set<string>();
+	for (const raw of value) {
+		const item = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : undefined;
+		if (
+			!item ||
+			!isLibraryResourceKind(item.kind) ||
+			typeof item.name !== "string" ||
+			item.name.length > LIBRARY_PROVIDES_LIMITS.name ||
+			!PROVIDED_NAME.test(item.name) ||
+			(item.description !== undefined &&
+				(typeof item.description !== "string" || item.description.length > LIBRARY_PROVIDES_LIMITS.description))
+		) {
+			diagnostics.push(`library index provides ignored (malformed hint): ${name}`);
+			return undefined;
+		}
+		const key = `${item.kind}:${item.name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		hints.push({
+			kind: item.kind,
+			name: item.name,
+			...(typeof item.description === "string" ? { description: item.description } : {}),
+		});
+	}
+	return hints;
+}
+
+export function readPluginCatalog(file: string, diagnostics: string[]): LibraryPackageEntry[] {
+	if (!existsSync(file)) return [];
+	try {
+		const parsed: unknown = parseYaml(readFileSync(file, "utf8"));
+		const rows: unknown[] | undefined = Array.isArray(parsed)
+			? parsed
+			: parsed && typeof parsed === "object" && Array.isArray((parsed as { entries?: unknown }).entries)
+				? (parsed as { entries: unknown[] }).entries
+				: undefined;
+		if (!rows) throw new Error("library index must be a list or contain an entries list");
+		return rows.flatMap((row): LibraryPackageEntry[] => {
+			if (!row || typeof row !== "object") {
+				diagnostics.push(`library index entry malformed: ${file}`);
+				return [];
+			}
+			const item = row as Record<string, unknown>;
+			if (
+				!isLibraryKind(item.kind) ||
+				typeof item.name !== "string" ||
+				!isPluginId(item.name) ||
+				typeof item.description !== "string" ||
+				typeof item.sourceUrl !== "string" ||
+				item.sourceUrl.trim().length === 0 ||
+				!isSemanticVersion(item.version) ||
+				typeof item.sha256 !== "string" ||
+				!/^[a-f0-9]{64}$/.test(item.sha256)
+			) {
+				diagnostics.push(
+					`library index entry requires name, description, sourceUrl, version, and full-tree sha256: ${String(item.name ?? file)}`,
+				);
+				return [];
+			}
+			if (
+				item.requires !== undefined &&
+				(!Array.isArray(item.requires) || item.requires.some((ref) => typeof ref !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${item.name}`);
+				return [];
+			}
+			const remote = /^(?:[a-z][a-z0-9+.-]*:\/\/|git@)/i.test(item.sourceUrl);
+			if (remote && !parsePluginGithubSource(item.sourceUrl)) {
+				diagnostics.push(`unsupported library index source: ${item.sourceUrl}`);
+				return [];
+			}
+			const provides = providedResources(item.provides, item.name, diagnostics);
+			return [
+				{
+					kind: item.kind,
+					name: item.name,
+					description: item.description,
+					sourceUrl: remote ? item.sourceUrl : path.resolve(path.dirname(file), item.sourceUrl),
+					version: item.version,
+					sha256: item.sha256,
+					origin: "catalog",
+					...(typeof item.category === "string" ? { category: item.category } : {}),
+					...(["pass", "warn", "fail", "unknown"].includes(String(item.audit))
+						? { audit: item.audit as NonNullable<LibraryPackageEntry["audit"]> }
+						: {}),
+					...(Array.isArray(item.triggers)
+						? { triggers: item.triggers.filter((value): value is string => typeof value === "string") }
+						: {}),
+					...(Array.isArray(item.requires) ? { requires: item.requires as LibraryRequirementRef[] } : {}),
+					...(provides ? { provides } : {}),
+					index: path.resolve(file),
+				},
+			];
+		});
+	} catch (error) {
+		diagnostics.push(`library index unreadable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}
+
+/** The index shipped inside this Clio-Coder package; rows from it are the only "bundled" evidence. */
+export function bundledLibraryIndexPath(): string {
+	return path.join(resolvePackageRoot(), "library", "registry.yaml");
+}
+
+export function bundledPluginCatalog(diagnostics: string[]): LibraryPackageEntry[] {
+	try {
+		return readPluginCatalog(bundledLibraryIndexPath(), diagnostics);
+	} catch (error) {
+		diagnostics.push(`library index unavailable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}

package/src/domains/plugins/contract.ts

@@ -0,0 +1,24 @@
+import type { DomainContract } from "../../core/domain-loader.js";
+import type {
+	InstalledPlugin,
+	PluginCandidate,
+	PluginInstallOptions,
+	PluginListOptions,
+	PluginMutationResult,
+	PluginResourceKind,
+	PluginResourceRoot,
+	PluginSnapshot,
+} from "./types.js";
+
+export interface PluginsContract extends DomainContract {
+	list(cwd?: string, options?: PluginListOptions): InstalledPlugin[];
+	discover(root: string): PluginCandidate[];
+	install(source: string, options?: PluginInstallOptions): PluginMutationResult;
+	update(id: string, options?: PluginInstallOptions): PluginMutationResult;
+	enable(id: string, options?: PluginListOptions): PluginMutationResult;
+	disable(id: string, options?: PluginListOptions): PluginMutationResult;
+	remove(id: string, options?: PluginListOptions): PluginMutationResult;
+	resourceRoots(kind: PluginResourceKind, cwd?: string): PluginResourceRoot[];
+	snapshot(cwd?: string): PluginSnapshot;
+	reload(cwd?: string): PluginSnapshot;
+}