@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/scheduling/cluster.ts

@@ -0,0 +1,175 @@
+/**
+ * Fleet node registry: N machines become one addressable, pinnable capacity
+ * pool. Node configuration comes from `fleet.nodes` in settings (read fresh
+ * on every call so settings edits apply next dispatch); runtime state
+ * (channel health and last-seen observations) lives here. Durable capacity
+ * and admission draining are owned by the dispatch admission store.
+ *
+ * State semantics:
+ *   - online   channel healthy as far as this registry knows. Nodes start
+ *              online; dispatch eligibility additionally requires a passing
+ *              doctor preflight (durable, checked at placement).
+ *   - offline  classified dead after consecutive channel failures. Placement
+ *              skips it; its in-flight runs are reaped for reroute by the
+ *              dispatch domain. A later channel success restores it.
+ *
+ * Staleness is advisory: `lastSeenAt` records the last probe or worker
+ * heartbeat, but an idle node is never auto-offlined for silence, because no
+ * signal is expected from a node with no work.
+ */
+
+import type { FleetNodeSettings } from "../../core/defaults.js";
+
+export type FleetNodeState = "online" | "offline";
+
+export interface FleetNodeSnapshot {
+	id: string;
+	host: string;
+	kind: "local" | "ssh";
+	state: FleetNodeState;
+	stateReason: string | null;
+	activeWorkers: number;
+	maxWorkers: number;
+	labels: ReadonlyArray<string>;
+	lastSeenAt: string | null;
+}
+
+export interface FleetRegistry {
+	/** True when at least one remote node is configured. */
+	hasRemoteNodes(): boolean;
+	/** All nodes, implicit local first, then declaration order. */
+	list(): FleetNodeSnapshot[];
+	get(id: string): FleetNodeSnapshot | null;
+	/** Raw settings entry for a remote node; null for local/unknown ids. */
+	config(id: string): FleetNodeSettings | null;
+	/** Record a probe or worker heartbeat for staleness display. */
+	seen(id: string): void;
+	/**
+	 * Channel failure accounting. Consecutive failures at or beyond the death
+	 * threshold classify the node offline. Returns the resulting state.
+	 */
+	recordChannelFailure(id: string, reason: string): FleetNodeState;
+	recordChannelSuccess(id: string): void;
+	/**
+	 * Attach the durable per-node usage source. The dispatch domain owns the
+	 * capacity leases, so it binds the reader once at bundle construction; until
+	 * then a snapshot reports zero rather than inventing a process-local count.
+	 */
+	bindActiveWorkers(source: (nodeId: string) => number): void;
+}
+
+export const LOCAL_NODE_ID = "local";
+
+/** Consecutive channel failures before a node is classified dead. */
+const NODE_DEATH_FAILURE_THRESHOLD = 2;
+
+interface NodeRuntimeState {
+	state: FleetNodeState;
+	stateReason: string | null;
+	consecutiveFailures: number;
+	lastSeenMs: number | null;
+}
+
+export interface FleetRegistryOptions {
+	now?: () => number;
+	/** Display-only cap for the implicit local node. */
+	localMaxWorkers?: () => number;
+	/** Durable lease-derived usage; never a process-local counter. */
+	activeWorkers?: (nodeId: string) => number;
+}
+
+function freshState(): NodeRuntimeState {
+	return { state: "online", stateReason: null, consecutiveFailures: 0, lastSeenMs: null };
+}
+
+export function createFleetRegistry(
+	getNodes: () => ReadonlyArray<FleetNodeSettings>,
+	options?: FleetRegistryOptions,
+): FleetRegistry {
+	const now = options?.now ?? (() => Date.now());
+	const runtime = new Map<string, NodeRuntimeState>();
+	let activeWorkers = options?.activeWorkers;
+
+	function stateFor(id: string): NodeRuntimeState {
+		let state = runtime.get(id);
+		if (!state) {
+			state = freshState();
+			runtime.set(id, state);
+		}
+		return state;
+	}
+
+	function snapshotFor(id: string, config: FleetNodeSettings | null): FleetNodeSnapshot {
+		const state = stateFor(id);
+		if (config === null) {
+			return {
+				id: LOCAL_NODE_ID,
+				host: "localhost",
+				kind: "local",
+				state: state.state,
+				stateReason: state.stateReason,
+				activeWorkers: activeWorkers?.(LOCAL_NODE_ID) ?? 0,
+				maxWorkers: options?.localMaxWorkers?.() ?? Number.POSITIVE_INFINITY,
+				labels: [],
+				lastSeenAt: state.lastSeenMs !== null ? new Date(state.lastSeenMs).toISOString() : null,
+			};
+		}
+		return {
+			id: config.id,
+			host: config.host,
+			kind: "ssh",
+			state: state.state,
+			stateReason: state.stateReason,
+			activeWorkers: activeWorkers?.(id) ?? 0,
+			maxWorkers: config.maxWorkers,
+			labels: [...(config.labels ?? [])],
+			lastSeenAt: state.lastSeenMs !== null ? new Date(state.lastSeenMs).toISOString() : null,
+		};
+	}
+
+	function findConfig(id: string): FleetNodeSettings | null {
+		return getNodes().find((node) => node.id === id) ?? null;
+	}
+
+	return {
+		hasRemoteNodes() {
+			return getNodes().length > 0;
+		},
+		list() {
+			return [snapshotFor(LOCAL_NODE_ID, null), ...getNodes().map((node) => snapshotFor(node.id, node))];
+		},
+		get(id) {
+			if (id === LOCAL_NODE_ID) return snapshotFor(LOCAL_NODE_ID, null);
+			const config = findConfig(id);
+			return config ? snapshotFor(id, config) : null;
+		},
+		config(id) {
+			return id === LOCAL_NODE_ID ? null : findConfig(id);
+		},
+		seen(id) {
+			stateFor(id).lastSeenMs = now();
+		},
+		recordChannelFailure(id, reason) {
+			const state = stateFor(id);
+			state.consecutiveFailures += 1;
+			if (state.state === "online" && state.consecutiveFailures >= NODE_DEATH_FAILURE_THRESHOLD) {
+				state.state = "offline";
+				state.stateReason = `classified dead after ${state.consecutiveFailures} consecutive channel failures (${reason})`;
+			}
+			return state.state;
+		},
+		bindActiveWorkers(source) {
+			activeWorkers = source;
+		},
+		recordChannelSuccess(id) {
+			const state = stateFor(id);
+			state.consecutiveFailures = 0;
+			state.lastSeenMs = now();
+			if (state.state === "offline") {
+				// A node that just completed a run over its channel is alive again.
+				state.state = "online";
+				state.stateReason = null;
+			}
+		},
+	};
+}

