@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/cli/web.ts

@@ -0,0 +1,79 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolvePackageRoot } from "../core/package-root.js";
+import { printError } from "./argv.js";
+
+const HELP = `Clio Coder web application
+
+Usage:
+  clio-coder web [--open] [--port <0-65535>]
+  clio-coder web background install [--open] [--port <1-65535>]
+  clio-coder web background status|start|open|stop|uninstall
+  clio-coder web launcher install|status|uninstall
+
+The foreground server prints a private launch link. --open opens your default
+browser. Press Ctrl+C to stop. --no-open explicitly disables browser opening.
+Optional --idle-exit <milliseconds> stops an idle foreground server.
+Use --path </app/path> to open a particular page. --reuse-background uses this
+installation's background app when configured, or starts a foreground server.
+
+On Linux with a systemd user session, background install keeps the app available
+at login. Open its launch link once, then install it from your browser. Background
+stop stops it now; background uninstall also removes its login and desktop entries.
+Other platforms can run the foreground web app. Your CLI, terminal interface,
+headless runs, and web app use the same Clio runtime and configuration.
+`;
+
+export async function runWebCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	try {
+		const root = resolvePackageRoot();
+		process.env.CLIO_CODER_PACKAGE_ROOT = root;
+		// A URL keeps this a separate entry; bundling it into the command chunk
+		// would change import.meta.url and the worker/client paths beside it.
+		const server = await import(pathToFileURL(join(root, "dist/web/server.js")).href);
+		await server.main(args);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not start the web application.");
+		return 1;
+	}
+}
+
+/** Separate packaged entry; inspection never starts a listener or opens a browser. */
+export async function prepareWebUninstall(options: { stateDir: string; desktopPrefix: string }): Promise<{
+	items: Array<{ label: string; path: string }>;
+	remove(): Promise<void>;
+}> {
+	// Most CLI-only installs have no web lifecycle files. Keep that path lazy,
+	// including checkouts whose optional web bundle has not been built yet.
+	const paths = [
+		join(options.stateDir, "web/background"),
+		join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop"),
+		join(options.desktopPrefix, "applications/io.iowarp.ClioCoder.desktop.owner.json"),
+	];
+	const present = paths.some((path) => {
+		try {
+			lstatSync(path);
+			return true;
+		} catch (error) {
+			if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+			throw error;
+		}
+	});
+	if (!present)
+		return {
+			items: [],
+			remove: async () => {
+				if ((await prepareWebUninstall(options)).items.length)
+					throw new Error("A web installation appeared during confirmation; run uninstall again.");
+			},
+		};
+	const packageRoot = resolvePackageRoot();
+	const server = await import(pathToFileURL(join(packageRoot, "dist/web/server.js")).href);
+	return server.prepareWebUninstall({ ...options, packageRoot });
+}

package/src/core/bash-exec.ts

@@ -21,7 +21,14 @@ export const BASH_HARD_CAP_BYTES = 16 * 1024 * 1024;
 
 const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE", "BASH_ENV", "ENV"] as const;
 
