@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/cli/memory.ts

@@ -0,0 +1,180 @@
+import { clioDataDir } from "../core/xdg.js";
+import {
+	approveMemoryRecord,
+	loadMemoryRecords,
+	type MemoryRecord,
+	memoryStatus,
+	proposeMemoryFromEvidence,
+	pruneStaleMemory,
+	rejectMemoryRecord,
+} from "../domains/memory/index.js";
+import { printError, printOk } from "./shared.js";
+
+const HELP = `clio-coder memory list
+clio-coder memory propose --from-evidence <evidenceId>
+clio-coder memory approve <memoryId>
+clio-coder memory reject <memoryId>
+clio-coder memory prune --stale
+
+Manage scoped, approved, evidence-linked local memory records.
+`;
+
+type MemoryCommand = "list" | "propose" | "approve" | "reject" | "prune";
+
+interface ParsedMemoryArgs {
+	command?: MemoryCommand;
+	evidenceId?: string;
+	memoryId?: string;
+	stale: boolean;
+	help: boolean;
+}
+
+function parseMemoryArgs(args: ReadonlyArray<string>): ParsedMemoryArgs {
+	const parsed: ParsedMemoryArgs = { stale: false, help: false };
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) continue;
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (parsed.command === undefined) {
+			if (arg === "list" || arg === "propose" || arg === "approve" || arg === "reject" || arg === "prune") {
+				parsed.command = arg;
+				continue;
+			}
+			throw new Error(`unknown memory command: ${arg}`);
+		}
+		if (parsed.command === "propose") {
+			if (arg === "--from-evidence") {
+				const value = args[index + 1];
+				if (value === undefined || value.startsWith("-")) throw new Error("--from-evidence requires an evidence id");
+				parsed.evidenceId = value;
+				index += 1;
+				continue;
+			}
+			throw new Error(`unknown memory propose argument: ${arg}`);
+		}
+		if (parsed.command === "approve" || parsed.command === "reject") {
+			if (parsed.memoryId === undefined && !arg.startsWith("-")) {
+				parsed.memoryId = arg;
+				continue;
+			}
+			throw new Error(`unexpected memory ${parsed.command} argument: ${arg}`);
+		}
+		if (parsed.command === "prune") {
+			if (arg === "--stale") {
+				parsed.stale = true;
+				continue;
+			}
+			throw new Error(`unknown memory prune argument: ${arg}`);
+		}
+		throw new Error(`unexpected memory argument: ${arg}`);
+	}
+	if (parsed.help) return parsed;
+	if (parsed.command === undefined) throw new Error("memory requires list, propose, approve, reject, or prune");
+	if (parsed.command === "propose" && parsed.evidenceId === undefined) {
+		throw new Error("propose requires --from-evidence <evidenceId>");
+	}
+	if ((parsed.command === "approve" || parsed.command === "reject") && parsed.memoryId === undefined) {
+		throw new Error(`${parsed.command} requires a memory id`);
+	}
+	if (parsed.command === "prune" && !parsed.stale) throw new Error("prune requires --stale");
+	if (parsed.command === "list" && (parsed.evidenceId !== undefined || parsed.memoryId !== undefined || parsed.stale)) {
+		throw new Error("list does not accept extra arguments");
+	}
+	return parsed;
+}
+
+export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<number> {
+	let parsed: ParsedMemoryArgs;
+	try {
+		parsed = parseMemoryArgs(args);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		process.stdout.write(HELP);
+		return 2;
+	}
+	if (parsed.help) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+
+	const dataDir = clioDataDir();
+	try {
+		if (parsed.command === "list") {
+			renderMemoryList(await loadMemoryRecords(dataDir));
+			return 0;
+		}
+		if (parsed.command === "propose") {
+			const evidenceId = parsed.evidenceId;
+			if (evidenceId === undefined) {
+				printError("propose requires --from-evidence <evidenceId>");
+				return 2;
+			}
+			const result = await proposeMemoryFromEvidence(dataDir, evidenceId);
+			renderProposal(result.record, result.created);
+			return 0;
+		}
+		if (parsed.command === "approve") {
+			const memoryId = parsed.memoryId;
+			if (memoryId === undefined) {
+				printError("approve requires a memory id");
+				return 2;
+			}
+			const record = await approveMemoryRecord(dataDir, memoryId);
+			printOk(`approved ${record.id}`);
+			return 0;
+		}
+		if (parsed.command === "reject") {
+			const memoryId = parsed.memoryId;
+			if (memoryId === undefined) {
+				printError("reject requires a memory id");
+				return 2;
+			}
+			const record = await rejectMemoryRecord(dataDir, memoryId);
+			printOk(`rejected ${record.id}`);
+			return 0;
+		}
+		if (parsed.command === "prune") {
+			const pruned = await pruneStaleMemory(dataDir);
+			printOk(`pruned ${pruned.length} stale memory record${pruned.length === 1 ? "" : "s"}`);
+			return 0;
+		}
+		printError("memory requires list, propose, approve, reject, or prune");
+		return 2;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}
+
+function renderProposal(record: MemoryRecord, created: boolean): void {
+	process.stdout.write(`memory: ${record.id}\n`);
+	process.stdout.write(`status: ${created ? "proposed" : memoryStatus(record)}\n`);
+	process.stdout.write(`scope: ${record.scope}\n`);
+	process.stdout.write(`key: ${record.key}\n`);
+	process.stdout.write(`evidence: ${record.evidenceRefs.join(", ")}\n`);
+	process.stdout.write(`confidence: ${record.confidence.toFixed(2)}\n`);
+	process.stdout.write(`lesson: ${record.lesson}\n`);
+}
+
+function renderMemoryList(records: ReadonlyArray<MemoryRecord>): void {
+	process.stdout.write(`${records.length} memory record${records.length === 1 ? "" : "s"}\n`);
+	if (records.length === 0) return;
+	process.stdout.write("\n");
+	for (const record of records) {
+		process.stdout.write(
+			[
+				record.id.padEnd(21),
+				memoryStatus(record).padEnd(10),
+				record.scope.padEnd(13),
+				`confidence=${record.confidence.toFixed(2)}`.padEnd(16),
+				`evidence=${record.evidenceRefs.join(",")}`,
+			].join(""),
+		);
+		process.stdout.write("\n");
+		process.stdout.write(`  key: ${record.key}\n`);
+		process.stdout.write(`  lesson: ${record.lesson}\n`);
+	}
+}

package/src/cli/models.ts

@@ -0,0 +1,257 @@
+import chalk from "chalk";
+import { loadDomains } from "../core/domain-loader.js";
+import { ConfigDomainModule } from "../domains/config/index.js";
+import { ensureClioState } from "../domains/lifecycle/index.js";
+import type { ProvidersContract, TargetStatus } from "../domains/providers/contract.js";
+import {
+	modelCandidatesForStatus,
+	ProvidersDomainModule,
+	resolveModelCapabilities,
+} from "../domains/providers/index.js";
+import { printError } from "./shared.js";
+
+export interface ModelRow {
+	targetId: string;
+	runtimeId: string;
+	modelId: string;
+	caps: string;
+	contextWindow: number;
+	maxTokens: number;
+	reasoning: boolean;
+	state: string;
+}
+
+const HELP = `clio-coder models [search] [--target <id>] [--json] [--offline]
+
+List live-discovered models for configured targets.
+
+Options:
+  --offline   use cached/configured/catalog model hints without probing targets
+`;
+
+interface ModelArgs {
+	json: boolean;
+	offline: boolean;
+	target?: string;
+	search?: string;
+	help: boolean;
+}
+
+function parseModelArgs(args: ReadonlyArray<string>): ModelArgs {
+	const parsed: ModelArgs = { json: false, offline: false, help: false };
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === undefined) continue;
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--offline") {
+			parsed.offline = true;
+			continue;
+		}
+		if (arg === "--target") {
+			const value = args[i + 1];
+			if (!value) throw new Error("--target requires a value");
+			parsed.target = value;
+			i += 1;
+			continue;
+		}
+		if (arg?.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
+		if (parsed.search) throw new Error("models accepts at most one search term");
+		parsed.search = arg;
+	}
+	return parsed;
+}
+
+export async function runModelsCommand(args: ReadonlyArray<string>): Promise<number> {
+	let parsed: ModelArgs;
+	try {
+		parsed = parseModelArgs(args);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		process.stderr.write(HELP);
+		return 2;
+	}
+	if (parsed.help) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+
+	ensureClioState();
+	const loaded = await loadDomains([ConfigDomainModule, ProvidersDomainModule]);
+	const providers = loaded.getContract<ProvidersContract>("providers");
+	if (!providers) {
+		process.stderr.write("models: provider domain not loaded\n");
+		await loaded.stop();
+		return 1;
+	}
+	if (!parsed.offline) {
+		try {
+			await providers.probeAllLive();
+		} catch (err) {
+			process.stderr.write(`models: live probe failed: ${err instanceof Error ? err.message : String(err)}\n`);
+		}
+	}
+	const entries = providers.list();
+	if (parsed.target !== undefined && !entries.some((e) => e.target.id === parsed.target)) {
+		printError(`no target with id ${parsed.target}. ${targetCount(entries.length)} configured.`);
+		await loaded.stop();
+		return 2;
+	}
+	const filtered = parsed.target ? entries.filter((e) => e.target.id === parsed.target) : entries;
+	const rows = collectRows(filtered, providers).filter((row) => matchesSearch(row, parsed.search));
+
+	if (parsed.json) {
+		process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+	} else if (rows.length === 0) {
+		process.stdout.write(`${emptyModelsMessage(parsed, entries.length, filtered.length)}\n`);
+	} else {
+		renderRows(rows);
+	}
+	await loaded.stop();
+	return 0;
+}
+
+function collectRows(entries: ReadonlyArray<TargetStatus>, providers: ProvidersContract): ModelRow[] {
+	const rows: ModelRow[] = [];
+	for (const status of entries) {
+		const runtimeId = status.runtime?.id ?? status.target.runtime;
+		const candidates = modelCandidatesForStatus(status);
+		if (candidates.length === 0) {
+			const caps = resolveRowCapabilities(status, status.target.defaultModel ?? null, providers);
+			rows.push({
+				targetId: status.target.id,
+				runtimeId,
+				modelId: "(no models)",
+				state: "-",
+				...formatCapabilities(caps),
+			});
+			continue;
+		}
+		for (const candidate of candidates) {
+			const modelId = candidate.id;
+			const caps = resolveRowCapabilities(status, modelId, providers);
+			rows.push({
+				targetId: status.target.id,
+				runtimeId,
+				modelId,
+				state: candidate.loadState ?? "-",
+				...formatCapabilities(caps),
+			});
+		}
+	}
+	return rows;
+}
+
+function resolveRowCapabilities(status: TargetStatus, modelId: string | null, providers: ProvidersContract) {
+	return resolveModelCapabilities(status, modelId, providers.knowledgeBase, {
+		detectedReasoning: modelId ? providers.getDetectedReasoning(status.target.id, modelId) : null,
+	});
+}
+
+function formatCapabilities(
+	c: ReturnType<typeof resolveRowCapabilities>,
+): Pick<ModelRow, "caps" | "contextWindow" | "maxTokens" | "reasoning"> {
+	return {
+		caps: capabilityBadges(c),
+		contextWindow: c.contextWindow,
+		maxTokens: c.maxTokens,
+		reasoning: c.reasoning,
+	};
+}
+
+function capabilityBadges(c: ReturnType<typeof resolveRowCapabilities>): string {
+	const badge = (on: boolean, letter: string): string => (on ? letter : "-");
+	return [
+		badge(c.chat, "C"),
+		badge(c.tools, "T"),
+		badge(c.reasoning, "R"),
+		badge(c.vision, "V"),
+		badge(c.embeddings, "E"),
+		badge(c.rerank, "K"),
+		badge(c.fim, "F"),
+	].join("");
+}
+
+function compactTokenCount(value: number): string {
+	if (!Number.isFinite(value) || value <= 0) return "-";
+	if (value >= 1_000_000) {
+		const rounded = value / 1_000_000;
+		return `${Number.isInteger(rounded) ? rounded.toFixed(0) : rounded.toFixed(1)}m`;
+	}
+	if (value >= 1000) return `${Math.round(value / 1000)}k`;
+	return String(value);
+}
+
+export function emptyModelsMessage(
+	args: Pick<ModelArgs, "search" | "target">,
+	configuredTargets: number,
+	matchedTargets: number,
+): string {
+	if (configuredTargets === 0) {
+		return "no targets configured. run `clio-coder configure` or `clio-coder targets add` to register one.";
+	}
+	if (args.target !== undefined && matchedTargets === 0) {
+		return `no target with id ${args.target}. ${targetCount(configuredTargets)} configured.`;
+	}
+	if (args.search !== undefined) {
+		return `no models matched "${args.search}" across ${targetCount(matchedTargets)}.`;
+	}
+	return `no models found across ${targetCount(matchedTargets)}.`;
+}
+
+function targetCount(n: number): string {
+	return `${n} target${n === 1 ? "" : "s"}`;
+}
+
+const MODEL_ID_WIDTH_CAP = 56;
+const COLUMN_GAP = "  ";
+
+function truncateModelId(id: string): string {
+	if (id.length <= MODEL_ID_WIDTH_CAP) return id;
+	return `${id.slice(0, MODEL_ID_WIDTH_CAP - 3)}...`;
+}
+
+export function modelTableLines(rows: ReadonlyArray<ModelRow>): string[] {
+	const includeState = rows.some((row) => row.state && row.state !== "-");
+	const headers = includeState
+		? ["target", "runtime", "model", "state", "caps", "ctx", "max"]
+		: ["target", "runtime", "model", "caps", "ctx", "max"];
+	const cells = rows.map((row) => {
+		const base = [row.targetId, row.runtimeId, truncateModelId(row.modelId)];
+		if (includeState) base.push(row.state || "-");
+		base.push(row.caps, compactTokenCount(row.contextWindow), compactTokenCount(row.maxTokens));
+		return base;
+	});
+	const widths = headers.map((h, col) => Math.max(h.length, ...cells.map((cell) => cell[col]?.length ?? 0)));
+	const formatLine = (values: ReadonlyArray<string>): string =>
+		values
+			.map((value, col) => value.padEnd(widths[col] ?? 0))
+			.join(COLUMN_GAP)
+			.trimEnd();
+	return [formatLine(headers), ...cells.map(formatLine)];
+}
+
+function renderRows(rows: ReadonlyArray<ModelRow>): void {
+	const [header, ...body] = modelTableLines(rows);
+	process.stdout.write(`${chalk.bold(header ?? "")}\n`);
+	for (const line of body) {
+		process.stdout.write(`${line}\n`);
+	}
+}
+
+function matchesSearch(row: ModelRow, search: string | undefined): boolean {
+	if (!search) return true;
+	const needle = search.toLowerCase();
+	return (
+		row.targetId.toLowerCase().includes(needle) ||
+		row.runtimeId.toLowerCase().includes(needle) ||
+		row.modelId.toLowerCase().includes(needle) ||
+		row.state.toLowerCase().includes(needle)
+	);
+}

