@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/extensions/state.ts

@@ -0,0 +1,224 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import path from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { isRecord, loadManifestFromRoot, trimString } from "./discovery.js";
+import type {
+	ExtensionInstallOptions,
+	ExtensionInstallResult,
+	ExtensionListOptions,
+	ExtensionMutationResult,
+	ExtensionScope,
+	ExtensionState,
+	InstalledExtension,
+} from "./types.js";
+
+const DEFAULT_STATE: ExtensionState = { version: 1, disabled: [], installed: {} };
+
+export function extensionBaseDir(scope: ExtensionScope, cwd = process.cwd()): string {
+	return scope === "user"
+		? path.join(clioConfigDir(), "extensions")
+		: path.join(path.resolve(cwd), ".clio-coder", "extensions");
+}
+
+function statePath(scope: ExtensionScope, cwd = process.cwd()): string {
+	return path.join(extensionBaseDir(scope, cwd), "state.json");
+}
+
+export function scopeRank(scope: ExtensionScope): number {
+	return scope === "project" ? 2 : 1;
+}
+
+function readState(scope: ExtensionScope, cwd = process.cwd()): ExtensionState {
+	const filePath = statePath(scope, cwd);
+	if (!existsSync(filePath)) return structuredClone(DEFAULT_STATE);
+	try {
+		const parsed = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+		if (!isRecord(parsed) || parsed.version !== 1) return structuredClone(DEFAULT_STATE);
+		const disabled = Array.isArray(parsed.disabled)
+			? parsed.disabled.filter((entry): entry is string => typeof entry === "string")
+			: [];
+		const installed = isRecord(parsed.installed)
+			? Object.fromEntries(
+					Object.entries(parsed.installed).flatMap(([id, raw]) => {
+						if (!isRecord(raw)) return [];
+						const installedAt = trimString(raw.installedAt) ?? new Date(0).toISOString();
+						const source = trimString(raw.source);
+						return [[id, { installedAt, ...(source ? { source } : {}) }]];
+					}),
+				)
+			: {};
+		return { version: 1, disabled, installed };
+	} catch {
+		return structuredClone(DEFAULT_STATE);
+	}
+}
+
+function writeState(scope: ExtensionScope, state: ExtensionState, cwd = process.cwd()): void {
+	const filePath = statePath(scope, cwd);
+	safeResourceWrite(filePath, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8" });
+}
+
+function installedFromRoot(root: string, scope: ExtensionScope, state: ExtensionState): InstalledExtension | null {
+	const candidate = loadManifestFromRoot(root);
+	const manifest = candidate.manifest;
+	if (!manifest || !candidate.manifestPath) return null;
+	return {
+		id: manifest.id,
+		name: manifest.name,
+		version: manifest.version,
+		description: manifest.description,
+		scope,
+		rootPath: root,
+		manifestPath: candidate.manifestPath,
+		enabled: !state.disabled.includes(manifest.id),
+		effective: false,
+		resources: manifest.resources,
+		diagnostics: candidate.diagnostics,
+	};
+}
+
+function listScope(scope: ExtensionScope, cwd = process.cwd()): InstalledExtension[] {
+	const base = extensionBaseDir(scope, cwd);
+	if (!existsSync(base)) return [];
+	const state = readState(scope, cwd);
+	const out: InstalledExtension[] = [];
+	for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		if (!entry.isDirectory()) continue;
+		const root = path.join(base, entry.name);
+		const installed = installedFromRoot(root, scope, state);
+		if (installed) out.push(installed);
+	}
+	return out;
+}
+
+export function listInstalledExtensions(cwd = process.cwd(), options: ExtensionListOptions = {}): InstalledExtension[] {
+	const scopes: ExtensionScope[] = options.scope ? [options.scope] : ["user", "project"];
+	const entries = scopes.flatMap((scope) => listScope(scope, cwd));
+	const byId = new Map<string, InstalledExtension[]>();
+	for (const entry of entries) {
+		const list = byId.get(entry.id) ?? [];
+		list.push(entry);
+		byId.set(entry.id, list);
+	}
+	for (const group of byId.values()) {
+		const winner = [...group].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope)).at(-1);
+		for (const entry of group) {
+			entry.effective = entry === winner;
+			if (!entry.effective && winner) entry.overriddenBy = winner.scope;
+		}
+	}
+	const all = options.all === true ? entries : entries.filter((entry) => entry.effective);
+	return all.sort((a, b) => {
+		const id = a.id.localeCompare(b.id);
+		if (id !== 0) return id;
+		return scopeRank(a.scope) - scopeRank(b.scope);
+	});
+}
+
+function findInstalled(id: string, cwd: string, scope?: ExtensionScope): InstalledExtension | null {
+	const entries = listInstalledExtensions(cwd, { ...(scope ? { scope } : {}), all: true }).filter(
+		(entry) => entry.id === id,
+	);
+	if (entries.length === 0) return null;
+	return [...entries].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope)).at(-1) ?? null;
+}
+
+export function installExtension(sourcePath: string, options: ExtensionInstallOptions = {}): ExtensionInstallResult {
+	const scope = options.scope ?? "user";
+	const cwd = options.cwd ?? process.cwd();
+	const source = path.resolve(sourcePath);
+	const candidate = loadManifestFromRoot(source);
+	if (!candidate.manifest) return { diagnostics: candidate.diagnostics };
+	const targetRoot = path.join(extensionBaseDir(scope, cwd), candidate.manifest.id);
+	if (existsSync(targetRoot)) {
+		if (!options.force) {
+			return {
+				diagnostics: [
+					{ type: "error", message: `extension ${candidate.manifest.id} is already installed`, path: targetRoot },
+				],
+			};
+		}
+	}
+	const parent = path.dirname(targetRoot);
+	const stagingRoot = path.join(parent, `.${candidate.manifest.id}.install-${process.pid}-${Date.now()}`);
+	const backupRoot = path.join(parent, `.${candidate.manifest.id}.backup-${process.pid}-${Date.now()}`);
+	let installedReplacement = false;
+	let movedExisting = false;
+	const state = readState(scope, cwd);
+	try {
+		mkdirSync(parent, { recursive: true });
+		rmSync(stagingRoot, { recursive: true, force: true });
+		rmSync(backupRoot, { recursive: true, force: true });
+		cpSync(source, stagingRoot, {
+			recursive: true,
+			filter: (src) => path.basename(src) !== "state.json",
+		});
+		if (existsSync(targetRoot)) {
+			renameSync(targetRoot, backupRoot);
+			movedExisting = true;
+		}
+		renameSync(stagingRoot, targetRoot);
+		installedReplacement = true;
+		state.installed[candidate.manifest.id] = { installedAt: new Date().toISOString(), source };
+		state.disabled = state.disabled.filter((entry) => entry !== candidate.manifest?.id);
+		writeState(scope, state, cwd);
+		rmSync(backupRoot, { recursive: true, force: true });
+	} catch (error) {
+		rmSync(stagingRoot, { recursive: true, force: true });
+		if (installedReplacement) rmSync(targetRoot, { recursive: true, force: true });
+		if (movedExisting && existsSync(backupRoot) && !existsSync(targetRoot)) {
+			renameSync(backupRoot, targetRoot);
+		}
+		return {
+			diagnostics: [
+				{
+					type: "error",
+					message: `extension ${candidate.manifest.id} install failed: ${error instanceof Error ? error.message : String(error)}`,
+					path: targetRoot,
+				},
+			],
+		};
+	}
+	const installed = findInstalled(candidate.manifest.id, cwd, scope);
+	return {
+		...(installed ? { extension: installed } : {}),
+		diagnostics: candidate.diagnostics,
+	};
+}
+
+function mutateEnabled(id: string, enabled: boolean, options: ExtensionListOptions = {}): ExtensionMutationResult {
+	const cwd = options.cwd ?? process.cwd();
+	const target = findInstalled(id, cwd, options.scope);
+	if (!target) {
+		return { diagnostics: [{ type: "error", message: `extension ${id} is not installed` }] };
+	}
+	const state = readState(target.scope, cwd);
+	if (enabled) state.disabled = state.disabled.filter((entry) => entry !== id);
+	else if (!state.disabled.includes(id)) state.disabled.push(id);
+	writeState(target.scope, state, cwd);
+	const extension = findInstalled(id, cwd, target.scope) ?? undefined;
+	return { ...(extension ? { extension } : {}), diagnostics: [] };
+}
+
+export function enableExtension(id: string, options: ExtensionListOptions = {}): ExtensionMutationResult {
+	return mutateEnabled(id, true, options);
+}
+
+export function disableExtension(id: string, options: ExtensionListOptions = {}): ExtensionMutationResult {
+	return mutateEnabled(id, false, options);
+}
+
+export function removeExtension(id: string, options: ExtensionListOptions = {}): ExtensionMutationResult {
+	const cwd = options.cwd ?? process.cwd();
+	const target = findInstalled(id, cwd, options.scope);
+	if (!target) {
+		return { diagnostics: [{ type: "error", message: `extension ${id} is not installed` }] };
+	}
+	rmSync(target.rootPath, { recursive: true, force: true });
+	const state = readState(target.scope, cwd);
+	Reflect.deleteProperty(state.installed, id);
+	state.disabled = state.disabled.filter((entry) => entry !== id);
+	writeState(target.scope, state, cwd);
+	return { removed: { id, scope: target.scope, path: target.rootPath }, diagnostics: [] };
+}