package/src/domains/scheduling/contract.ts

@@ -0,0 +1,30 @@
+import type { BudgetVerdict } from "./budget.js";
+import type { FleetRegistry } from "./cluster.js";
+
+export interface BudgetPreflight {
+	verdict: BudgetVerdict;
+	currentUsd: number;
+	ceilingUsd: number;
+}
+
+export interface SchedulingContract {
+	ceilingUsd(): number;
+	checkCeiling(currentUsd: number): BudgetVerdict;
+	raiseCeiling(newUsd: number): void;
+	/**
+	 * Evaluate the running session cost against the ceiling. Scheduling owns the
+	 * observability lookup so callers (notably dispatch) don't need to import it.
+	 * Verdict is "under" when spend is below the ceiling, "at" when equal, "over"
+	 * when above. Dispatch treats "at" and "over" as admission failures.
+	 */
+	preflight(): BudgetPreflight;
+	/** Configured global worker capacity; durable leases own active usage. */
+	maxWorkers(): number;
+	/**
+	 * Fleet node registry backing multi-node placement: per-node states,
+	 * capacity accounting, and channel-failure classification. Optional so
+	 * minimal scheduling stubs remain valid; dispatch treats absence as a
+	 * local-only fleet.
+	 */
+	fleet?: FleetRegistry;
+}

