@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/components/scan.ts

@@ -0,0 +1,304 @@
+import type { Dirent } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { sha256Hex, stableJson } from "./hash.js";
+import type {
+	ComponentAuthority,
+	ComponentKind,
+	ComponentReloadClass,
+	ComponentSnapshot,
+	ComponentSnapshotOptions,
+	HarnessComponent,
+} from "./types.js";
+
+const KIND_ORDER: ReadonlyArray<ComponentKind> = [
+	"prompt-fragment",
+	"agent-recipe",
+	"tool-implementation",
+	"tool-helper",
+	"runtime-descriptor",
+	"safety-rule-pack",
+	"config-schema",
+	"session-schema",
+	"receipt-schema",
+	"context-file",
+	"doc-spec",
+	"middleware",
+	"memory",
+	"eval-suite",
+];
+
+const AUTHORITY_BY_KIND: Record<ComponentKind, ComponentAuthority> = {
+	"prompt-fragment": "advisory",
+	"context-file": "advisory",
+	"tool-implementation": "enforcing",
+	"tool-helper": "enforcing",
+	middleware: "enforcing",
+	"agent-recipe": "advisory",
+	"runtime-descriptor": "runtime-critical",
+	"safety-rule-pack": "enforcing",
+	"config-schema": "runtime-critical",
+	"session-schema": "runtime-critical",
+	"receipt-schema": "runtime-critical",
+	memory: "advisory",
+	"eval-suite": "descriptive",
+	"doc-spec": "descriptive",
+};
+
+const RELOAD_BY_KIND: Record<ComponentKind, ComponentReloadClass> = {
+	"prompt-fragment": "hot",
+	"context-file": "hot",
+	"tool-implementation": "hot",
+	"tool-helper": "restart-required",
+	middleware: "restart-required",
+	"agent-recipe": "next-dispatch",
+	"runtime-descriptor": "restart-required",
+	"safety-rule-pack": "restart-required",
+	"config-schema": "restart-required",
+	"session-schema": "restart-required",
+	"receipt-schema": "restart-required",
+	memory: "hot",
+	"eval-suite": "static",
+	"doc-spec": "static",
+};
+
+const OWNER_BY_KIND: Record<ComponentKind, string> = {
+	"prompt-fragment": "prompts",
+	"context-file": "repository",
+	"tool-implementation": "tools",
+	"tool-helper": "tools",
+	middleware: "middleware",
+	"agent-recipe": "agents",
+	"runtime-descriptor": "providers",
+	"safety-rule-pack": "safety",
+	"config-schema": "config",
+	"session-schema": "session",
+	"receipt-schema": "dispatch",
+	memory: "memory",
+	"eval-suite": "eval",
+	"doc-spec": "docs",
+};
+
+const TOOL_HELPER_FILES = new Set(["src/tools/bootstrap.ts", "src/tools/registry.ts", "src/tools/truncate-utf8.ts"]);
+
+const CONFIG_SCHEMA_FILES: ReadonlyArray<string> = [
+	"src/core/defaults.ts",
+	"src/core/config.ts",
+	"src/domains/config/schema.ts",
+];
+
+const SESSION_SCHEMA_FILES: ReadonlyArray<string> = [
+	"src/domains/session/entries.ts",
+	"src/domains/session/contract.ts",
+	"src/engine/session.ts",
+];
+
+const RECEIPT_SCHEMA_FILES: ReadonlyArray<string> = [
+	"src/domains/dispatch/types.ts",
+	"src/domains/dispatch/receipt-integrity.ts",
+];
+
+const CONTEXT_FILES: ReadonlyArray<string> = ["CLIO-CODER.md", "CONTRIBUTING.md", "SECURITY.md"];
+
+interface RawSafetyPack {
+	id: string;
+	value: unknown;
+}
+
+async function scanComponents(root: string): Promise<HarnessComponent[]> {
+	const absoluteRoot = resolve(root);
+	const components: HarnessComponent[] = [];
+	components.push(...(await collectRecursive(absoluteRoot, "src/domains/prompts/fragments", ".md", "prompt-fragment")));
+	components.push(...(await collectRecursive(absoluteRoot, "src/domains/agents/builtins", ".md", "agent-recipe")));
+	components.push(...(await collectTools(absoluteRoot)));
+	components.push(
+		...(await collectRecursive(absoluteRoot, "src/domains/providers/runtimes", ".ts", "runtime-descriptor")),
+	);
+	components.push(...(await collectSafetyRulePacks(absoluteRoot)));
+	components.push(...(await collectKnownFiles(absoluteRoot, CONFIG_SCHEMA_FILES, "config-schema")));
+	components.push(...(await collectKnownFiles(absoluteRoot, SESSION_SCHEMA_FILES, "session-schema")));
+	components.push(...(await collectKnownFiles(absoluteRoot, RECEIPT_SCHEMA_FILES, "receipt-schema")));
+	components.push(...(await collectKnownFiles(absoluteRoot, CONTEXT_FILES, "context-file")));
+	components.push(...(await collectRecursive(absoluteRoot, "docs/specs", ".md", "doc-spec")));
+	return sortComponents(components);
+}
+
+export async function createComponentSnapshot(options: ComponentSnapshotOptions): Promise<ComponentSnapshot> {
+	const root = resolve(options.root);
+	const generatedAt = (options.generatedAt ?? new Date()).toISOString();
+	return {
+		version: 1,
+		generatedAt,
+		root,
+		components: await scanComponents(root),
+	};
+}
+
+async function collectRecursive(
+	root: string,
+	dirPath: string,
+	extension: string,
+	kind: ComponentKind,
+): Promise<HarnessComponent[]> {
+	const files = await listFiles(join(root, dirPath));
+	const matching = files
+		.map((filePath) => toRepoPath(root, filePath))
+		.filter((repoPath) => repoPath.endsWith(extension))
+		.sort((a, b) => a.localeCompare(b));
+	return collectKnownFiles(root, matching, kind);
+}
+
+async function collectTools(root: string): Promise<HarnessComponent[]> {
+	const files = await listFiles(join(root, "src/tools"));
+	const repoPaths = files
+		.map((filePath) => toRepoPath(root, filePath))
+		.filter((repoPath) => repoPath.startsWith("src/tools/") && repoPath.endsWith(".ts"))
+		.sort((a, b) => a.localeCompare(b));
+	const components: HarnessComponent[] = [];
+	for (const repoPath of repoPaths) {
+		const kind: ComponentKind = TOOL_HELPER_FILES.has(repoPath) ? "tool-helper" : "tool-implementation";
+		const component = await componentFromFile(root, repoPath, kind);
+		if (component) components.push(component);
+	}
+	return components;
+}
+
+async function collectKnownFiles(
+	root: string,
+	paths: ReadonlyArray<string>,
+	kind: ComponentKind,
+): Promise<HarnessComponent[]> {
+	const components: HarnessComponent[] = [];
+	for (const repoPath of [...paths].sort((a, b) => a.localeCompare(b))) {
+		const component = await componentFromFile(root, repoPath, kind);
+		if (component) components.push(component);
+	}
+	return components;
+}
+
+async function componentFromFile(
+	root: string,
+	repoPath: string,
+	kind: ComponentKind,
+): Promise<HarnessComponent | null> {
+	const absolutePath = join(root, repoPath);
+	if (!(await isFile(absolutePath))) return null;
+	const content = await readFile(absolutePath);
+	return baseComponent({
+		id: `${kind}:${repoPath}`,
+		kind,
+		path: repoPath,
+		contentHash: sha256Hex(content),
+	});
+}
+
+async function collectSafetyRulePacks(root: string): Promise<HarnessComponent[]> {
+	const repoPath = "damage-control-rules.yaml";
+	const absolutePath = join(root, repoPath);
+	if (!(await isFile(absolutePath))) return [];
+	const content = await readFile(absolutePath, "utf8");
+	const packs = parseSafetyPacks(content);
+	return packs
+		.map((pack) =>
+			baseComponent({
+				id: `safety-rule-pack:${pack.id}`,
+				kind: "safety-rule-pack",
+				path: repoPath,
+				contentHash: sha256Hex(stableJson(pack.value)),
+				description: `damage-control rule pack: ${pack.id}`,
+			}),
+		)
+		.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function parseSafetyPacks(content: string): RawSafetyPack[] {
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(content);
+	} catch {
+		return [];
+	}
+	if (!isRecord(parsed)) return [];
+	const version = parsed.version;
+	if (version === 1) {
+		return [{ id: "base", value: { version, rules: parsed.rules ?? [] } }];
+	}
+	if (version !== 2 || !Array.isArray(parsed.packs)) return [];
+	const packs: RawSafetyPack[] = [];
+	for (const pack of parsed.packs) {
+		if (!isRecord(pack) || typeof pack.id !== "string" || pack.id.length === 0) continue;
+		packs.push({ id: pack.id, value: pack });
+	}
+	return packs.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function baseComponent(input: {
+	id: string;
+	kind: ComponentKind;
+	path: string;
+	contentHash: string;
+	description?: string;
+}): HarnessComponent {
+	const component: HarnessComponent = {
+		id: input.id,
+		kind: input.kind,
+		path: input.path,
+		ownerDomain: OWNER_BY_KIND[input.kind],
+		mutable: true,
+		authority: AUTHORITY_BY_KIND[input.kind],
+		reloadClass: RELOAD_BY_KIND[input.kind],
+		contentHash: input.contentHash,
+	};
+	if (input.description !== undefined) component.description = input.description;
+	return component;
+}
+
+async function listFiles(dirPath: string): Promise<string[]> {
+	let entries: Dirent<string>[];
+	try {
+		entries = await readdir(dirPath, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const files: string[] = [];
+	for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+		const fullPath = join(dirPath, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...(await listFiles(fullPath)));
+			continue;
+		}
+		if (entry.isFile()) files.push(fullPath);
+	}
+	return files;
+}
+
+async function isFile(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function toRepoPath(root: string, filePath: string): string {
+	const rel = relative(root, filePath);
+	const normalized = rel.split(sep).join("/");
+	return isAbsolute(normalized) ? normalized : normalized;
+}
+
+function sortComponents(components: ReadonlyArray<HarnessComponent>): HarnessComponent[] {
+	const kindRank = new Map(KIND_ORDER.map((kind, index) => [kind, index] as const));
+	return [...components].sort((a, b) => {
+		const rankA = kindRank.get(a.kind) ?? KIND_ORDER.length;
+		const rankB = kindRank.get(b.kind) ?? KIND_ORDER.length;
+		if (rankA !== rankB) return rankA - rankB;
+		const pathOrder = a.path.localeCompare(b.path);
+		if (pathOrder !== 0) return pathOrder;
+		return a.id.localeCompare(b.id);
+	});
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/domains/components/snapshot.ts

@@ -0,0 +1,108 @@
+import { readFile } from "node:fs/promises";
+import {
+	COMPONENT_AUTHORITIES,
+	COMPONENT_KINDS,
+	COMPONENT_RELOAD_CLASSES,
+	type ComponentAuthority,
+	type ComponentKind,
+	type ComponentReloadClass,
+	type ComponentSnapshot,
+	type HarnessComponent,
+} from "./types.js";
+
+export async function loadComponentSnapshot(path: string): Promise<ComponentSnapshot> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		// Same voice as the invalid-JSON refusal below: name the artifact, then
+		// the path, rather than repeating node:fs at the operator.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`component snapshot not found: ${path}`);
+		throw error;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw) as unknown;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`${path}: invalid JSON: ${message}`);
+	}
+	return parseComponentSnapshot(parsed, path);
+}
+
+function parseComponentSnapshot(value: unknown, source = "snapshot"): ComponentSnapshot {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	if (value.version !== 1) throw new Error(`${source}: expected version 1`);
+	if (typeof value.generatedAt !== "string" || value.generatedAt.length === 0) {
+		throw new Error(`${source}: expected generatedAt string`);
+	}
+	if (typeof value.root !== "string" || value.root.length === 0) {
+		throw new Error(`${source}: expected root string`);
+	}
+	if (!Array.isArray(value.components)) throw new Error(`${source}: expected components array`);
+	return {
+		version: 1,
+		generatedAt: value.generatedAt,
+		root: value.root,
+		components: value.components.map((component, index) =>
+			parseHarnessComponent(component, `${source}:components[${index}]`),
+		),
+	};
+}
+
+function parseHarnessComponent(value: unknown, source: string): HarnessComponent {
+	if (!isRecord(value)) throw new Error(`${source}: expected object`);
+	const id = readString(value, source, "id");
+	const kind = readEnum(value, source, "kind", COMPONENT_KINDS);
+	const path = readString(value, source, "path");
+	const ownerDomain = readString(value, source, "ownerDomain");
+	const mutable = readBoolean(value, source, "mutable");
+	const authority = readEnum(value, source, "authority", COMPONENT_AUTHORITIES);
+	const reloadClass = readEnum(value, source, "reloadClass", COMPONENT_RELOAD_CLASSES);
+	const contentHash = readString(value, source, "contentHash");
+	if (!/^[a-f0-9]{64}$/.test(contentHash)) throw new Error(`${source}: expected contentHash sha256 hex`);
+	const component: HarnessComponent = {
+		id,
+		kind,
+		path,
+		ownerDomain,
+		mutable,
+		authority,
+		reloadClass,
+		contentHash,
+	};
+	if (Object.hasOwn(value, "description")) {
+		if (typeof value.description !== "string") throw new Error(`${source}: expected description string`);
+		component.description = value.description;
+	}
+	return component;
+}
+
+function readString(record: Record<string, unknown>, source: string, field: string): string {
+	const value = record[field];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${source}: expected ${field} string`);
+	return value;
+}
+
+function readBoolean(record: Record<string, unknown>, source: string, field: string): boolean {
+	const value = record[field];
+	if (typeof value !== "boolean") throw new Error(`${source}: expected ${field} boolean`);
+	return value;
+}
+
+function readEnum<T extends ComponentKind | ComponentAuthority | ComponentReloadClass>(
+	record: Record<string, unknown>,
+	source: string,
+	field: string,
+	values: ReadonlyArray<T>,
+): T {
+	const value = record[field];
+	if (typeof value !== "string" || !values.includes(value as T)) {
+		throw new Error(`${source}: expected ${field} to be one of ${values.join(", ")}`);
+	}
+	return value as T;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/domains/components/types.ts

@@ -0,0 +1,82 @@
+export const COMPONENT_KINDS = [
+	"prompt-fragment",
+	"context-file",
+	"tool-implementation",
+	"tool-helper",
+	"middleware",
+	"agent-recipe",
+	"runtime-descriptor",
+	"safety-rule-pack",
+	"config-schema",
+	"session-schema",
+	"receipt-schema",
+	"memory",
+	"eval-suite",
+	"doc-spec",
+] as const;
+
+export type ComponentKind = (typeof COMPONENT_KINDS)[number];
+
+export const COMPONENT_AUTHORITIES = ["advisory", "descriptive", "enforcing", "runtime-critical"] as const;
+
+export type ComponentAuthority = (typeof COMPONENT_AUTHORITIES)[number];
+
+export const COMPONENT_RELOAD_CLASSES = ["hot", "next-dispatch", "restart-required", "static"] as const;
+
+export type ComponentReloadClass = (typeof COMPONENT_RELOAD_CLASSES)[number];
+
+export interface HarnessComponent {
+	id: string;
+	kind: ComponentKind;
+	path: string;
+	ownerDomain: string;
+	mutable: boolean;
+	authority: ComponentAuthority;
+	reloadClass: ComponentReloadClass;
+	contentHash: string;
+	description?: string;
+}
+
+export interface ComponentSnapshot {
+	version: 1;
+	generatedAt: string;
+	root: string;
+	components: HarnessComponent[];
+}
+
+export interface ComponentSnapshotOptions {
+	root: string;
+	generatedAt?: Date;
+}
+
+export type ComponentFieldName = keyof HarnessComponent;
+
+export interface ComponentSnapshotRef {
+	root: string;
+	generatedAt: string;
+	componentCount: number;
+}
+
+export interface ComponentDiffSummary {
+	added: number;
+	removed: number;
+	changed: number;
+	unchanged: number;
+}
+
+export interface ChangedHarnessComponent {
+	id: string;
+	before: HarnessComponent;
+	after: HarnessComponent;
+	changedFields: ComponentFieldName[];
+}
+
+export interface ComponentDiff {
+	version: 1;
+	from: ComponentSnapshotRef;
+	to: ComponentSnapshotRef;
+	summary: ComponentDiffSummary;
+	added: HarnessComponent[];
+	removed: HarnessComponent[];
+	changed: ChangedHarnessComponent[];
+}

package/src/domains/config/agent-namespace.ts

@@ -0,0 +1,13 @@
+/** Native recipes and ACP delegation agents share the operator-facing id namespace. */
+export function assertAgentIdNamespace(
+	nativeRecipes: ReadonlyArray<{ id: string }>,
+	acpDelegates: ReadonlyArray<{ id: string }>,
+): void {
+	const native = new Set(nativeRecipes.map((recipe) => recipe.id));
+	const collision = acpDelegates.find((delegate) => native.has(delegate.id));
+	if (collision !== undefined) {
+		throw new Error(
+			`agent id collision: native recipe '${collision.id}' and ACP delegation agent '${collision.id}' share one namespace`,
+		);
+	}
+}

package/src/domains/config/classify.ts

@@ -0,0 +1,94 @@
+import type { ClioSettings } from "../../core/config.js";
+
+/**
+ * Classifies a settings change into one of three buckets per spec §13:
+ *   - hotReload   : theme, keybindings, safety rules, prompt fragments,
+ *                   audit verbosity. Apply immediately (≤100ms).
+ *   - nextTurn    : model selection, thinking level, budget ceiling. Apply before the
+ *                   next turn starts.
+ *   - restartRequired : provider credentials, active provider list, runtime enable/disable,
+ *                       engine settings. Needs a restart nudge.
+ *
+ * Output is an exhaustive per-bucket list. A single patch can touch multiple buckets;
+ * the caller emits the event(s) for every non-empty bucket.
+ */
+
+export type ChangeKind = "hotReload" | "nextTurn" | "restartRequired";
+
+export interface ConfigDiff {
+	hotReload: string[];
+	nextTurn: string[];
+	restartRequired: string[];
+}
+
+const HOT_RELOAD_FIELDS = new Set<string>(["theme", "keybindings", "autonomy", "modelSelector"]);
+
+const NEXT_TURN_FIELDS = new Set<string>([
+	"identity",
+	"targets",
+	"orchestrator.target",
+	"orchestrator.model",
+	"orchestrator.thinkingLevel",
+	"background.target",
+	"background.model",
+	"background.thinkingLevel",
+	"memory",
+	"workers.default.target",
+	"workers.default.model",
+	"workers.default.thinkingLevel",
+	"workers.profiles",
+	"workers.agentBindings",
+	"workers.maxRetries",
+	"workers.onPermission",
+	"fleet",
+	"routing",
+	"scope",
+	"budget.sessionCeilingUsd",
+	"defaults",
+	"terminal",
+	"skills",
+	"delegation",
+	"compaction",
+	"retry",
+]);
+
+const RESTART_REQUIRED_FIELDS = new Set<string>(["budget.concurrency", "runtimePlugins"]);
+
+function matchesPrefix(path: string, fields: Set<string>): boolean {
+	if (fields.has(path)) return true;
+	for (const field of fields) {
+		if (path.startsWith(`${field}.`)) return true;
+	}
+	return false;
+}
+
+export function diffSettings(prev: ClioSettings, next: ClioSettings): ConfigDiff {
+	const changed = collectChangedPaths(prev, next);
+	const diff: ConfigDiff = { hotReload: [], nextTurn: [], restartRequired: [] };
+	for (const p of changed) {
+		if (matchesPrefix(p, HOT_RELOAD_FIELDS)) diff.hotReload.push(p);
+		else if (matchesPrefix(p, NEXT_TURN_FIELDS)) diff.nextTurn.push(p);
+		else if (matchesPrefix(p, RESTART_REQUIRED_FIELDS)) diff.restartRequired.push(p);
+		else {
+			// Unknown field falls back to restartRequired to fail closed.
+			diff.restartRequired.push(p);
+		}
+	}
+	return diff;
+}
+
+function collectChangedPaths(a: unknown, b: unknown, prefix = ""): string[] {
+	if (Object.is(a, b)) return [];
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+		return [prefix || "(root)"];
+	}
+	const keys = new Set([...Object.keys(a as object), ...Object.keys(b as object)]);
+	const paths: string[] = [];
+	for (const k of keys) {
+		const nextPrefix = prefix ? `${prefix}.${k}` : k;
+		const av = (a as Record<string, unknown>)[k];
+		const bv = (b as Record<string, unknown>)[k];
+		paths.push(...collectChangedPaths(av, bv, nextPrefix));
+	}
+	return paths;
+}

package/src/domains/config/contract.ts

@@ -0,0 +1,22 @@
+import type { ClioSettings, SettingsMutator } from "../../core/config.js";
+import type { ChangeKind, ConfigDiff } from "./classify.js";
+
+/**
+ * The ConfigDomain's external surface. Other domains import this through the contract
+ * returned by the domain loader, never by reaching into extension.ts.
+ */
+export interface ConfigContract {
+	get(): Readonly<ClioSettings>;
+	set?(next: ClioSettings): void;
+	/**
+	 * Cross-process-safe read-modify-write: the mutator runs against the
+	 * freshest on-disk settings while holding the advisory settings lock, so
+	 * two processes patching different fields cannot drop each other's writes.
+	 * Refreshes the in-memory snapshot and dispatches change events like set.
+	 */
+	update?(mutate: SettingsMutator): void;
+	onChange(
+		kind: ChangeKind,
+		listener: (payload: { diff: ConfigDiff; settings: Readonly<ClioSettings> }) => void,
+	): () => void;
+}