package/src/domains/extensions/types.ts

@@ -0,0 +1,83 @@
+export type ExtensionScope = "user" | "project";
+export type ExtensionResourceKind = "skills" | "prompts" | "themes";
+
+export interface ExtensionManifestResources {
+	skills?: string;
+	prompts?: string;
+	themes?: string;
+}
+
+export interface ClioExtensionManifest {
+	manifestVersion: 1;
+	id: string;
+	name: string;
+	version: string;
+	description: string;
+	resources: ExtensionManifestResources;
+	tools?: string[];
+	settings?: string[];
+	compatibility?: { clio?: string };
+}
+
+export interface ExtensionDiagnostic {
+	type: "warning" | "error";
+	message: string;
+	path?: string;
+}
+
+export interface InstalledExtension {
+	id: string;
+	name: string;
+	version: string;
+	description: string;
+	scope: ExtensionScope;
+	rootPath: string;
+	manifestPath: string;
+	enabled: boolean;
+	effective: boolean;
+	resources: ExtensionManifestResources;
+	overriddenBy?: ExtensionScope;
+	diagnostics: ExtensionDiagnostic[];
+}
+
+export interface ExtensionCandidate {
+	path: string;
+	manifestPath?: string;
+	manifest?: ClioExtensionManifest;
+	valid: boolean;
+	diagnostics: ExtensionDiagnostic[];
+}
+
+export interface ExtensionResourceRoot {
+	id: string;
+	scope: ExtensionScope;
+	path: string;
+	source: string;
+}
+
+export interface ExtensionListOptions {
+	scope?: ExtensionScope;
+	cwd?: string;
+	all?: boolean;
+}
+
+export interface ExtensionInstallOptions extends ExtensionListOptions {
+	force?: boolean;
+}
+
+export interface ExtensionInstallResult {
+	extension?: InstalledExtension;
+	diagnostics: ExtensionDiagnostic[];
+}
+
+export interface ExtensionMutationResult {
+	extension?: InstalledExtension;
+	removed?: { id: string; scope: ExtensionScope; path: string };
+	diagnostics: ExtensionDiagnostic[];
+}
+
+export interface ExtensionState {
+	version: 1;
+	disabled: string[];
+	installed: Record<string, { installedAt: string; source?: string }>;
+}

