@iowarp/clio-coder 0.4.7 → 0.4.8

package/src/cli/uninstall.ts

@@ -9,6 +9,7 @@ import { detectInstallMethod } from "../domains/lifecycle/install-method.js";
 import { createLifecyclePresenter, type LifecycleItem, measurePath, shortenPath } from "./lifecycle-presenter.js";
 import { type RemovalFailure, removePath, reportRemovalFailures } from "./removal.js";
 import { printError } from "./shared.js";
+import { prepareWebUninstall } from "./web.js";
 
 const HELP = `clio-coder uninstall [--remove-binary] [--keep-config] [--keep-data] [--dry-run] [--force] [--json]
 
@@ -18,6 +19,8 @@ Per-project \`.clio-coder/\` directories sit outside those roots and are never
 removed here. Every project Clio has run in is recorded in the session metadata,
 so the real run and --dry-run both list them and name the command that clears one.
 Shell startup files are reported, never edited.
+Owned web background services are stopped and disabled before their state is
+removed; their desktop launchers are removed using the app's ownership manifests.
 
 Flags:
   --keep-config    preserve the configuration root (settings.yaml, credentials)
@@ -331,6 +334,18 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	const linkSize = measurePath(linkPath);
 	const launcher = classifyLauncher(linkPath);
 	const shellEdits = detectShellRcEdits();
+	let web: Awaited<ReturnType<typeof prepareWebUninstall>>;
+	try {
+		const desktopPrefix =
+			process.env.XDG_DATA_HOME && isAbsolute(process.env.XDG_DATA_HOME)
+				? process.env.XDG_DATA_HOME
+				: join(homedir(), ".local/share");
+		web = await prepareWebUninstall({ stateDir: dirs.state, desktopPrefix });
+	} catch (error) {
+		presenter.fail(error instanceof Error ? error.message : "Web installation ownership could not be checked.");
+		presenter.finish();
+		return 1;
+	}
 
 	// The state root's own children (audit, sessions) are inside the State row
 	// and go with it; listing them again as separate removals double-counted the
@@ -372,6 +387,7 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 			detail: launcherItemDetail(launcher, args.removeBinary),
 		},
 	];
+	for (const item of web.items) items.push({ ...item, status: "remove", detail: "verified app ownership" });
 
 	// A login file is reported, never edited; see detectShellRcEdits.
 	for (const file of shellEdits) {
@@ -413,6 +429,16 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	}
 
 	const failures: RemovalFailure[] = [];
+	try {
+		await web.remove();
+		for (const item of web.items) presenter.completedStep(`Removed ${item.label}`);
+	} catch (error) {
+		presenter.fail(
+			error instanceof Error ? error.message : "Could not stop the web installation; Clio state was preserved.",
+		);
+		presenter.finish();
+		return 1;
+	}
 
 	if (cacheSize.exists) {
 		const failure = removePath("cache", dirs.cache, false);

package/src/cli/usage.ts

@@ -85,6 +85,7 @@ interface UsageTotals {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd: number;
@@ -169,6 +170,7 @@ function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
 		output: row.usage.output ?? 0,
 		cacheRead: row.usage.cacheRead ?? 0,
 		cacheWrite: row.usage.cacheWrite ?? 0,
+		...(typeof row.usage.cacheWrite1h === "number" ? { cacheWrite1h: row.usage.cacheWrite1h } : {}),
 		reasoningTokens: row.usage.reasoning ?? 0,
 		totalTokens: row.usage.totalTokens ?? 0,
 		costUsd: row.usage.costUsd ?? 0,
@@ -197,6 +199,7 @@ function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.output += call.output;
 	totals.cacheRead += call.cacheRead;
 	totals.cacheWrite += call.cacheWrite;
+	if (call.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + call.cacheWrite1h;
 	totals.reasoningTokens += call.reasoningTokens;
 	totals.totalTokens += call.totalTokens;
 	totals.costUsd += call.costUsd;

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/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;

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/termination.ts

@@ -29,6 +29,16 @@ interface RegisteredHook {
 	timeoutMs?: number;
 }
 
+function registeredHook(hook: Hook, options?: { timeoutMs: number }): RegisteredHook {
+	if (
+		options &&
+		(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
+	) {
+		throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
+	}
+	return { run: hook, ...options };
+}
+
 /** Wall-clock budget per hook and per domain.stop() call. */
 export const DEFAULT_SHUTDOWN_HOOK_MS = 500;
 
@@ -141,19 +151,13 @@ class TerminationCoordinator {
 	}
 
 	onDrain(hook: Hook, options?: { timeoutMs: number }): void {
-		if (
-			options &&
-			(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
-		) {
-			throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
-		}
-		this.drainHooks.push({ run: hook, ...options });
+		this.drainHooks.push(registeredHook(hook, options));
 	}
 	onTerminate(hook: Hook): void {
 		this.terminateHooks.push({ run: hook });
 	}
-	onPersist(hook: Hook): void {
-		this.persistHooks.push({ run: hook });
+	onPersist(hook: Hook, options?: { timeoutMs: number }): void {
+		this.persistHooks.push(registeredHook(hook, options));
 	}
 
 	async shutdown(code = 0): Promise<void> {

package/src/domains/agents/contract.ts

@@ -3,7 +3,7 @@ import type { AgentRecipeDiagnostic } from "./registry.js";
 import type { AgentSpec } from "./spec.js";
 
 export interface AgentsContract {
-	/** Monotonic catalog revision; changes after every successful discovery. */
+	/** Monotonic catalog revision; changes after discovery or external-agent settings updates. */
 	revision(): number;
 	/** Raw recipes as loaded from Markdown files. */
 	list(): ReadonlyArray<AgentRecipe>;

package/src/domains/agents/extension.ts

@@ -29,10 +29,22 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 		rediscoveryPending = false;
 	}
 
-	let unsubscribeExtensionsReload: (() => void) | null = null;
+	let unsubscribePluginsReload: (() => void) | null = null;
+	let unsubscribeConfigChange: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			discover();
+			unsubscribeConfigChange =
+				_context.getContract<ConfigContract>("config")?.onChange("nextTurn", ({ diff }) => {
+					if (
+						diff.nextTurn.some(
+							(path) =>
+								path === "integrations.externalAgents.entries" || path.startsWith("integrations.externalAgents.entries."),
+						)
+					) {
+						revision += 1;
+					}
+				}) ?? null;
 			// Recipes are cached at start; plugin agent roots come from the
 			// committed plugin generation, so a changed generation rediscovers.
 			const onResourceReload = (payload: unknown) => {
@@ -69,17 +81,13 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 					);
 				}
 			};
-			const unsubscribe = [
-				_context.bus.on(BusChannels.ExtensionsReloaded, onResourceReload),
-				_context.bus.on(BusChannels.PluginsReloaded, onResourceReload),
-			];
-			unsubscribeExtensionsReload = () => {
-				for (const stop of unsubscribe) stop();
-			};
+			unsubscribePluginsReload = _context.bus.on(BusChannels.PluginsReloaded, onResourceReload);
 		},
 		async stop() {
-			unsubscribeExtensionsReload?.();
-			unsubscribeExtensionsReload = null;
+			unsubscribePluginsReload?.();
+			unsubscribePluginsReload = null;
+			unsubscribeConfigChange?.();
+			unsubscribeConfigChange = null;
 		},
 	};
 

package/src/domains/config/extension.ts

@@ -116,13 +116,14 @@ export function createConfigBundle(
 		update(mutate) {
 			if (!snapshot) throw new Error("config domain not started");
 			const previous = snapshot;
-			const candidate = structuredClone(previous);
-			mutate(candidate);
-			assertAgentNamespace(candidate);
 			// Apply the effective-view delta to the user document under one lock,
 			// then validate it with the project layers before writing. In particular,
 			// a route may name a target supplied only by this workspace.
-			const normalized = updateLayeredSettings(process.cwd(), mutate);
+			const normalized = updateLayeredSettings(process.cwd(), (candidate) => {
+				const next = mutate(candidate) ?? candidate;
+				assertAgentNamespace(next);
+				return next;
+			});
 			snapshot = normalized;
 			setGitCommitAttributionEnabled(normalized.integrations.git.commitAttribution);
 			const diff = diffSettings(previous, normalized);