@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/cli/docs.ts

@@ -1,354 +1,91 @@
-import { spawn } from "node:child_process";
-import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import type { AddressInfo } from "node:net";
-import { relative, resolve } from "node:path";
-import chalk from "chalk";
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
 import { resolvePackageRoot } from "../core/package-root.js";
-import { printError, printHeader } from "./argv.js";
-
-// Human-facing viewer over the source-checkout HTML blueprints. It binds an ephemeral
-// static file server to 127.0.0.1 only, serves docs/html/index.html as the
-// menu plus the blueprint pages, prints the URL, and runs until SIGINT. It
-// uses only Node's built-in http and fs: zero new dependencies, no daemon, no
-// persisted state, no telemetry, and no external network. The static-path
-// resolution and the menu synthesis are pure functions so they unit-test
-// without binding a port.
-
-const HOST = "127.0.0.1";
+import { printError } from "./argv.js";
+import { runWebCommand } from "./web.js";
 
 const HELP = `clio-coder docs [topic] [--no-open]
 
-Serve Clio Coder's interactive HTML documentation locally and open it in a
-browser. The blueprints live in docs/html of a source checkout; the npm package
-ships the categorized Markdown reference tree under docs/ and excludes HTML.
-The server binds an ephemeral port on
-127.0.0.1, keeps no state, runs no daemon, and reaches no external network.
-Press Ctrl+C to stop it.
+Open the documentation in the Clio Coder web app. Pages, navigation and outlines
+are rendered from the same Markdown reference shipped with Clio.
 
 Arguments:
-  [topic]      deep-link a specific blueprint (for example: safety, configuration,
-               tools). Omit to open the documentation menu.
+  [topic]      a topic such as safety, configuration, or fleet_dispatch, or a
+               document path such as architecture/safety-model.md.
+               Omit to open the documentation map.
 
 Flags:
-  --no-open    do not launch a browser; just print the URL.
+  --no-open    print the private launch link without opening a browser.
   --help, -h   this message.
-`;
-
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-	".html": "text/html; charset=utf-8",
-	".htm": "text/html; charset=utf-8",
-	".css": "text/css; charset=utf-8",
-	".js": "text/javascript; charset=utf-8",
-	".mjs": "text/javascript; charset=utf-8",
-	".json": "application/json; charset=utf-8",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".webp": "image/webp",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".ico": "image/x-icon",
-	".woff": "font/woff",
-	".woff2": "font/woff2",
-	".ttf": "font/ttf",
-	".map": "application/json; charset=utf-8",
-	".txt": "text/plain; charset=utf-8",
-};
-
-export interface DocsMenuEntry {
-	/** Short deep-link key, for example `safety`. */
-	topic: string;
-	/** Real on-disk file name, for example `safety_blueprint.html`. */
-	file: string;
-	/** Human label, for example `Safety`. */
-	label: string;
-}
-
-/** Resolve the source-checkout HTML root. The npm package deliberately excludes it. */
-function resolveDocsHtmlDir(): string {
-	return resolve(resolvePackageRoot(), "docs", "html");
-}
 