package/src/domains/interop/consent.ts

@@ -0,0 +1,185 @@
+import { stringify as stringifyYaml } from "yaml";
+import { type ClioSettings, readSettings, updateSettings } from "../../core/config.js";
+import type { DelegationAgentConfig } from "../../core/defaults.js";
+import { withStateFileLockSync } from "../../core/state-file-lock.js";
+import { interopAgentKind } from "./registry.js";
+import { interopStatePath, readInteropReport, writeInteropReport } from "./state.js";
+import type {
+	InteropAgentId,
+	InteropAgentKind,
+	InteropAgentRecord,
+	InteropDecision,
+	InteropDecisionResult,
+	InteropProposal,
+	InteropReport,
+} from "./types.js";
+
+/**
+ * A wired peer inherits `projectContext: "none"`, so repo conventions never
+ * leave the machine unless the operator opts this agent in later. The key is
+ * left out of the written entry precisely so it tracks that default.
+ */
+export const INHERITED_PROJECT_CONTEXT = "none";
+
+/** The delegation entry a given agent kind would be wired as. */
+export function delegationEntryForKind(
+	kind: InteropAgentKind,
+	defaults: ClioSettings["delegation"]["defaults"],
+): DelegationAgentConfig {
+	const recipe = kind.acp;
+	if (recipe === undefined) throw new Error(`interop kind ${kind.id} has no ACP recipe`);
+	return {
+		id: kind.id,
+		command: recipe.command,
+		args: [...recipe.args],
+		connectTimeoutMs: defaults.connectTimeoutMs,
+		turnTimeoutMs: defaults.turnTimeoutMs,
+		permissionTimeoutMs: defaults.permissionTimeoutMs,
+		toolGovernance: "clio-policy",
+	};
+}
+
+/**
+ * Agents the operator has not decided on yet. A standing decision suppresses
+ * re-proposal only while the facts it was made against still hold, so a
+ * declined agent whose binary or version moved comes back as a fresh proposal.
+ */
+export function interopProposals(report: InteropReport, settings: ClioSettings): ReadonlyArray<InteropProposal> {
+	const configured = new Set(settings.delegation.agents.map((agent) => agent.id));
+	const proposals: InteropProposal[] = [];
+	for (const record of report.agents) {
+		const kind = interopAgentKind(record.kind);
+		if (kind?.acp === undefined) continue;
+		if (record.presence !== "present") continue;
+		if (configured.has(kind.id)) continue;
+		if (record.decision !== undefined && record.decidedFingerprint === record.fingerprint) continue;
+		proposals.push({
+			kind: kind.id,
+			label: kind.label,
+			fingerprint: record.fingerprint,
+			entry: delegationEntryForKind(kind, settings.delegation.defaults),
+			needsNetworkInstall: record.adapter !== "present",
+		});
+	}
+	return proposals;
+}
+
+/** The exact YAML the entry lands as, rendered by the writer's own serializer. */
+export function renderProposalEntry(proposal: InteropProposal): string {
+	return stringifyYaml([proposal.entry]).trimEnd();
+}
+
+/**
+ * Facts come from the caller's report, standing decisions from disk. A caller
+ * holds one report across several calls, so its copy of a record is stale the
+ * moment an earlier call decided that record: taking the report's bookkeeping
+ * would erase the decision just written. Recording one accept and one decline
+ * in the same review lost the accept exactly this way.
+ */
+function withStoredDecision(stored: InteropAgentRecord | undefined, fresh: InteropAgentRecord): InteropAgentRecord {
+	if (stored === undefined) return fresh;
+	return {
+		...fresh,
+		...(stored.decision !== undefined ? { decision: stored.decision } : {}),
+		...(stored.decidedAt !== undefined ? { decidedAt: stored.decidedAt } : {}),
+		...(stored.decidedFingerprint !== undefined ? { decidedFingerprint: stored.decidedFingerprint } : {}),
+		...(stored.hintedFingerprint !== undefined ? { hintedFingerprint: stored.hintedFingerprint } : {}),
+	};
+}
+
+/**
+ * Merge the report with what is on disk and patch the named records. The lock
+ * covers the read as well as the write so a decision taken in one process is
+ * not overwritten by a detection snapshot from another.
+ */
+function updateRecords(
+	ids: ReadonlyArray<InteropAgentId>,
+	report: InteropReport,
+	patch: (record: InteropAgentRecord) => InteropAgentRecord,
+): InteropAgentId[] {
+	const wanted = new Set(ids);
+	const touched: InteropAgentId[] = [];
+	withStateFileLockSync(interopStatePath(), () => {
+		const stored = readInteropReport();
+		const storedByKind = new Map<InteropAgentId, InteropAgentRecord>(
+			(stored?.agents ?? []).map((record) => [record.kind, record]),
+		);
+		const byKind = new Map<InteropAgentId, InteropAgentRecord>(storedByKind);
+		for (const record of report.agents) {
+			byKind.set(record.kind, withStoredDecision(storedByKind.get(record.kind), record));
+		}
+		for (const id of wanted) {
+			const record = byKind.get(id);
+			if (record === undefined) continue;
+			byKind.set(id, patch(record));
+			touched.push(id);
+		}
+		writeInteropReport({ version: 1, detectedAt: report.detectedAt, agents: [...byKind.values()] });
+	});
+	return touched;
+}
+
+function recordDecisions(
+	ids: ReadonlyArray<InteropAgentId>,
+	report: InteropReport,
+	decision: InteropDecision,
+): InteropAgentId[] {
+	const decidedAt = new Date().toISOString();
+	return updateRecords(ids, report, (record) => ({
+		...record,
+		decision,
+		decidedAt,
+		decidedFingerprint: record.fingerprint,
+	}));
+}
+
+/**
+ * One line at boot for agents that are installed, unconfigured, and undecided,
+ * and only the first time each set of facts is seen. The caller decides where
+ * this belongs; it is never emitted headless or under ACP.
+ */
+export function interopBootHint(report: InteropReport, settings: ClioSettings): string | null {
+	const fresh = interopProposals(report, settings).filter(
+		(proposal) => report.agents.find((agent) => agent.kind === proposal.kind)?.hintedFingerprint !== proposal.fingerprint,
+	);
+	if (fresh.length === 0) return null;
+	updateRecords(
+		fresh.map((proposal) => proposal.kind),
+		report,
+		(record) => ({ ...record, hintedFingerprint: record.fingerprint }),
+	);
+	const names = fresh.map((proposal) => proposal.entry.id).join(", ");
+	return `clio: ${names} detected on PATH and not configured. Run /interop to review.`;
+}
+
+/**
+ * Wire the named agents as ACP delegation peers. The settings append runs
+ * inside the shared settings lock, which re-reads the file, so two processes
+ * accepting different agents at once cannot drop each other's entry.
+ */
+export function acceptInteropAgents(ids: ReadonlyArray<InteropAgentId>, report: InteropReport): InteropDecisionResult {
+	const proposals = interopProposals(report, readSettings()).filter((proposal) => ids.includes(proposal.kind));
+	const diagnostics: string[] = [];
+	for (const id of ids) {
+		if (!proposals.some((proposal) => proposal.kind === id)) diagnostics.push(`${id} is not a pending proposal`);
+	}
+	if (proposals.length === 0) return { decided: [], wired: [], diagnostics };
+	const wired: string[] = [];
+	updateSettings((settings) => {
+		for (const proposal of proposals) {
+			if (settings.delegation.agents.some((agent) => agent.id === proposal.entry.id)) continue;
+			settings.delegation.agents.push({ ...proposal.entry, args: [...proposal.entry.args] });
+			wired.push(proposal.entry.id);
+		}
+	});
+	const decided = recordDecisions(
+		proposals.map((proposal) => proposal.kind),
+		report,
+		"accepted",
+	);
+	return { decided, wired, diagnostics };
+}
+
+export function declineInteropAgents(ids: ReadonlyArray<InteropAgentId>, report: InteropReport): InteropDecisionResult {
+	return { decided: recordDecisions(ids, report, "declined"), wired: [], diagnostics: [] };
+}