package/src/domains/scheduling/extension.ts

@@ -0,0 +1,91 @@
+/**
+ * Scheduling domain wire-up. Seeds budget + concurrency state from settings and
+ * listens to dispatch.enqueued so it can fire budget.alert events when session
+ * spend meets or crosses the ceiling. Dispatch admission preflights this state
+ * and denies new dispatches at or over the ceiling; the alert is the TUI's
+ * explanation of those denials.
+ */
+
+import { type BudgetAlertPayload, BusChannels } from "../../core/bus-events.js";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import type { ConfigContract } from "../config/contract.js";
+import type { ObservabilityContract } from "../observability/contract.js";
+import { createBudgetState } from "./budget.js";
+import { createFleetRegistry } from "./cluster.js";
+import type { SchedulingContract } from "./contract.js";
+
+const DEFAULT_MAX_WORKERS = 4;
+
+function resolveMaxWorkers(concurrency: "auto" | number): number {
+	if (concurrency === "auto") return DEFAULT_MAX_WORKERS;
+	return Math.max(1, concurrency);
+}
+
+export function createSchedulingBundle(context: DomainContext): DomainBundle<SchedulingContract> {
+	const maybeConfig = context.getContract<ConfigContract>("config");
+	if (!maybeConfig) throw new Error("scheduling domain requires 'config' contract");
+	const config: ConfigContract = maybeConfig;
+	const observability = context.getContract<ObservabilityContract>("observability");
+
+	const settings = config.get();
+	let budget = createBudgetState(settings.budget.sessionCeilingUsd);
+	const fleet = createFleetRegistry(() => config.get().fleet?.nodes ?? [], {
+		localMaxWorkers: () => resolveMaxWorkers(config.get().budget.concurrency),
+	});
+	const unsubscribes: Array<() => void> = [];
+
+	function syncBudget(): void {
+		const nextCeiling = config.get().budget.sessionCeilingUsd;
+		if (nextCeiling === budget.ceilingUsd) return;
+		budget = createBudgetState(nextCeiling);
+	}
+
+	function evaluate(): { verdict: ReturnType<typeof budget.checkCeiling>; currentUsd: number } {
+		syncBudget();
+		const currentUsd = observability?.sessionCost() ?? 0;
+		return { verdict: budget.checkCeiling(currentUsd), currentUsd };
+	}
+
+	const extension: DomainExtension = {
+		async start() {
+			unsubscribes.push(
+				context.bus.on(BusChannels.DispatchEnqueued, () => {
+					const { verdict, currentUsd } = evaluate();
+					if (verdict !== "under") {
+						context.bus.emit(BusChannels.BudgetAlert, {
+							level: verdict,
+							currentUsd,
+							ceilingUsd: budget.ceilingUsd,
+						} satisfies BudgetAlertPayload);
+					}
+				}),
+			);
+		},
+		async stop() {
+			for (const off of unsubscribes) off();
+			unsubscribes.length = 0;
+		},
+	};
+
+	const contract: SchedulingContract = {
+		ceilingUsd: () => {
+			syncBudget();
+			return budget.ceilingUsd;
+		},
+		checkCeiling: (current) => {
+			syncBudget();
+			return budget.checkCeiling(current);
+		},
+		raiseCeiling: (next) => {
+			budget = createBudgetState(next);
+		},
+		preflight: () => {
+			const { verdict, currentUsd } = evaluate();
+			return { verdict, currentUsd, ceilingUsd: budget.ceilingUsd };
+		},
+		maxWorkers: () => resolveMaxWorkers(config.get().budget.concurrency),
+		fleet,
+	};
+
+	return { extension, contract };
+}

package/src/domains/scheduling/index.ts

@@ -0,0 +1,12 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createSchedulingBundle } from "./extension.js";
+import { SchedulingManifest } from "./manifest.js";
+
+export const SchedulingDomainModule: DomainModule = {
+	manifest: SchedulingManifest,
+	createExtension: createSchedulingBundle,
+};
+
+export type { BudgetVerdict } from "./budget.js";
+export type { SchedulingContract } from "./contract.js";
+export { SchedulingManifest } from "./manifest.js";

