@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/cli/acp.ts

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { runClioCommand } from "./clio.js";
+import { restoreStdout, takeOverStdout, writeRawStdout } from "./output-guard.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder acp [--cwd PATH] [--permission-timeout MS]
+
+Serve Clio Coder as an Agent Client Protocol v1 agent over stdio.
+
+  --cwd PATH               Workspace root the server boots in and opens sessions at.
+  --permission-timeout MS  How long a mediated permission request may wait for the
+                           client before it is denied. Defaults to the configured
+                           delegation.defaults.permissionTimeoutMs.
+
+This command is intended for ACP frontends to spawn. Interactive delegation remains
+available through /agents, /delegate, the dispatch board, and receipts.
+`;
+
+interface AcpFlags {
+	cwd?: string;
+	permissionTimeoutMs?: number;
+}
+
+/** Parsed flags, or the message explaining why the invocation is not usable. */
+function parseAcpFlags(args: ReadonlyArray<string>): AcpFlags | string {
+	const flags: AcpFlags = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		const value = args[index + 1];
+		if (arg === "--cwd") {
+			if (value === undefined) return "--cwd needs a directory";
+			flags.cwd = path.resolve(value);
+			index += 1;
+			continue;
+		}
+		if (arg === "--permission-timeout") {
+			const ms = value === undefined ? Number.NaN : Number(value);
+			if (!Number.isInteger(ms) || ms <= 0) return "--permission-timeout needs a positive whole number of milliseconds";
+			flags.permissionTimeoutMs = ms;
+			index += 1;
+			continue;
+		}
+		return `unknown clio-coder acp option: ${arg ?? ""}`;
+	}
+	return flags;
+}
+
+export async function runAcpCommand(
+	args: ReadonlyArray<string>,
+	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
+): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const flags = parseAcpFlags(args);
+	if (typeof flags === "string") {
+		printError(flags);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	// Boot has to happen in the workspace the sessions will use: settings
+	// resolution, project context, and the session ledger all read process.cwd(),
+	// and the server refuses a session whose cwd is not the one it booted in.
+	if (flags.cwd !== undefined) {
+		try {
+			process.chdir(flags.cwd);
+		} catch {
+			printError(`--cwd is not a directory this process can enter: ${flags.cwd}`);
+			return 2;
+		}
+	}
+	takeOverStdout();
+	try {
+		return await runClioCommand({
+			...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+			...(options.noContextFiles ? { noContextFiles: true } : {}),
+			...(options.noSkills ? { noSkills: true } : {}),
+			...(options.skillPaths && options.skillPaths.length > 0 ? { skillPaths: options.skillPaths } : {}),
+			acp: {
+				transportOptions: { write: writeRawStdout },
+				...(flags.permissionTimeoutMs === undefined ? {} : { permissionTimeoutMs: flags.permissionTimeoutMs }),
+			},
+		});
+	} finally {
+		restoreStdout();
+	}
+}

package/src/cli/agents.ts

@@ -0,0 +1,60 @@
+import { loadDomains } from "../core/domain-loader.js";
+import type { AgentsContract } from "../domains/agents/contract.js";
+import { AgentsDomainModule } from "../domains/agents/index.js";
+import { type AgentSpec, isUserVisibleAgent } from "../domains/agents/spec.js";
+import { ConfigDomainModule } from "../domains/config/index.js";
+import { ensureClioState } from "../domains/lifecycle/index.js";
+import { SafetyDomainModule } from "../domains/safety/index.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder agents [--json] [--all]
+
+List user-facing agent specs from built-in, user, and project recipes.
+
+Flags:
+  --json   emit specs as JSON instead of the formatted table
+  --all    include shadow/internal specs reserved for Clio orchestration
+`;
+
+export async function runAgentsCommand(args: ReadonlyArray<string>): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const json = args.includes("--json");
+	const all = args.includes("--all");
+	const unknown = args.find((arg) => arg !== "--json" && arg !== "--all");
+	if (unknown) {
+		printError(`unknown flag: ${unknown}`);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	ensureClioState();
+	const result = await loadDomains([ConfigDomainModule, SafetyDomainModule, AgentsDomainModule]);
+	const agents = result.getContract<AgentsContract>("agents");
+	if (!agents) {
+		process.stderr.write("agents: domain not loaded\n");
+		await result.stop();
+		return 1;
+	}
+	const specs = all ? agents.listSpecs() : agents.listSpecs().filter(isUserVisibleAgent);
+	if (json) {
+		const withoutBody = specs.map(({ body: _body, ...rest }) => rest);
+		process.stdout.write(`${JSON.stringify(withoutBody, null, 2)}\n`);
+	} else {
+		for (const spec of specs) {
+			renderLine(spec);
+		}
+	}
+	await result.stop();
+	return 0;
+}
+
+function renderLine(spec: AgentSpec): void {
+	const shape = `${spec.audience}/${spec.category}/${spec.capabilityClass}/${spec.latencyClass}`;
+	const skills = spec.skills.length > 0 ? ` skills=${spec.skills.join(",")}` : "";
+	const budget = spec.budget
+		? `${spec.budget.toolCalls}/${spec.budget.readReserve}/${spec.budget.synthesis ? "synthesize" : "stop"}`
+		: "operator-default";
+	process.stdout.write(`${spec.id.padEnd(20)} ${shape.padEnd(48)} ${spec.description}${skills} budget=${budget}\n`);
+}