-export interface BashCommandResult {
+export interface BashStreamByteCounts {
+	observedStdoutBytes: number;
+	observedStderrBytes: number;
+	retainedStdoutBytes: number;
+	retainedStderrBytes: number;
+}
+
+export interface BashCommandResult extends Partial<BashStreamByteCounts> {
 	error: NodeJS.ErrnoException | null;
 	stdout: string;
 	stderr: string;
@@ -60,6 +67,8 @@ export interface BashProgressScheduler {
 }
 
 export interface BashOutputProgressController {
+	/** Raw stream byte counts, independent of UTF-8 decoding and capture clipping. */
+	byteCounts(): BashStreamByteCounts;
 	/** Emit the initial empty cumulative snapshot, when a callback is configured. */
 	start(): void;
 	/** Accept one stream chunk. Returns true only when this chunk reaches the hard cap. */
@@ -90,6 +99,12 @@ export function createBashOutputProgressController(
 	const stdoutDecoder = new StringDecoder("utf8");
 	const stderrDecoder = new StringDecoder("utf8");
 	let decodersFinished = false;
+	const counts: BashStreamByteCounts = {
+		observedStdoutBytes: 0,
+		observedStderrBytes: 0,
+		retainedStdoutBytes: 0,
+		retainedStderrBytes: 0,
+	};
 	let outputBytes = 0;
 	let outputCapped = false;
 	let updateTimer: unknown = null;
@@ -144,16 +159,22 @@ export function createBashOutputProgressController(
 	};
 
 	return {
+		byteCounts: () => ({ ...counts }),
 		start(): void {
 			if (phase !== "active" || onUpdate === undefined) return;
 			updateDirty = true;
 			emitUpdate();
 		},
 		append(target, chunk): boolean {
-			if (phase !== "active" || outputCapped) return false;
+			if (phase !== "active") return false;
+			if (target === "stdout") counts.observedStdoutBytes += chunk.byteLength;
+			else counts.observedStderrBytes += chunk.byteLength;
+			if (outputCapped) return false;
 			const remaining = BASH_HARD_CAP_BYTES - outputBytes;
 			const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
 			outputBytes += accepted.byteLength;
+			if (target === "stdout") counts.retainedStdoutBytes += accepted.byteLength;
+			else counts.retainedStderrBytes += accepted.byteLength;
 			if (accepted.byteLength > 0) {
 				const decoded = target === "stdout" ? stdoutDecoder.write(accepted) : stderrDecoder.write(accepted);
 				if (target === "stdout") stdout += decoded;
@@ -213,7 +234,7 @@ function parseNullDelimitedEnv(raw: string): NodeJS.ProcessEnv | null {
 }
 
 function captureLoginEnv(): Promise<NodeJS.ProcessEnv | null> {
-	return new Promise((resolve) => {
+	return new Promise<NodeJS.ProcessEnv | null>((resolve) => {
 		let stdout = "";
 		let settled = false;
 		const finish = (value: NodeJS.ProcessEnv | null): void => {
@@ -266,7 +287,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		enabled: gitCommitAttributionEnabled(process.env),
 	});
 	reportCommitAttributionDiagnostic(attribution.diagnostic);
-	return new Promise((resolve) => {
+	return new Promise<BashCommandResult>((resolve) => {
 		const timeout = clampTimerDelayMs(options.timeoutMs ?? 300_000);
 		let aborted = false;
 		let timedOut = false;
@@ -377,6 +398,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			resolveAfterCancellation({
 				error: error as NodeJS.ErrnoException,
 				...finalOutput,
+				...output.byteCounts(),
 				exitCode: null,
 				signal: null,
 				aborted,
@@ -401,6 +423,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			resolveAfterCancellation({
 				error,
 				...finalOutput,
+				...output.byteCounts(),
 				exitCode: code,
 				signal: signalName,
 				aborted,

package/src/core/bus-events.ts

@@ -630,6 +630,7 @@ export interface DispatchTerminalStats {
 	outputTokenCount: number;
 	cacheReadTokenCount: number;
 	cacheWriteTokenCount: number;
+	cacheWrite1hTokenCount?: number;
 	reasoningTokenCount: number;
 	staticShellHash: string | null;
 	sessionShellHash: string | null;
@@ -714,10 +715,8 @@ export interface CompactionPayload {
 /**
  * Published on {@link BusChannels.ExtensionsReloaded} by the composition
  * root after a new extension generation and its user-hook registrations
- * have both been committed. Consumers that cache extension-sourced data
- * (prompt fragments, agent recipes, the session prompt) refresh on
- * `changed`; an unchanged generation carries the previous digest and needs
- * no work. Never published between the two commits.
+ * have both been committed. Never published between the two commits.
+ * Recipe and prompt consumers subscribe to PluginsReloaded instead.
  */
 export interface ExtensionsReloadedPayload {
 	generation: number;

package/src/core/config.ts

@@ -593,6 +593,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"lifecycle",
 		"gateway",
 		"pricing",
+		"cache",
 		"lmstudio",
 		"litellm",
 		"maxConcurrentRequests",
@@ -642,6 +643,76 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validatePricing(issues, `${path}.pricing`, value.pricing);
 		if (v !== undefined) target.pricing = v;
 	}
+	if ("cache" in value) {
+		if (!isPlainObject(value.cache)) issues.add(`${path}.cache`, "expected a map");
+		else {
+			issues.unknownKeys(`${path}.cache`, value.cache, ["retention", "deployment", "warm"]);
+			target.cache = {};
+			if ("retention" in value.cache) {
+				const retention = expectEnum(issues, `${path}.cache.retention`, value.cache.retention, [
+					"none",
+					"short",
+					"long",
+				] as const);
+				if (retention !== undefined) target.cache.retention = retention;
+			}
+			if ("deployment" in value.cache) {
+				const binding = value.cache.deployment;
+				const bindingPath = `${path}.cache.deployment`;
+				if (!isPlainObject(binding)) issues.add(bindingPath, "expected a map");
+				else {
+					issues.unknownKeys(bindingPath, binding, ["backend", "controlUrl", "model", "build", "gatewayDeploymentId"]);
+					const backend = expectEnum(issues, `${bindingPath}.backend`, binding.backend, ["llamacpp", "vllm"] as const);
+					for (const key of ["controlUrl", "model", "build"] as const) {
+						if (typeof binding[key] !== "string" || !binding[key].trim())
+							issues.add(`${bindingPath}.${key}`, "expected a nonempty string");
+					}
+					if (typeof binding.controlUrl === "string") {
+						try {
+							const url = new URL(binding.controlUrl);
+							if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+								throw new Error("invalid URL");
+						} catch {
+							issues.add(`${bindingPath}.controlUrl`, "expected an HTTP(S) URL without credentials, query, or fragment");
+						}
+					}
+					if (
+						binding.gatewayDeploymentId !== undefined &&
+						(typeof binding.gatewayDeploymentId !== "string" || !binding.gatewayDeploymentId.trim())
+					)
+						issues.add(`${bindingPath}.gatewayDeploymentId`, "expected a nonempty string");
+					if (
+						backend &&
+						typeof binding.controlUrl === "string" &&
+						typeof binding.model === "string" &&
+						typeof binding.build === "string"
+					) {
+						target.cache.deployment = {
+							backend,
+							controlUrl: binding.controlUrl,
+							model: binding.model,
+							build: binding.build,
+							...(typeof binding.gatewayDeploymentId === "string" ? { gatewayDeploymentId: binding.gatewayDeploymentId } : {}),
+						};
+					}
+				}
+			}
+			if ("warm" in value.cache) {
+				if (!isPlainObject(value.cache.warm)) issues.add(`${path}.cache.warm`, "expected a map");
+				else {
+					issues.unknownKeys(`${path}.cache.warm`, value.cache.warm, ["maxInputTokens", "maxDurationMs", "cooldownMs"]);
+					target.cache.warm = {};
+					for (const key of ["maxInputTokens", "maxDurationMs", "cooldownMs"] as const) {
+						const bound = value.cache.warm[key];
+						if (bound === undefined) continue;
+						if (typeof bound !== "number" || !Number.isSafeInteger(bound) || bound < 1)
+							issues.add(`${path}.cache.warm.${key}`, "expected a positive safe integer");
+						else target.cache.warm[key] = bound;
+					}
+				}
+			}
+		}
+	}
 	if ("lmstudio" in value) {
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
@@ -1238,12 +1309,13 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 						"baseDelayMs",
 						"maxDelayMs",
 						"streamStallMs",
+						"firstTokenStallMs",
 					]);
 					if ("enabled" in chat.retry) {
 						const parsed = expectBoolean(issues, "chat.retry.enabled", chat.retry.enabled);
 						if (parsed !== undefined) settings.chat.retry.enabled = parsed;
 					}
-					for (const key of ["maxRetries", "baseDelayMs", "maxDelayMs", "streamStallMs"] as const) {
+					for (const key of ["maxRetries", "baseDelayMs", "maxDelayMs", "streamStallMs", "firstTokenStallMs"] as const) {
 						if (!(key in chat.retry)) continue;
 						const parsed = expectInteger(issues, `chat.retry.${key}`, chat.retry[key], { min: 0 });
 						if (parsed !== undefined) settings.chat.retry[key] = parsed;

package/src/core/defaults.ts

@@ -217,6 +217,13 @@ export interface RetrySettings {
 	maxDelayMs: number;
 	/** Silence on an in-flight stream past this many ms is treated as a wedged backend: abort and retry. */
 	streamStallMs: number;
+	/**
+	 * Silence allowed before a call's first token. A local server that slept
+	 * reloads the model and prefills cold before it can emit anything, so this
+	 * window is longer than the mid-stream one. 0 never aborts a call that has
+	 * not started streaming.
+	 */
+	firstTokenStallMs: number;
 }
 
 export const OUTPUT_STYLES = ["compact", "standard", "detailed"] as const;
@@ -391,7 +398,7 @@ export interface FleetSettings extends FleetRouteSettings {
 	history: FleetHistorySettings;
 }
 
-/** Roles whose authority is narrow enough for Slice 9 active joint routing. */
+/** Roles whose authority is narrow enough for active joint routing. */
 export const ACTIVE_ROUTING_ROLES = ["researcher", "verifier", "reviewer", "judge"] as const;
 export type ActiveRoutingRole = (typeof ACTIVE_ROUTING_ROLES)[number];
 
@@ -485,6 +492,7 @@ export const DEFAULT_SETTINGS = {
 			baseDelayMs: 2000,
 			maxDelayMs: 60000,
 			streamStallMs: 180000,
+			firstTokenStallMs: 600000,
 		} as RetrySettings,
 	} as ChatSettings,
 	fleet: {
@@ -620,6 +628,7 @@ chat:
     baseDelayMs: 2000
     maxDelayMs: 60000
     streamStallMs: 180000
+    firstTokenStallMs: 600000
 
 fleet:
   default:

package/src/core/domain-loader.ts

@@ -78,35 +78,11 @@ export async function loadDomains(
 		},
 	};
 
-	for (const name of order) {
-		const mod = modules.find((m) => m.manifest.name === name);
-		if (!mod) continue;
-		try {
-			const bundle = await mod.createExtension(context);
-			await bundle.extension.start();
-			extensions.set(name, bundle.extension);
-			contracts.set(name, bundle.contract);
-			loaded.push(name);
-			bus.emit(BusChannels.DomainLoaded, { name });
-		} catch (error) {
-			failed.push({ name, error });
-			bus.emit(BusChannels.DomainFailed, { name, error });
-			// The throw below aborts boot; nothing downstream gets a chance to
-			// render the failure, so the structured line must land first.
-			const message = error instanceof Error ? error.message : String(error);
-			(options.diagnostic ?? ((text: string) => process.stderr.write(text)))(
-				`[clio-coder:domain] load failed: ${name}: ${message}\n`,
-			);
-			throw new DomainLoadError(name, error);
-		}
-	}
-
-	const stop = async (): Promise<void> => {
+	const stopAll = async (): Promise<void> => {
 		const debug = process.env.CLIO_CODER_DEBUG_SHUTDOWN === "1";
 		const budgetMs = resolveShutdownHookBudgetMs();
-		for (const name of [...loaded].reverse()) {
-			const ext = extensions.get(name);
-			if (!ext?.stop) continue;
+		for (const [name, ext] of [...extensions].reverse()) {
+			if (!ext.stop) continue;
 			const stopFn = ext.stop.bind(ext);
 			const t0 = debug ? process.hrtime.bigint() : 0n;
 			const completed = await runWithBudget(stopFn, budgetMs, (err) => {
@@ -124,7 +100,34 @@ export async function loadDomains(
 				);
 			}
 		}
+		extensions.clear();
+		contracts.clear();
 	};
+	let stopping: Promise<void> | undefined;
+	const stop = (): Promise<void> => (stopping ??= stopAll());
+
+	for (const name of order) {
+		const mod = modules.find((m) => m.manifest.name === name);
+		if (!mod) continue;
+		try {
+			const bundle = await mod.createExtension(context);
+			// A rejected start may already own listeners or other resources.
+			extensions.set(name, bundle.extension);
+			await bundle.extension.start();
+			contracts.set(name, bundle.contract);
+			loaded.push(name);
+			bus.emit(BusChannels.DomainLoaded, { name });
+		} catch (error) {
+			failed.push({ name, error });
+			bus.emit(BusChannels.DomainFailed, { name, error });
+			await stop();
+			const message = error instanceof Error ? error.message : String(error);
+			(options.diagnostic ?? ((text: string) => process.stderr.write(text)))(
+				`[clio-coder:domain] load failed: ${name}: ${message}\n`,
+			);
+			throw new DomainLoadError(name, error);
+		}
+	}
 
 	const getContract = <T extends DomainContract = DomainContract>(name: string): T | undefined => {
 		return contracts.get(name) as T | undefined;
@@ -134,7 +137,13 @@ export async function loadDomains(
 }
 
 function topoSort(modules: ReadonlyArray<DomainModule>): string[] {
-	const names = new Set(modules.map((m) => m.manifest.name));
+	const names = new Set<string>();
+	for (const { manifest } of modules) {
+		if (names.has(manifest.name)) {
+			throw new DomainLoadError("topo", new Error(`Duplicate domain: ${manifest.name}`));
+		}
+		names.add(manifest.name);
+	}
 	const unresolved: string[] = [];
 	for (const m of modules) {
 		for (const dep of m.manifest.dependsOn) {

package/src/core/event-bus.ts

@@ -14,7 +14,7 @@ import type { BusChannel, BusPayloadMap } from "./bus-events.js";
  * settling, so side effects that must happen before the next emit() must be
  * completed synchronously.
  *
- * Phase 2+ registers domain listeners here; violate the invariant and
+ * Domain listeners register here; violate the invariant and
  * shutdown.* ordering or banner timing will drift.
  */
 export type SafeEventListener<C extends BusChannel = BusChannel> = (payload: BusPayloadMap[C]) => void | Promise<void>;