package/src/domains/scheduling/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const SchedulingManifest: DomainManifest = {
+	name: "scheduling",
+	dependsOn: ["config", "observability"],
+};

package/src/domains/session/archive-readers.ts

@@ -0,0 +1,208 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isSessionEntry, isSessionHeader, type SessionEntry } from "./index.js";
+
+/**
+ * Shared read-only readers over the local usage archive: the per-day audit
+ * JSONL files and the per-session ledger files under the state dir. Evidence
+ * building and the cross-session usage report both consume these; they were
+ * factored out of evidence/build.ts so the parsers exist exactly once.
+ *
+ * The module lives in the session domain because that is its only dependency,
+ * and it is re-exported from the session index so consumers reach it through
+ * the barrel. It used to live under observability, where the barrel could not
+ * be used: the observability extension imports the evidence domain, so an
+ * evidence-side import through the observability index would cycle.
+ */
+
+export interface AuditJsonRow {
+	file: string;
+	line: number;
+	row: Record<string, unknown>;
+	ts: string | null;
+	auditKind: string;
+	correlationId: string;
+}
+
+export interface AuditReadResult {
+	rows: AuditJsonRow[];
+	errors: string[];
+}
+
+export interface SessionReadResult {
+	entries: SessionEntry[];
+	missing: boolean;
+	errors: string[];
+}
+
+/** A discovered session ledger file under <stateDir>/sessions/. */
+export interface SessionLedgerRef {
+	cwdHash: string;
+	sessionId: string;
+	path: string;
+}
+
+/**
+ * Read every `<stateDir>/audit/<date>.jsonl` row. Malformed lines are skipped
+ * and reported in `errors` instead of failing the read.
+ */
+export async function readAuditRows(stateDir: string): Promise<AuditReadResult> {
+	const root = join(stateDir, "audit");
+	let files: string[];
+	try {
+		files = await readdir(root);
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return { rows: [], errors: [] };
+		return { rows: [], errors: [`audit root read error: ${err.message ?? String(err)}`] };
+	}
+	const rows: AuditJsonRow[] = [];
+	const errors: string[] = [];
+	for (const file of files.filter((name) => name.endsWith(".jsonl")).sort(compareStrings)) {
+		const path = join(root, file);
+		let raw: string;
+		try {
+			raw = await readFile(path, "utf8");
+		} catch (error) {
+			const err = error as NodeJS.ErrnoException;
+			errors.push(`${path}: ${err.message ?? String(err)}`);
+			continue;
+		}
+		const lines = raw.split("\n");
+		for (let index = 0; index < lines.length; index += 1) {
+			const line = lines[index];
+			if (line === undefined || line.length === 0) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line) as unknown;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				errors.push(`${path}:${index + 1}: invalid JSON: ${message}`);
+				continue;
+			}
+			if (!isRecord(parsed)) {
+				errors.push(`${path}:${index + 1}: expected object`);
+				continue;
+			}
+			const auditKind = readOptionalString(parsed.kind) ?? "tool_call";
+			rows.push({
+				file,
+				line: index + 1,
+				row: parsed,
+				ts: readOptionalString(parsed.ts),
+				auditKind,
+				correlationId: readOptionalString(parsed.correlationId) ?? "",
+			});
+		}
+	}
+	return { rows, errors };
+}
+
+/**
+ * Find and parse the ledger for one session id by scanning the cwd-hash
+ * directories. `missing` is true when no ledger exists anywhere.
+ */
+export async function readSessionEntriesForId(stateDir: string, sessionId: string): Promise<SessionReadResult> {
+	const root = join(stateDir, "sessions");
+	let cwdHashes: string[];
+	try {
+		cwdHashes = await readdir(root);
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") return { entries: [], missing: true, errors: [] };
+		return { entries: [], missing: false, errors: [`session root read error: ${err.message ?? String(err)}`] };
+	}
+	for (const cwdHash of cwdHashes.sort(compareStrings)) {
+		const currentPath = join(root, cwdHash, sessionId, "current.jsonl");
+		let raw: string;
+		let source = currentPath;
+		try {
+			raw = await readFile(currentPath, "utf8");
+		} catch (error) {
+			const err = error as NodeJS.ErrnoException;
+			if (err.code === "ENOENT") {
+				const tmpPath = `${currentPath}.tmp`;
+				try {
+					raw = await readFile(tmpPath, "utf8");
+					source = tmpPath;
+				} catch {
+					continue;
+				}
+			} else if (err.code === "ENOTDIR") {
+				continue;
+			} else {
+				return { entries: [], missing: false, errors: [`${currentPath}: ${err.message ?? String(err)}`] };
+			}
+		}
+		return parseSessionEntries(raw, source);
+	}
+	return { entries: [], missing: true, errors: [] };
+}
+
+/** Parse a session ledger containing a header and structured entries. */
+export function parseSessionEntries(raw: string, source: string): SessionReadResult {
+	const entries: SessionEntry[] = [];
+	const errors: string[] = [];
+	const lines = raw.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (line === undefined || line.trim().length === 0) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line) as unknown;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			errors.push(`${source}:${index + 1}: invalid JSON: ${message}`);
+			continue;
+		}
+		if (isSessionHeader(parsed)) continue;
+		if (isSessionEntry(parsed)) {
+			entries.push(parsed);
+			continue;
+		}
+		errors.push(
+			`session ledger contains an unreadable entry (missing kind discriminant): ${source}. Remove or compact the session to reset.`,
+		);
+	}
+	return { entries, missing: false, errors };
+}
+
+/**
+ * Enumerate every session ledger under `<stateDir>/sessions/`, optionally
+ * restricted to one cwd hash. Read-only; missing roots yield an empty list.
+ */
+export async function listSessionLedgerRefs(stateDir: string, onlyCwdHash?: string): Promise<SessionLedgerRef[]> {
+	const root = join(stateDir, "sessions");
+	let cwdHashes: string[];
+	try {
+		cwdHashes = await readdir(root);
+	} catch {
+		return [];
+	}
+	const refs: SessionLedgerRef[] = [];
+	for (const cwdHash of cwdHashes.sort(compareStrings)) {
+		if (onlyCwdHash !== undefined && cwdHash !== onlyCwdHash) continue;
+		let sessionIds: string[];
+		try {
+			sessionIds = await readdir(join(root, cwdHash));
+		} catch {
+			continue;
+		}
+		for (const sessionId of sessionIds.sort(compareStrings)) {
+			refs.push({ cwdHash, sessionId, path: join(root, cwdHash, sessionId, "current.jsonl") });
+		}
+	}
+	return refs;
+}
+
+function readOptionalString(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}