-/** Content-type for a file path by extension. Pure. Defaults to octet-stream. */
-function contentTypeFor(filePath: string): string {
-	const dot = filePath.lastIndexOf(".");
-	if (dot === -1) return "application/octet-stream";
-	return CONTENT_TYPES[filePath.slice(dot).toLowerCase()] ?? "application/octet-stream";
-}
-
-/**
- * Map a request URL to a safe relative path under the html root. Pure: no disk
- * access. Strips the query and fragment, decodes percent-escapes, defaults `/`
- * to `index.html`, and rejects any traversal segment so a request can never
- * escape the served directory.
- */
-function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
-	const pathPart = (rawUrl.split(/[?#]/, 1)[0] ?? "").trim();
-	let decoded: string;
-	try {
-		decoded = decodeURIComponent(pathPart);
-	} catch {
-		return { ok: false, reason: "bad-request" };
-	}
-	if (decoded.includes("\0")) return { ok: false, reason: "forbidden" };
-	const segments = decoded.split(/[/\\]/).filter((segment) => segment.length > 0 && segment !== ".");
-	if (segments.length === 0) return { ok: true, relative: "index.html" };
-	for (const segment of segments) {
-		if (segment === "..") return { ok: false, reason: "forbidden" };
-	}
-	return { ok: true, relative: segments.join("/") };
-}
-
-function titleize(topic: string): string {
-	return topic
-		.split(/[-_]+/)
-		.filter((word) => word.length > 0)
-		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-		.join(" ");
-}
-
-/**
- * Synthesize the deep-linkable topic menu from a directory listing. Pure: takes
- * the file-name list, not the directory. `index.html` is the menu itself and is
- * excluded; a trailing `_blueprint` is stripped from the topic key.
- */
-function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
-	const entries: DocsMenuEntry[] = [];
-	for (const name of fileNames) {
-		if (!name.toLowerCase().endsWith(".html")) continue;
-		if (name.toLowerCase() === "index.html") continue;
-		const topic = name.replace(/\.html$/i, "").replace(/_blueprint$/i, "");
-		entries.push({ topic, file: name, label: titleize(topic) });
-	}
-	entries.sort((a, b) => a.topic.localeCompare(b.topic));
-	return entries;
-}
-
-/**
- * Resolve a user-supplied `[topic]` to a real file name. Pure. Accepts the bare
- * topic (`safety`), the blueprint file stem (`safety_blueprint`), or a full
- * `.html` name, case-insensitively. Returns null when nothing matches.
- */
-function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
-	const wanted = topic
-		.trim()
-		.toLowerCase()
-		.replace(/\.html$/i, "");
-	if (wanted.length === 0) return null;
-	for (const candidate of [`${wanted}.html`, `${wanted}_blueprint.html`]) {
-		const match = fileNames.find((name) => name.toLowerCase() === candidate);
-		if (match) return match;
-	}
-	const hit = synthesizeMenu(fileNames).find((entry) => entry.topic.toLowerCase() === wanted);
-	return hit ? hit.file : null;
-}
-
-function isWithin(child: string, parent: string): boolean {
-	const rel = relative(parent, child);
-	return rel === "" || (!rel.startsWith("..") && !rel.startsWith(`..${"/"}`) && !/^([A-Za-z]:)?[/\\]/.test(rel));
-}
-
-function listHtmlFiles(htmlDir: string): string[] {
-	try {
-		return readdirSync(htmlDir)
-			.filter((name) => name.toLowerCase().endsWith(".html"))
-			.sort((a, b) => a.localeCompare(b));
-	} catch {
-		return [];
-	}
-}
+Reuses your installed background app when available. Otherwise starts a local
+foreground web server on 127.0.0.1; press Ctrl+C to stop it. No background service
+is installed by this command. Your current directory does not affect the docs.
+`;
 
-/** Build the static request handler for one html root. */
-export function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
-	const root = realpathSync(resolve(htmlDir));
-	return (req, res) => {
-		if (req.method !== "GET" && req.method !== "HEAD") {
-			res.writeHead(405, { "content-type": "text/plain; charset=utf-8", allow: "GET, HEAD" });
-			res.end("method not allowed");
-			return;
-		}
-		const resolved = resolveRequestPath(req.url ?? "/");
-		if (!resolved.ok) {
-			const status = resolved.reason === "forbidden" ? 403 : 400;
-			res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
-			res.end(resolved.reason);
-			return;
-		}
-		const requestedTarget = resolve(root, resolved.relative);
-		if (!isWithin(requestedTarget, root)) {
-			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-			res.end("forbidden");
-			return;
-		}
-		let size: number | null = null;
-		let target: string | null = null;
-		try {
-			target = realpathSync(requestedTarget);
-			if (!isWithin(target, root)) {
-				res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-				res.end("forbidden");
-				return;
-			}
-			const stat = statSync(target);
-			if (stat.isFile()) size = stat.size;
-		} catch {
-			size = null;
-		}
-		if (size === null || target === null) {
-			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-			res.end("not found");
-			return;
-		}
-		const headers = {
-			"content-type": contentTypeFor(target),
-			"content-length": String(size),
-			"cache-control": "no-store",
-		};
-		if (req.method === "HEAD") {
-			res.writeHead(200, headers);
-			res.end();
-			return;
-		}
-		res.writeHead(200, headers);
-		const stream = createReadStream(target);
-		stream.on("error", () => {
-			if (!res.writableEnded) res.end();
-		});
-		stream.pipe(res);
+const key = (value: string) => value.toLowerCase().replace(/_/g, "-");
+const route = (path: string) => `/docs/${path.split("/").map(encodeURIComponent).join("/")}`;
+
+/** Resolve only catalogued destinations; ambiguous basenames require a full path. */
+export function docsTopicRoute(topic: string | undefined, pages: readonly string[]): string | undefined {
+	if (topic === undefined) return "/docs";
+	if (!topic || /[\\\0?#]/.test(topic) || topic.startsWith("/") || topic.split("/").includes("..")) return;
+	const wanted = key(topic.replace(/^docs\//, ""));
+	const topics: Record<string, string> = {
+		safety: "architecture/safety-model.md",
+		configuration: "guide/configuration-and-targets.md",
+		trace: "architecture/trace-store.md",
 	};
-}
-
-export interface DocsServerHandle {
-	server: Server;
-	url: string;
-	port: number;
-	close(): Promise<void>;
-}
-
-export interface StartDocsServerOptions {
-	htmlDir: string;
-	/** Bind host. Defaults to 127.0.0.1 and is never widened. */
-	host?: string;
-	/** Bind port. Defaults to 0 (ephemeral). */
-	port?: number;
-}
-
-/** Start the viewer bound to 127.0.0.1 on an ephemeral port. */
-async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
-	const host = options.host ?? HOST;
-	const server = createServer(createDocsRequestHandler(options.htmlDir));
-	await new Promise<void>((resolveListen, rejectListen) => {
-		const onError = (err: Error): void => rejectListen(err);
-		server.once("error", onError);
-		server.listen(options.port ?? 0, host, () => {
-			server.removeListener("error", onError);
-			resolveListen();
-		});
-	});
-	const address = server.address() as AddressInfo;
-	const port = address.port;
-	return {
-		server,
-		port,
-		url: `http://${host}:${port}/`,
-		close: () => new Promise<void>((resolveClose) => server.close(() => resolveClose())),
+	const preferred = topics[wanted];
+	if (preferred && pages.includes(preferred)) return route(preferred);
+	const exact = pages.find((path) => key(path) === wanted || key(path.replace(/\.md$/i, "")) === wanted);
+	if (exact) return route(exact);
+	const name = wanted.replace(/\.md$/, "");
+	const exactNames = pages.filter((path) => key(basename(path).replace(/\.md$/i, "")) === name);
+	const matches = exactNames.length
+		? exactNames
+		: pages.filter((path) => key(basename(path).replace(/\.md$/i, "")).startsWith(`${name}-`));
+	const match = matches[0];
+	return matches.length === 1 && match ? route(match) : undefined;
+}
+
+function catalog(root: string) {
+	const pages: string[] = [];
+	const scan = (path: string) => {
+		for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+			const name = path ? `${path}/${entry.name}` : entry.name;
+			if (name === "html") continue;
+			if (entry.isDirectory()) scan(name);
+			else if (entry.isFile() && /\.md$/i.test(name)) pages.push(name);
+		}
 	};