package/src/domains/interop/contract.ts

@@ -0,0 +1,29 @@
+import type { DelegationAgentConfig } from "../../core/defaults.js";
+import type { DomainContract } from "../../core/domain-loader.js";
+import type {
+	InteropAgentId,
+	InteropAgentKind,
+	InteropDecisionResult,
+	InteropDetectInput,
+	InteropProposal,
+	InteropReport,
+} from "./types.js";
+
+export interface InteropContract extends DomainContract {
+	/** The static agent table. No I/O. */
+	kinds(): ReadonlyArray<InteropAgentKind>;
+	detect(input?: InteropDetectInput): Promise<InteropReport>;
+	/** The newest report this process produced, else the recorded one. Never probes. */
+	lastReport(): InteropReport | null;
+	proposals(report: InteropReport): ReadonlyArray<InteropProposal>;
+	/**
+	 * Peers already wired, read from the same settings a proposal is filtered
+	 * against. The two lists partition the same agents, so they cannot come from
+	 * different reads of the settings without an agent falling between them.
+	 */
+	configured(): ReadonlyArray<DelegationAgentConfig>;
+	accept(ids: ReadonlyArray<InteropAgentId>): InteropDecisionResult;
+	decline(ids: ReadonlyArray<InteropAgentId>): InteropDecisionResult;
+	/** One boot line for undecided agents whose facts have not been announced yet. */
+	bootHint(report: InteropReport): string | null;
+}