package/src/domains/session/checkpoint.ts

@@ -0,0 +1,38 @@
+import { stateRootRemoved } from "../../core/xdg.js";
+import { atomicWrite, sessionPaths } from "../../engine/session.js";
+import type { SessionMeta } from "./contract.js";
+import type { SessionManagerState } from "./manager.js";
+
+/**
+ * Three-stage atomic checkpoint:
+ *  1. current.jsonl appends are fsync'd by writer.persistTree() (the engine
+ *     writer debounces fsync between checkpoints).
+ *  2. tree.json is written via writer.persistTree() (atomicWrite under the hood).
+ *  3. meta.json is rewritten with lastCheckpointAt / lastCheckpointReason via
+ *     atomicWrite so the on-disk marker survives crashes.
+ *
+ * The engine writer closes over the same meta reference we hold in
+ * SessionManagerState.meta. Mutating it here keeps the writer's eventual
+ * close() in sync with the checkpoint-enriched fields.
+ *
+ * Nothing is written, and no checkpoint is claimed in memory, once `clio
+ * uninstall` has taken the state root away. The check sits before
+ * `sessionPaths()`, which mkdirs the session directory and so rebuilds the
+ * whole root on its way to a meta.json the operator just deleted. This is the
+ * writer that undid an uninstall roughly two minutes after it reported success,
+ * leaving behind a root holding meta.json and tree.json with
+ * `lastCheckpointReason: shutdown`.
+ */
+export async function performCheckpoint(state: SessionManagerState, reason?: string): Promise<void> {
+	await state.writer.persistTree();
+	if (stateRootRemoved()) return;
+	const paths = sessionPaths(state.meta);
+	const at = new Date().toISOString();
+	const enriched: SessionMeta = {
+		...state.meta,
+		lastCheckpointAt: at,
+		lastCheckpointReason: reason ?? null,
+	};
+	atomicWrite(paths.meta, JSON.stringify(enriched, null, 2));
+	Object.assign(state.meta, enriched);
+}