package/src/cli/modes/json-stream.ts

@@ -0,0 +1,85 @@
+/**
+ * Projection from chat-loop events to the headless `--json` wire stream.
+ *
+ * The stream is append-oriented: it carries each piece of content exactly
+ * once, as an increment while it streams and as one completed message when it
+ * lands. It never repeats the growing snapshot of an in-progress message,
+ * because that is quadratic in a long turn. One tool-heavy SciCode sub-step
+ * wrote 802 MB of stdout, 99.3% of it `message_update` snapshots of a message
+ * whose final form is 44 KB.
+ *
+ * The rules, in one place:
+ *   - `message_update` is dropped. Its increments are already published as
+ *     `text_delta` / `thinking_delta`, and its `message` is the partial form of
+ *     the `message_end` that follows.
+ *   - `text_delta` / `thinking_delta` carry the increment, not the growing
+ *     partial text.
+ *   - `agent_end` carries its segment's usage and message count, not a second
+ *     copy of every message already streamed.
+ *   - `turn_end` keeps its assistant message (stop reason and usage live
+ *     there) and drops `toolResults`, each of which already crossed the wire
+ *     as a `tool_execution_end`.
+ *   - Every other event passes through unchanged.
+ */
+
+import type { AgentMessage } from "../../engine/types.js";
+import type { ChatLoopEvent } from "../../interactive/chat-loop.js";
+import { sumRunUsage } from "../../interactive/chat-loop-messages.js";
+
+export function projectHeadlessJsonEvent(event: ChatLoopEvent): unknown | null {
+	if (event.type === "message_update") return null;
+	if (event.type === "text_delta") {
+		return { type: event.type, contentIndex: event.contentIndex, delta: event.delta };
+	}
+	if (event.type === "thinking_delta") {
+		return { type: event.type, contentIndex: event.contentIndex, delta: event.delta };
+	}
+	if (event.type === "agent_end") return segmentSummary(event.type, event.messages);
+	if (event.type === "turn_end") {
+		return { type: event.type, message: event.message };
+	}
+	return event;
+}
+
+/**
+ * Projection for the dispatch `--json` stream, whose events come off a worker
+ * rather than out of the chat loop.
+ *
+ * The two streams name streaming increments differently by design: a worker
+ * publishes them as `message_update` deltas already slimmed of their
+ * cumulative snapshots at the worker stdout seam, and the chat loop publishes
+ * them as `text_delta`. They make the same promise about content crossing
+ * once, and `agent_end` was breaking it here: it carried the segment's entire
+ * transcript, every message of which had already crossed as its own
+ * `message_end`. It now carries the same segment summary the main-agent stream
+ * carries, which is also what lets a reader check the per-segment and
+ * per-message accounts of one run against each other.
+ */
+export function projectDispatchJsonEvent(event: unknown): unknown {
+	if (!isRecord(event) || event.type !== "agent_end" || !Array.isArray(event.messages)) return event;
+	const { messages: _messages, ...rest } = event;
+	return { ...rest, ...segmentSummary("agent_end", event.messages as AgentMessage[]) };
+}
+
+function segmentSummary(type: string, messages: ReadonlyArray<AgentMessage>): Record<string, unknown> {
+	const usage = sumRunUsage(messages);
+	return {
+		type,
+		messageCount: messages.length,
+		usage: {
+			input: usage.input,
+			output: usage.output,
+			cacheRead: usage.cacheRead,
+			cacheWrite: usage.cacheWrite,
+			reasoning: usage.reasoning,
+			totalTokens: usage.tokens,
+			costUsd: usage.costUsd,
+			apiCalls: usage.apiCalls,
+			measured: usage.hadUsage,
+		},
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/cli/modes/jsonl.ts

@@ -0,0 +1,9 @@
+/**
+ * Serialize one LF-framed JSONL record.
+ *
+ * Keep framing strict: JSON strings may legally contain U+2028/U+2029 and
+ * escaped newlines, but records are delimited only by the final ASCII LF.
+ */
+export function serializeJsonLine(value: unknown): string {
+	return `${JSON.stringify(value)}\n`;
+}