package/src/domains/interop/detect.ts

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+import { accessSync, constants, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { runCommandVector } from "../../core/safe-exec.js";
+import { INTEROP_AGENT_KINDS } from "./registry.js";
+import { readInteropReport } from "./state.js";
+import type {
+	InteropAgentFacts,
+	InteropAgentKind,
+	InteropAgentRecord,
+	InteropDetectInput,
+	InteropPresence,
+	InteropReport,
+} from "./types.js";
+
+const VERSION_PROBE_TIMEOUT_MS = 2000;
+const VERSION_PROBE_MAX_OUTPUT_BYTES = 4096;
+
+/** Resolve an executable on PATH without a shell. Never throws; unresolvable state reports "unknown". */
+export function resolveOnPath(binaryNames: ReadonlyArray<string>): { presence: InteropPresence; binary?: string } {
+	if (binaryNames.length === 0) return { presence: "absent" };
+	const rawPath = process.env.PATH;
+	if (rawPath === undefined || rawPath.length === 0) return { presence: "unknown" };
+	try {
+		for (const dir of rawPath.split(path.delimiter)) {
+			if (dir.length === 0) continue;
+			for (const name of binaryNames) {
+				const candidate = path.join(dir, name);
+				try {
+					accessSync(candidate, constants.X_OK);
+					return { presence: "present", binary: candidate };
+				} catch {
+					// Not this entry. A directory Clio cannot traverse is not evidence of absence,
+					// but it is also not evidence of presence, so the sweep simply continues.
+				}
+			}
+		}
+	} catch {
+		return { presence: "unknown" };
+	}
+	return { presence: "absent" };
+}
+
+/**
+ * Whether the ACP adapter can start without a network install. `npx` is never
+ * run: a package under a local node_modules or an adapter executable already on
+ * PATH answers the question, and anything else means npx would fetch it.
+ */
+function adapterPresence(kind: InteropAgentKind, cwd: string, binaryPresence: InteropPresence): InteropPresence {
+	const recipe = kind.acp;
+	if (recipe === undefined) return "absent";
+	if (recipe.npmPackage === undefined) return binaryPresence;
+	try {
+		if (existsSync(path.join(cwd, "node_modules", recipe.npmPackage))) return "present";
+	} catch {
+		return "unknown";
+	}
+	if (recipe.npmPackageBin === undefined) return "absent";
+	return resolveOnPath([recipe.npmPackageBin]).presence;
+}
+
+function installDirOf(kind: InteropAgentKind, home: string): string | undefined {
+	const dir = path.join(home, kind.userDir);
+	try {
+		return existsSync(dir) ? dir : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** First version-shaped token in the output of `<bin> --version`, or undefined. */
+function parseVersion(output: string): string | undefined {
+	return /\b\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?\b/.exec(output)?.[0];
+}
+
+async function probeVersion(binary: string, cwd: string): Promise<string | undefined> {
+	try {
+		const result = await runCommandVector(binary, ["--version"], {
+			cwd,
+			workspaceRoot: cwd,
+			timeoutMs: VERSION_PROBE_TIMEOUT_MS,
+			maxOutputBytes: VERSION_PROBE_MAX_OUTPUT_BYTES,
+		});
+		if (result.timedOut || result.exitCode !== 0) return undefined;
+		return parseVersion(`${result.stdout}\n${result.stderr}`);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Facts a proposal is keyed by. Skill and artifact counts are deliberately out:
+ * adding a skill to a foreign root must not re-propose an agent the operator
+ * already declined.
+ */
+function interopFingerprint(kind: InteropAgentKind, facts: InteropAgentFacts): string {
+	const recipe = kind.acp;
+	const parts = [
+		kind.id,
+		facts.binary ?? "",
+		facts.version ?? "",
+		recipe === undefined ? "" : `${recipe.command} ${recipe.args.join(" ")}`,
+	];
+	return `sha256:${createHash("sha256").update(parts.join("\0")).digest("hex")}`;
+}
+
+function countBy<T>(values: ReadonlyArray<T> | undefined, match: T | undefined): number {
+	if (values === undefined || match === undefined) return 0;
+	return values.filter((value) => value === match).length;
+}
+
+function detected(facts: InteropAgentFacts): boolean {
+	return (
+		facts.presence === "present" || facts.installDir !== undefined || facts.skillCount > 0 || facts.projectArtifacts > 0
+	);
+}
+
+/**
+ * Probe every registered agent. Detection resolves paths and, only when asked
+ * and only for a binary that already resolved, runs a bounded `--version`. It
+ * never starts a foreign agent's work command and never reads under a foreign
+ * session, history, cache, projects, or state directory.
+ */
+export async function detectInteropAgents(
+	input: InteropDetectInput = {},
+	previous?: ReadonlyArray<InteropAgentRecord>,
+): Promise<InteropReport> {
+	const cwd = path.resolve(input.cwd ?? process.cwd());
+	const home = input.home ?? homedir();
+	// Standing decisions live in the recorded report. A caller that already holds
+	// a fresher one passes it; everyone else must still see the decisions, or a
+	// declined agent is proposed again on the next run.
+	const priorByKind = new Map((previous ?? readInteropReport()?.agents ?? []).map((record) => [record.kind, record]));
+	const agents: InteropAgentRecord[] = [];
+
+	for (const kind of INTEROP_AGENT_KINDS) {
+		const resolved = resolveOnPath(kind.binaryNames);
+		const prior = priorByKind.get(kind.id);
+		const installDir = installDirOf(kind, home);
+		const facts: InteropAgentFacts = {
+			kind: kind.id,
+			presence: resolved.presence,
+			...(resolved.binary !== undefined ? { binary: resolved.binary } : {}),
+			...(installDir !== undefined ? { installDir } : {}),
+			...(kind.acp !== undefined ? { adapter: adapterPresence(kind, cwd, resolved.presence) } : {}),
+			skillCount: countBy(input.skillSources, kind.skillSource),
+			projectArtifacts: countBy(input.artifactProviders, kind.adoptionProvider),
+		};
+		if (resolved.binary !== undefined) {
+			const version =
+				input.probeVersion === true
+					? await probeVersion(resolved.binary, cwd)
+					: // A run that did not probe keeps the last version seen for the same
+						// binary, so the fingerprint does not flip between probing callers.
+						prior?.binary === resolved.binary
+						? prior.version
+						: undefined;
+			if (version !== undefined) facts.version = version;
+		}
+		if (!detected(facts)) continue;
+		agents.push({
+			...facts,
+			fingerprint: interopFingerprint(kind, facts),
+			...(prior?.decision !== undefined ? { decision: prior.decision } : {}),
+			...(prior?.decidedAt !== undefined ? { decidedAt: prior.decidedAt } : {}),
+			...(prior?.decidedFingerprint !== undefined ? { decidedFingerprint: prior.decidedFingerprint } : {}),
+			...(prior?.hintedFingerprint !== undefined ? { hintedFingerprint: prior.hintedFingerprint } : {}),
+		});
+	}
+
+	return { version: 1, detectedAt: new Date().toISOString(), agents };
+}