+	scan("");
+	return pages;
 }
 
-function openBrowser(url: string): void {
-	const platform = process.platform;
-	const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-	const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-	try {
-		const child = spawn(command, args, { stdio: "ignore", detached: true });
-		child.on("error", () => {
-			// Best-effort: the printed URL is the fallback when no opener exists.
-		});
-		child.unref();
-	} catch {
-		// Best-effort: never fail the command because a browser could not launch.
-	}
-}
-
-export function waitForShutdown(): Promise<void> {
-	return new Promise((resolveShutdown) => {
-		const onSignal = (): void => {
-			process.removeListener("SIGINT", onSignal);
-			process.removeListener("SIGTERM", onSignal);
-			resolveShutdown();
-		};
-		process.once("SIGINT", onSignal);
-		process.once("SIGTERM", onSignal);
-	});
-}
-
-export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<number> {
+export async function runDocsCommand(args: readonly string[] = []): Promise<number> {
 	if (args.includes("--help") || args.includes("-h")) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	let noOpen = false;
-	const positionals: string[] = [];
-	for (const arg of args) {
-		if (arg === "--no-open") {
-			noOpen = true;
-			continue;
-		}
-		if (arg.startsWith("-")) {
-			printError(`unknown flag: ${arg}`);
-			process.stdout.write(HELP);
-			return 2;
-		}
-		positionals.push(arg);
-	}
-	if (positionals.length > 1) {
-		printError("docs accepts at most one [topic]");
-		process.stdout.write(HELP);
+	const positionals = args.filter((arg) => arg !== "--no-open");
+	const unknownFlag = positionals.find((arg) => arg.startsWith("-"));
+	if (unknownFlag || positionals.length > 1) {
+		printError(unknownFlag ? `unknown flag: ${unknownFlag}` : "docs accepts at most one [topic]");
 		return 2;
 	}
-
-	let htmlDir: string;
 	try {
-		htmlDir = resolveDocsHtmlDir();
-	} catch (err) {
-		printError(`could not resolve the docs HTML root: ${err instanceof Error ? err.message : String(err)}`);
-		return 1;
-	}
-	const files = listHtmlFiles(htmlDir);
-	if (files.length === 0) {
-		printError(`no HTML docs at ${htmlDir}`);
-		process.stdout.write(
-			`  the npm package ships only the categorized Markdown reference tree: ${resolve(resolvePackageRoot(), "docs")}\n` +
-				"  the interactive blueprints are in a source checkout and at https://github.com/iowarp/clio-coder/tree/main/docs/html\n",
-		);
-		return 1;
-	}
-
-	let landing = "index.html";
-	const topic = positionals[0];
-	if (topic !== undefined) {
-		const file = topicToFile(topic, files);
-		if (!file) {
-			printError(`unknown docs topic: ${topic}`);
-			const topics = synthesizeMenu(files).map((entry) => entry.topic);
-			if (topics.length > 0) process.stdout.write(`  available topics: ${topics.join(", ")}\n`);
+		const pages = catalog(join(resolvePackageRoot(), "docs"));
+		const path = docsTopicRoute(positionals[0], pages);
+		if (!path) {
+			printError(
+				`Unknown or ambiguous docs topic: ${positionals[0]}. Run clio-coder docs to browse the documentation map.`,
+			);
 			return 2;
 		}
-		landing = file;
+		return runWebCommand(["--path", path, "--reuse-background", args.includes("--no-open") ? "--no-open" : "--open"]);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not open the documentation.");
+		return 1;
 	}
-
-	const handle = await startDocsServer({ htmlDir });
-	const landingUrl = landing === "index.html" ? handle.url : `${handle.url}${landing}`;
-	printHeader("Clio docs viewer");
-	process.stdout.write(`  serving HTML root ${htmlDir}\n`);
-	process.stdout.write(`  open ${chalk.cyan(landingUrl)}\n`);
-	process.stdout.write("  bound to 127.0.0.1 only: no external network, no daemon, no state.\n");
-	process.stdout.write("  press Ctrl+C to stop.\n");
-	if (!noOpen) openBrowser(landingUrl);
-
-	await waitForShutdown();
-	await handle.close();
-	process.stdout.write("docs viewer stopped.\n");
-	return 0;
 }

package/src/cli/eval.ts

@@ -18,11 +18,15 @@ import { EvalSuiteFileError, loadEvalSuiteFile, loadV1TaskFileAsSuite } from "..
 import { resolveSuiteForRun } from "../domains/eval/suites/resolve.js";
 import { runEvalSuiteV2 } from "../domains/eval/suites/run.js";
 import { EvalTaskFileError } from "../domains/eval/task-file.js";
+import { resolveLibraryEval } from "../domains/resources/library-evals.js";
 import { printError } from "./shared.js";
 
 const HELP = `clio-coder eval <command>
 
 Commands:
+  clio-coder eval skill <name|path> [--scenario <id>] [--json]
+  clio-coder eval validate --package <path|kind:name> [--eval <name>] [--user|--project]
+  clio-coder eval run --package <path|kind:name> [--eval <name>] [--user|--project] [--out <path>]
   clio-coder eval validate --suite <suite.yaml>
 	  clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
 	  clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
@@ -60,6 +64,9 @@ interface ParsedEvalArgs {
 	baseline?: string;
 	thresholds?: string;
 	help: boolean;
+	package?: string;
+	packageEval?: string;
+	packageScope?: "user" | "project";
 }
 
 function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
@@ -84,6 +91,21 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 			}
 			throw new Error(`unknown eval command: ${arg}`);
 		}
+		if (parsed.command === "validate" || parsed.command === "run") {
+			if (arg === "--package" || arg === "--eval") {
+				const value = requiredValue(args, index++, arg);
+				if (arg === "--package") parsed.package = value;
+				else parsed.packageEval = value;
+				continue;
+			}
+			if (arg === "--user" || arg === "--project") {
+				const scope = arg === "--user" ? "user" : "project";
+				if (parsed.packageScope && parsed.packageScope !== scope)
+					throw new Error("--user and --project are mutually exclusive");
+				parsed.packageScope = scope;
+				continue;
+			}
+		}
 		if (parsed.command === "validate") {
 			if (arg === "--suite") {
 				parsed.suite = requiredValue(args, index, "--suite");
@@ -193,9 +215,12 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 	}
 	if (parsed.help) return parsed;
 	if (parsed.command === undefined) throw new Error("eval requires a command");
-	if (parsed.command === "validate" && parsed.suite === undefined) throw new Error("validate requires --suite <path>");
-	if (parsed.command === "run" && (parsed.suite === undefined) === (parsed.taskFile === undefined)) {
-		throw new Error("run requires exactly one of --suite or --task-file");
+	if (!parsed.package && (parsed.packageEval || parsed.packageScope))
+		throw new Error("--eval and scope flags require --package");
+	if (parsed.command === "validate" && [parsed.suite, parsed.package].filter(Boolean).length !== 1)
+		throw new Error("validate requires exactly one of --suite or --package");
+	if (parsed.command === "run" && [parsed.suite, parsed.taskFile, parsed.package].filter(Boolean).length !== 1) {
+		throw new Error("run requires exactly one of --suite, --task-file, or --package");
 	}
 	if (parsed.command === "report" && (parsed.evalId === undefined) === (parsed.artifact === undefined)) {
 		throw new Error("report requires exactly one of an eval id or --artifact <path>");
@@ -210,6 +235,7 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 }
 
 export async function runEvalCommand(args: ReadonlyArray<string>): Promise<number> {
+	if (args[0] === "skill") return (await import("./skills-eval.js")).runSkillEvalCli(args.slice(1));
 	// Routed before the shared parser so the fixed read stays exactly fixed: no
 	// eval flag can reach it, and no flag it does not name can be spent on it.
 	if (args[0] === "inventory") {
@@ -239,7 +265,10 @@ export async function runEvalCommand(args: ReadonlyArray<string>): Promise<numbe
 
 async function runEvalValidate(parsed: ParsedEvalArgs): Promise<number> {
 	try {
-		const loaded = await loadEvalSuiteFile(parsed.suite ?? "");
+		const declared = parsed.package
+			? resolveLibraryEval(parsed.package, parsed.packageEval, parsed.packageScope ? { scope: parsed.packageScope } : {})
+			: undefined;
+		const loaded = await loadEvalSuiteFile(declared?.path ?? parsed.suite ?? "");
 		process.stdout.write(`valid suite: ${loaded.suite.suite.id}\n`);
 		return 0;
 	} catch (error) {
@@ -249,10 +278,15 @@ async function runEvalValidate(parsed: ParsedEvalArgs): Promise<number> {
 
 async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 	try {
+		const declared = parsed.package
+			? resolveLibraryEval(parsed.package, parsed.packageEval, parsed.packageScope ? { scope: parsed.packageScope } : {})
+			: undefined;
+		const suitePath = declared?.path ?? parsed.suite;
 		const loaded =
-			parsed.suite !== undefined
-				? await loadEvalSuiteFile(parsed.suite)
+			suitePath !== undefined
+				? await loadEvalSuiteFile(suitePath)
 				: await loadV1TaskFileAsSuite(parsed.taskFile ?? "", parsed.trials ?? parsed.repeat);
+		if (declared) loaded.suite.suite.provenance = { ...loaded.suite.suite.provenance, library: declared.provenance };
 		const resolveOptions: { target?: string; model?: string } = {};
 		if (parsed.target !== undefined) resolveOptions.target = parsed.target;
 		if (parsed.model !== undefined) resolveOptions.model = parsed.model;

package/src/cli/extensions.ts

@@ -10,6 +10,7 @@ import {
 	listInstalledExtensions,
 	removeExtension,
 } from "../domains/extensions/index.js";
+import { extensionInvocation, OperatorExtensionRuntime } from "../domains/extensions/operator-runtime.js";
 import { formatColumns, printError, printOk } from "./shared.js";
 
 const HELP = `clio-coder extensions <command>
@@ -19,6 +20,7 @@ Manage Clio extension packages.
 Commands:
   clio-coder extensions list [--all] [--json] [--user|--project]
   clio-coder extensions discover <path> [--json]
+  clio-coder extensions run <id> <command> [--json] -- [arguments]
   clio-coder extensions install <path> [--user|--project] [--force] [--json]
   clio-coder extensions enable <id> [--user|--project] [--json]
   clio-coder extensions disable <id> [--user|--project] [--json]
@@ -37,7 +39,16 @@ interface Parsed {
 
 function parse(argv: ReadonlyArray<string>): Parsed {
 	const out: Parsed = { positional: [], json: false, all: false, force: false, help: false };
+	let argumentsOnly = false;
 	for (const arg of argv) {
+		if (argumentsOnly) {
+			out.positional.push(arg);
+			continue;
+		}
+		if (arg === "--") {
+			argumentsOnly = true;
+			continue;
+		}
 		if (!out.command && !arg.startsWith("-")) {
 			out.command = arg;
 			continue;
@@ -85,9 +96,9 @@ function printDiagnostics(diagnostics: ReadonlyArray<ExtensionDiagnostic>): void
 	}
 }
 
-function resourceSummary(extension: InstalledExtension): string {
-	const resources = Object.entries(extension.resources).map(([key, value]) => `${key}:${value}`);
-	return resources.length > 0 ? resources.join(",") : "-";
+function toolSummary(extension: InstalledExtension): string {
+	const tools = extension.capabilities?.tools.map((tool) => tool.name) ?? [];
+	return tools.length > 0 ? tools.join(",") : "-";
 }
 
 function stateLabel(extension: InstalledExtension): string {
@@ -95,7 +106,7 @@ function stateLabel(extension: InstalledExtension): string {
 	if (!extension.compatible) return "incompatible";
 	if (!extension.enabled) return "disabled";
 	if (!extension.effective) return `shadowed:${extension.overriddenBy ?? "higher"}`;
-	return extension.loadable ? "active" : "inactive";
+	return extension.loadable ? "eligible" : "inactive";
 }
 
 function printList(items: ReadonlyArray<InstalledExtension>): void {
@@ -105,20 +116,20 @@ function printList(items: ReadonlyArray<InstalledExtension>): void {
 	}
 	process.stdout.write(
 		`${formatColumns([
-			["id", "scope", "state", "version", "resources", "description"],
+			["id", "scope", "state", "version", "tools", "description"],
 			...items.map((extension) => [
 				extension.id,
 				extension.scope,
 				stateLabel(extension),
 				extension.version,
-				resourceSummary(extension),
+				toolSummary(extension),
 				extension.description,
 			]),
 		])}\n`,
 	);
 }
 
-export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
+export function runExtensionsCommand(argv: ReadonlyArray<string>): number | Promise<number> {
 	let parsed: Parsed;
 	try {
 		parsed = parse(argv);
@@ -142,6 +153,8 @@ export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
 	}
 	const scopeOptions = { ...(parsed.scope ? { scope: parsed.scope } : {}) };
 	switch (parsed.command) {
+		case "run":
+			return runOperatorCommand(parsed);
 		case "list": {
 			const items = listInstalledExtensions(process.cwd(), { ...scopeOptions, all: parsed.all });
 			if (parsed.json) process.stdout.write(`${JSON.stringify({ extensions: items }, null, 2)}\n`);
@@ -178,7 +191,13 @@ export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
 			if (parsed.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 			else {
 				printDiagnostics(result.diagnostics);
-				if (result.extension) printOk(`installed ${result.extension.id} (${result.extension.scope})`);
+				if (result.extension) {
+					printOk(`installed ${result.extension.id} (${result.extension.scope})`);
+					if (result.extension.runtime)
+						process.stderr.write(
+							"Operator runtime code starts on the next interactive startup/reload or explicit extensions run. Install only code you trust; it runs with your user account authority.\n",
+						);
+				}
 			}
 			return hasErrors(result.diagnostics) ? 1 : 0;
 		}
@@ -217,3 +236,50 @@ export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
 			return 2;
 	}
 }
+
+async function runOperatorCommand(parsed: Parsed): Promise<number> {
+	const [id, command, ...args] = parsed.positional;
+	if (!id || !command || parsed.scope || parsed.force || parsed.all) {
+		process.stderr.write("usage: clio-coder extensions run <id> <command> [--json] -- [arguments]\n");
+		return 2;
+	}
+	const selected = listInstalledExtensions(process.cwd(), { all: true }).find(
+		(entry) => entry.id === id && entry.loadable,
+	);
+	if (!selected?.runtime?.commands.some((entry) => entry.name === command)) {
+		printError(`extension ${id} has no eligible operator command '${command}'`);
+		return 1;
+	}
+	const runtime = new OperatorExtensionRuntime({
+		context: () => ({ workspace: process.cwd(), sessionId: null, mode: "headless" }),
+		isIdle: () => true,
+		onlyId: id,
+	});
+	const controller = new AbortController();
+	const cancel = (): void => {
+		controller.abort();
+		void runtime.dispose();
+	};
+	process.once("SIGINT", cancel);
+	process.once("SIGTERM", cancel);
+	try {
+		const reload = await runtime.reload("startup");
+		if (reload.status !== "committed") throw new Error(reload.message);
+		const provenance = runtime.entries().find((entry) => entry.id === id && entry.state === "ready")?.provenance;
+		const output = await runtime.invoke(extensionInvocation(id, command), args.join(" "), [], controller.signal);
+		if (!provenance) throw new Error("extension result has no activated provenance");
+		if (parsed.json)
+			process.stdout.write(
+				`${JSON.stringify({ extensionId: id, command, generation: reload.generation, provenance, output })}\n`,
+			);
+		else process.stdout.write(`${output.text}\n`);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 1;
+	} finally {
+		process.off("SIGINT", cancel);
+		process.off("SIGTERM", cancel);
+		await runtime.dispose();
+	}
+}