package/src/domains/session/compaction/auto.ts

@@ -0,0 +1,89 @@
+/**
+ * Auto-compaction trigger.
+ *
+ * Pure pressure check + in-flight-debounced runner used by the chat-loop
+ * before every assistant request. `shouldCompact` reports whether the current
+ * context pressure crossed the single compaction threshold; the
+ * `AutoCompactionTrigger` wraps the actual task so two concurrent chat
+ * submissions cannot spawn overlapping compaction runs on the same session.
+ *
+ * Kept deliberately small so the chat-loop can call it on the hot path
+ * without new allocations per turn. No I/O here. The caller injects the work
+ * via `fire(task)`.
+ */
+
+export interface ContextCompactionVerdict {
+	shouldCompact: boolean;
+	pressure: number | null;
+	contextTokens: number;
+	contextWindow: number;
+	threshold: number;
+}
+
+export const DEFAULT_COMPACTION_THRESHOLD = 0.8;
+
+/**
+ * Report whether `contextTokens / contextWindow` crossed `threshold`.
+ * Defensive behavior:
+ *   - non-positive or NaN contextWindow returns a no-op verdict.
+ *   - thresholds outside (0, 1] disable the trigger.
+ */
+export function shouldCompact(
+	contextTokens: number,
+	threshold: number,
+	contextWindow: number,
+): ContextCompactionVerdict {
+	const base: ContextCompactionVerdict = {
+		shouldCompact: false,
+		pressure: null,
+		contextTokens,
+		contextWindow,
+		threshold,
+	};
+	if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) return base;
+	if (!Number.isFinite(contextTokens) || contextTokens <= 0) return base;
+	if (!Number.isFinite(contextWindow) || contextWindow <= 0) return base;
+
+	const pressure = contextTokens / contextWindow;
+	return {
+		shouldCompact: pressure >= threshold,
+		pressure,
+		contextTokens,
+		contextWindow,
+		threshold,
+	};
+}
+
+/**
+ * Coalesces concurrent `fire(task)` calls onto a single in-flight Promise.
+ *
+ * A chat session can race a threshold-driven trigger and an overflow-recovery
+ * trigger inside the same tick. Both want to run compaction. The first fire
+ * starts the task and stores the Promise; subsequent fires observe the same
+ * Promise and await it instead of kicking off a second run. Once the task
+ * settles (resolve or reject), the slot clears so the next fire starts a
+ * fresh run.
+ */
+export class AutoCompactionTrigger<T> {
+	private inFlight: Promise<T> | null = null;
+
+	/** True while a task is in flight. Callers can short-circuit on this. */
+	isBusy(): boolean {
+		return this.inFlight !== null;
+	}
+
+	/**
+	 * Run `task` unless one is already in flight. Returns the Promise the
+	 * task is running under. Callers always get the eventual result of the
+	 * first task, never a second call. Rejections clear the slot so a later
+	 * fire can start fresh.
+	 */
+	fire(task: () => Promise<T>): Promise<T> {
+		if (this.inFlight) return this.inFlight;
+		const run = task().finally(() => {
+			this.inFlight = null;
+		});
+		this.inFlight = run;
+		return run;
+	}
+}