package/src/cli/args.ts

@@ -0,0 +1,280 @@
+import { THINKING_LEVELS } from "../core/defaults.js";
+import type { JobThinkingLevel } from "../domains/dispatch/validation.js";
+import { AUTONOMY_LEVELS, type AutonomyLevel } from "../domains/safety/autonomy.js";
+import { globalFlagPositionHint } from "./argv.js";
+
+export interface CliArgDiagnostic {
+	type: "warning" | "error";
+	message: string;
+}
+
+export interface RunSamplingArgs {
+	temperature?: number;
+	topP?: number;
+	topK?: number;
+	minP?: number;
+	presencePenalty?: number;
+	frequencyPenalty?: number;
+	repeatPenalty?: number;
+}
+
+export type RunJsonEventsMode = "full" | "terminal";
+
+export interface RunCliArgs {
+	help: boolean;
+	json: boolean;
+	jsonEvents: RunJsonEventsMode;
+	target?: string;
+	model?: string;
+	thinking?: JobThinkingLevel;
+	autonomy?: AutonomyLevel;
+	sampling?: RunSamplingArgs;
+	agentId?: string;
+	agentProfile?: string;
+	agentRuntime?: string;
+	toolProfile?: string;
+	required: string[];
+	noSkills: boolean;
+	skillPaths: string[];
+	maxContextTokens?: number;
+	kvCacheMode?: string;
+	steerChannel?: string;
+	/** Resume this exact session and append the turn to it. */
+	sessionId?: string;
+	/** Resume the most recent session for this workspace. */
+	continueSession: boolean;
+	fileArgs: string[];
+	messages: string[];
+	diagnostics: CliArgDiagnostic[];
+}
+
+const VALID_THINKING: ReadonlyArray<JobThinkingLevel> = THINKING_LEVELS;
+
+export function parseRunCliArgs(argv: ReadonlyArray<string>): RunCliArgs {
+	const parsed: RunCliArgs = {
+		help: false,
+		json: false,
+		jsonEvents: "full",
+		required: [],
+		noSkills: false,
+		continueSession: false,
+		skillPaths: [],
+		fileArgs: [],
+		messages: [],
+		diagnostics: [],
+	};
+
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const need = (flag: string): string | null => {
+			const value = argv[i + 1];
+			if (value === undefined || (value.startsWith("-") && !isNumericLiteral(value))) {
+				parsed.diagnostics.push({ type: "error", message: `${flag} requires a value` });
+				return null;
+			}
+			i += 1;
+			return value;
+		};
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--json-events") {
+			const value = need(arg);
+			if (value !== null) {
+				parsed.json = true;
+				if (value === "full" || value === "terminal") parsed.jsonEvents = value;
+				else parsed.diagnostics.push({ type: "error", message: "--json-events must be one of: full|terminal" });
+			}
+			continue;
+		}
+		if (arg === "--target") {
+			const value = need(arg);
+			if (value !== null) parsed.target = value;
+			continue;
+		}
+		if (arg === "--model") {
+			const value = need(arg);
+			if (value !== null) parsed.model = value;
+			continue;
+		}
+		if (arg === "--thinking") {
+			const value = need(arg);
+			if (value !== null) {
+				if (VALID_THINKING.includes(value as JobThinkingLevel)) parsed.thinking = value as JobThinkingLevel;
+				else
+					parsed.diagnostics.push({
+						type: "error",
+						message: "--thinking must be one of: off|minimal|low|medium|high|xhigh|max",
+					});
+			}
+			continue;
+		}
+		if (arg === "--autonomy") {
+			const value = need(arg);
+			if (value !== null) {
+				if (AUTONOMY_LEVELS.includes(value as AutonomyLevel)) parsed.autonomy = value as AutonomyLevel;
+				else
+					parsed.diagnostics.push({
+						type: "error",
+						message: "--autonomy must be one of: read-only|suggest|auto-edit|full-auto",
+					});
+			}
+			continue;
+		}
+		if (arg === "--temperature") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "temperature", value, { min: 0 });
+			continue;
+		}
+		if (arg === "--top-p") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "topP", value, { min: 0, max: 1 });
+			continue;
+		}
+		if (arg === "--top-k") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "topK", value, { min: 0, integer: true });
+			continue;
+		}
+		if (arg === "--min-p") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "minP", value, { min: 0, max: 1 });
+			continue;
+		}
+		if (arg === "--presence-penalty") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "presencePenalty", value);
+			continue;
+		}
+		if (arg === "--frequency-penalty") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "frequencyPenalty", value);
+			continue;
+		}
+		if (arg === "--repeat-penalty") {
+			const value = need(arg);
+			if (value !== null) setNumberOption(parsed, "repeatPenalty", value);
+			continue;
+		}
+		if (arg === "--agent") {
+			const value = need(arg);
+			if (value !== null) parsed.agentId = value;
+			continue;
+		}
+		if (arg === "--agent-profile" || arg === "--worker-profile" || arg === "--worker") {
+			const value = need(arg);
+			if (value !== null) parsed.agentProfile = value;
+			continue;
+		}
+		if (arg === "--agent-runtime" || arg === "--worker-runtime" || arg === "--runtime") {
+			const value = need(arg);
+			if (value !== null) parsed.agentRuntime = value;
+			continue;
+		}
+		if (arg === "--tool-profile") {
+			const value = need(arg);
+			if (value !== null) parsed.toolProfile = value;
+			continue;
+		}
+		if (arg === "--require") {
+			const value = need(arg);
+			if (value !== null) parsed.required.push(value);
+			continue;
+		}
+		if (arg === "--no-skills") {
+			parsed.noSkills = true;
+			continue;
+		}
+		if (arg === "--skill") {
+			const value = need(arg);
+			if (value !== null) parsed.skillPaths.push(value);
+			continue;
+		}
+		if (arg === "--max-context-tokens") {
+			const value = need(arg);
+			if (value !== null) {
+				const n = Number(value);
+				if (Number.isInteger(n) && n > 0) {
+					parsed.maxContextTokens = n;
+				} else {
+					parsed.diagnostics.push({ type: "error", message: "--max-context-tokens must be a positive integer" });
+				}
+			}
+			continue;
+		}
+		if (arg === "--kv-cache-mode") {
+			const value = need(arg);
+			if (value !== null) {
+				parsed.kvCacheMode = value;
+			}
+			continue;
+		}
+		if (arg === "--session") {
+			const value = need(arg);
+			if (value !== null) {
+				parsed.sessionId = value;
+			}
+			continue;
+		}
+		if (arg === "--continue") {
+			parsed.continueSession = true;
+			continue;
+		}
+		if (arg === "--steer-channel") {
+			const value = need(arg);
+			if (value !== null) {
+				parsed.steerChannel = value;
+			}
+			continue;
+		}
+		if (arg?.startsWith("-")) {
+			parsed.diagnostics.push({
+				type: "error",
+				message: globalFlagPositionHint(arg, "run") ?? `unknown clio-coder run option: ${arg}`,
+			});
+			continue;
+		}
+		if (arg !== undefined) {
+			if (arg.startsWith("@") && arg.length > 1) parsed.fileArgs.push(arg.slice(1));
+			else parsed.messages.push(arg);
+		}
+	}
+
+	return parsed;
+}
+
+function setNumberOption(
+	parsed: RunCliArgs,
+	key: keyof NonNullable<RunCliArgs["sampling"]>,
+	raw: string,
+	limits: { min?: number; max?: number; integer?: boolean } = {},
+): void {
+	const value = Number(raw);
+	if (!Number.isFinite(value)) {
+		parsed.diagnostics.push({ type: "error", message: `--${kebab(key)} must be a number` });
+		return;
+	}
+	if (limits.min !== undefined && value < limits.min) {
+		parsed.diagnostics.push({ type: "error", message: `--${kebab(key)} must be >= ${limits.min}` });
+		return;
+	}
+	if (limits.max !== undefined && value > limits.max) {
+		parsed.diagnostics.push({ type: "error", message: `--${kebab(key)} must be <= ${limits.max}` });
+		return;
+	}
+	const normalized = limits.integer === true ? Math.floor(value) : value;
+	parsed.sampling = { ...(parsed.sampling ?? {}), [key]: normalized };
+}
+
+function kebab(value: string): string {
+	return value.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+
+function isNumericLiteral(value: string): boolean {
+	return value.startsWith("-") && !value.startsWith("--") && Number.isFinite(Number(value));
+}

package/src/cli/argv.ts

@@ -0,0 +1,170 @@
+/**
+ * Dependency-light CLI argument parsing and terminal formatting. This module
+ * imports nothing from the domain graph (only `chalk`), so `cli/index.ts` can
+ * parse argv and dispatch without dragging provider/auth code (and its
+ * transitive pi-* externals) into the eagerly loaded startup chunk. `shared.ts`
+ * re-exports everything here for the command modules, which already pay for the
+ * heavier graph.
+ */
+
+import chalk from "chalk";
+
+export function printError(message: string, detail?: string): void {
+	const head = chalk.red("error:");
+	process.stderr.write(`${head} ${message}\n`);
+	if (detail) process.stderr.write(`  ${detail}\n`);
+}
+
+export function printOk(message: string): void {
+	process.stdout.write(`${chalk.green("ok:")} ${message}\n`);
+}
+
+export function printHeader(message: string): void {
+	process.stdout.write(`${chalk.cyan(message)}\n`);
+}
+
+export function columnWidths(rows: ReadonlyArray<ReadonlyArray<string>>): number[] {
+	const widths: number[] = [];
+	for (const row of rows) {
+		for (let i = 0; i < row.length; i += 1) {
+			widths[i] = Math.max(widths[i] ?? 0, row[i]?.length ?? 0);
+		}
+	}
+	return widths;
+}
+
+export function formatColumnRow(row: ReadonlyArray<string>, widths: ReadonlyArray<number>, gap = 2): string {
+	return row
+		.map((cell, index) => {
+			if (index === row.length - 1) return cell;
+			return cell.padEnd((widths[index] ?? cell.length) + gap);
+		})
+		.join("")
+		.trimEnd();
+}
+
+export function formatColumns(rows: ReadonlyArray<ReadonlyArray<string>>, gap = 2): string {
+	if (rows.length === 0) return "";
+	const widths = columnWidths(rows);
+	return `${rows.map((row) => formatColumnRow(row, widths, gap)).join("\n")}\n`;
+}
+
+export function parseFlags(argv: string[]): { flags: Set<string>; positional: string[] } {
+	const flags = new Set<string>();
+	const positional: string[] = [];
+	for (const arg of argv) {
+		if (arg.startsWith("--")) flags.add(arg.slice(2));
+		else if (arg.startsWith("-") && arg.length > 1) flags.add(arg.slice(1));
+		else positional.push(arg);
+	}
+	return { flags, positional };
+}
+
+export interface GlobalCliFlags {
+	apiKey?: string;
+	noContextFiles: boolean;
+	noSkills: boolean;
+	skillPaths: string[];
+	rest: string[];
+	error?: string;
+}
+
+const ROOT_FLAG_TOKENS = new Set(["--help", "-h", "--all", "--version", "-v"]);
+
+/**
+ * Startup flags a subcommand parser will never accept, mapped to the form the
+ * hint should show. `--no-skills` and `--skill` are deliberately absent: both
+ * are also `clio-coder run` options, so either position works and no hint is owed.
+ */
+const GLOBAL_ONLY_FLAGS: ReadonlyMap<string, string> = new Map([
+	["--api-key", "--api-key <key>"],
+	["--no-context-files", "--no-context-files"],
+	["-nc", "-nc"],
+]);
+
+/**
+ * Explain the ordering rule when a rejected option is a global one in the
+ * wrong position. `clio-coder run --no-context-files` failed with nothing but
+ * "unknown option" while `clio-coder --no-context-files run` worked, which leaves the
+ * user guessing at a rule the help text states only by where it lists the flag.
+ */
+export function globalFlagPositionHint(arg: string, command: string): string | null {
+	const usage = GLOBAL_ONLY_FLAGS.get(arg);
+	if (usage === undefined) return null;
+	return `${arg} is a global option and must come before the subcommand: clio-coder ${usage} ${command} ...`;
+}
+
+/**
+ * Extract every global startup flag in one order-independent pass. Only flags
+ * before the first positional command are global; later occurrences belong to
+ * the subcommand. Keeping the value-taking flags in the same state machine is
+ * important: three sequential extractors used to mistake one another's values
+ * for the command boundary, so `--skill path --api-key SECRET paths` treated
+ * SECRET as a subcommand and printed it in an error.
+ */
+export function extractGlobalFlags(
+	argv: ReadonlyArray<string>,
+	isSubcommand: (token: string) => boolean = () => false,
+): GlobalCliFlags {
+	const rest: string[] = [];
+	let apiKey: string | undefined;
+	let noContextFiles = false;
+	let noSkills = false;
+	const skillPaths: string[] = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === undefined) continue;
+		if (arg === "--") {
+			rest.push(...argv.slice(i + 1));
+			break;
+		}
+		if (!arg.startsWith("-")) {
+			rest.push(...argv.slice(i));
+			break;
+		}
+		if (ROOT_FLAG_TOKENS.has(arg)) {
+			rest.push(arg);
+			continue;
+		}
+		if (arg === "--no-context-files" || arg === "-nc") {
+			noContextFiles = true;
+			continue;
+		}
+		if (arg === "--no-skills") {
+			noSkills = true;
+			continue;
+		}
+		if (arg === "--api-key" || arg === "--skill") {
+			const value = argv[i + 1];
+			if (value === undefined || value.startsWith("-") || isSubcommand(value)) {
+				return {
+					noContextFiles,
+					noSkills,
+					skillPaths,
+					rest,
+					error: `${arg} requires a value`,
+					...(apiKey === undefined ? {} : { apiKey }),
+				};
+			}
+			if (arg === "--api-key") apiKey = value;
+			else skillPaths.push(value);
+			i += 1;
+			continue;
+		}
+		return {
+			noContextFiles,
+			noSkills,
+			skillPaths,
+			rest,
+			error: `unknown global option: ${arg}`,
+			...(apiKey === undefined ? {} : { apiKey }),
+		};
+	}
+	return {
+		noContextFiles,
+		noSkills,
+		skillPaths,
+		rest,
+		...(apiKey === undefined ? {} : { apiKey }),
+	};
+}

package/src/cli/ask.ts

@@ -0,0 +1,34 @@
+import type { createInterface } from "node:readline/promises";
+
+export async function ask(
+	rl: ReturnType<typeof createInterface>,
+	label: string,
+	defaultValue?: string,
+): Promise<string | null> {
+	const suffix = defaultValue && defaultValue.length > 0 ? ` [${defaultValue}]` : "";
+	try {
+		const answer = (await rl.question(`${label}${suffix}: `)).trim();
+		if (answer.length === 0) return defaultValue ?? "";
+		if (answer.toLowerCase() === "q" || answer.toLowerCase() === "quit") return null;
+		return answer;
+	} catch {
+		return null;
+	}
+}
+
+export async function askYesNo(
+	rl: ReturnType<typeof createInterface>,
+	label: string,
+	defaultValue: boolean,
+): Promise<boolean> {
+	const marker = defaultValue ? "Y/n" : "y/N";
+	for (;;) {
+		const answer = await ask(rl, `${label} [${marker}]`);
+		if (answer === null) return defaultValue;
+		if (answer.length === 0) return defaultValue;
+		const lc = answer.toLowerCase();
+		if (lc === "y" || lc === "yes") return true;
+		if (lc === "n" || lc === "no") return false;
+		process.stderr.write(`invalid response: ${answer}\n`);
+	}
+}