@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/setup/paseo/setup-deps.ts

@@ -0,0 +1,175 @@
+/**
+ * Injectable dependency surface for `gjc setup paseo`.
+ *
+ * Every module in this directory takes `PaseoSetupDependencies` explicitly so
+ * tests can substitute paths, the Paseo CLI probe, and the clock without
+ * `mock.module()`. Production wiring calls `createDefaultPaseoSetupDependencies()`.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+
+/** The five Paseo skills this setup links. `context-search` is deliberately excluded. */
+export const INSTALL_SKILL_NAMES = [
+	"paseo",
+	"paseo-advisor",
+	"paseo-committee",
+	"paseo-handoff",
+	"paseo-loop",
+] as const;
+
+export type InstallSkillName = (typeof INSTALL_SKILL_NAMES)[number];
+
+/** Prefix used to enumerate Paseo-owned skills when scanning for drift. */
+export const PASEO_SKILL_PREFIX = "paseo";
+
+/** Base provider key written into `agents.providers`. */
+export const PROVIDER_KEY = "gjc";
+
+/** Paseo's undocumented provider inheritance contract, reverse-engineered from a hand-written config. */
+export const PROVIDER_EXTENDS = "acp";
+
+/**
+ * Role keys Paseo stores under `providers` in `orchestration-preferences.json`.
+ *
+ * Verified against a live file: the roles are nested, not top-level, and the
+ * sibling `preferences` array belongs to the user.
+ */
+export const ORCHESTRATION_ROLE_KEYS = ["impl", "ui", "research", "planning", "audit"] as const;
+
+export interface PaseoPaths {
+	/** `~/.paseo/config.json` */
+	readonly configJson: string;
+	/** `~/.paseo/orchestration-preferences.json` */
+	readonly orchestrationPreferences: string;
+	/** `~/.agents/skills` -- READ-ONLY, never written by this setup. */
+	readonly agentsSkillsDir: string;
+	/** `<agentDir>/paseo-skills` -- the bridge directory this setup owns. */
+	readonly bridgeDir: string;
+	/** `<agentDir>/paseo/provenance.json` -- GJC-side ownership ledger. */
+	readonly provenanceLedger: string;
+	/** `<agentDir>/paseo/intent.json` -- durable crash-recovery intent record. */
+	readonly intentRecord: string;
+	/** `<agentDir>/skills` -- second protected tree, never written by this setup. */
+	readonly gjcSkillsDir: string;
+}
+
+/** A provider row as `paseo provider ls --json` reports it. */
+export interface PaseoProviderRow {
+	readonly id: string;
+	/** Paseo reports `"available"` for a provider it can actually reach. */
+	readonly status?: string;
+}
+
+/** Distinct outcomes of probing `paseo provider ls --json`. Never collapsed into a boolean. */
+export type PaseoLsOutcome =
+	| { readonly kind: "ok"; readonly providerIds: readonly string[]; readonly rows: readonly PaseoProviderRow[] }
+	| { readonly kind: "unavailable"; readonly detail: string }
+	| { readonly kind: "timeout"; readonly timeoutMs: number }
+	| { readonly kind: "malformed"; readonly detail: string }
+	| { readonly kind: "nonzero-exit"; readonly exitCode: number; readonly detail: string };
+
+export interface PaseoSetupDependencies {
+	readonly paths: PaseoPaths;
+	/** Bounded probe of the Paseo daemon. MUST enforce `timeoutMs` and kill the child on expiry. */
+	runProviderLs(timeoutMs: number): Promise<PaseoLsOutcome>;
+	now(): Date;
+}
+
+export function createDefaultPaseoPaths(agentDir: string = getAgentDir(), home: string = os.homedir()): PaseoPaths {
+	const paseoHome = path.join(home, ".paseo");
+	return {
+		configJson: path.join(paseoHome, "config.json"),
+		orchestrationPreferences: path.join(paseoHome, "orchestration-preferences.json"),
+		agentsSkillsDir: path.join(home, ".agents", "skills"),
+		bridgeDir: path.join(agentDir, "paseo-skills"),
+		provenanceLedger: path.join(agentDir, "paseo", "provenance.json"),
+		intentRecord: path.join(agentDir, "paseo", "intent.json"),
+		gjcSkillsDir: path.join(agentDir, "skills"),
+	};
+}
+
+/**
+ * Probe the Paseo daemon for its registered providers.
+ *
+ * The daemon may be down, wedged, or a different version, so every failure mode
+ * is classified rather than collapsed: `--check` maps `unavailable`/`timeout` to
+ * `skipped` and must never report `drift` because the daemon did not answer.
+ */
+async function runProviderLs(timeoutMs: number): Promise<PaseoLsOutcome> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const child = Bun.spawn(["paseo", "provider", "ls", "--json"], {
+			stdout: "pipe",
+			stderr: "pipe",
+			signal: controller.signal,
+		});
+		const [exitCode, stdout, stderr] = await Promise.all([
+			child.exited,
+			new Response(child.stdout).text(),
+			new Response(child.stderr).text(),
+		]);
+		if (controller.signal.aborted) return { kind: "timeout", timeoutMs };
+		if (exitCode !== 0) return { kind: "nonzero-exit", exitCode, detail: stderr.trim().slice(0, 500) };
+		return parseProviderLs(stdout);
+	} catch (error) {
+		if (controller.signal.aborted) return { kind: "timeout", timeoutMs };
+		return { kind: "unavailable", detail: error instanceof Error ? error.message : String(error) };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Parse `paseo provider ls --json`.
+ *
+ * The measured shape is an array of `{ provider, label, status, ... }` rows.
+ * `id` and `name` are also accepted because the key is undocumented and has no
+ * stability guarantee, and a bare string array is accepted for the same reason.
+ */
+export function parseProviderLs(stdout: string): PaseoLsOutcome {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch (error) {
+		return { kind: "malformed", detail: error instanceof Error ? error.message : String(error) };
+	}
+	const raw = Array.isArray(parsed)
+		? parsed
+		: parsed && typeof parsed === "object" && Array.isArray((parsed as { providers?: unknown }).providers)
+			? ((parsed as { providers: unknown[] }).providers as unknown[])
+			: undefined;
+	if (!raw) return { kind: "malformed", detail: "expected an array or an object carrying a providers array" };
+
+	const rows: PaseoProviderRow[] = [];
+	for (const row of raw) {
+		if (typeof row === "string") {
+			rows.push({ id: row });
+			continue;
+		}
+		if (!row || typeof row !== "object") {
+			return { kind: "malformed", detail: "provider entry was not an object" };
+		}
+		const candidate = row as { provider?: unknown; id?: unknown; name?: unknown; status?: unknown };
+		const id =
+			typeof candidate.provider === "string"
+				? candidate.provider
+				: typeof candidate.id === "string"
+					? candidate.id
+					: typeof candidate.name === "string"
+						? candidate.name
+						: undefined;
+		if (id === undefined) return { kind: "malformed", detail: "provider entry carried no string id" };
+		rows.push(typeof candidate.status === "string" ? { id, status: candidate.status } : { id });
+	}
+	return { kind: "ok", providerIds: rows.map(row => row.id), rows };
+}
+
+export function createDefaultPaseoSetupDependencies(): PaseoSetupDependencies {
+	return {
+		paths: createDefaultPaseoPaths(),
+		runProviderLs,
+		now: () => new Date(),
+	};
+}

package/src/setup/paseo/skills-bridge.ts

@@ -0,0 +1,260 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { CasReceipt } from "../../config/atomic-yaml-patch";
+import type { RawSettings, Settings } from "../../config/settings";
+import type { SettingPath } from "../../config/settings-schema";
+import type { DriftReason } from "./result-types";
+import {
+	INSTALL_SKILL_NAMES,
+	type InstallSkillName,
+	PASEO_SKILL_PREFIX,
+	type PaseoSetupDependencies,
+} from "./setup-deps";
+
+type BridgeEntryAction = "create" | "noop" | "prune-and-recreate";
+
+type BridgeEntryPlan = {
+	readonly name: InstallSkillName;
+	readonly action: BridgeEntryAction;
+	readonly linkPath: string;
+	readonly targetPath: string;
+	/** The dangling link text captured during preflight, used as an unlink guard. */
+	readonly danglingTarget?: string;
+};
+
+/** Immutable preflight evidence consumed by the install saga and its inverse. */
+export interface SkillsBridgePreflight {
+	readonly bridgeDir: string;
+	readonly bridgeDirCreated: boolean;
+	readonly entries: Readonly<Record<InstallSkillName, BridgeEntryPlan>>;
+}
+
+/** What the forward operation actually created, rather than what preflight intended to create. */
+export interface SkillsBridgeInstallResult {
+	readonly createdEntries: readonly InstallSkillName[];
+	readonly bridgeDirCreated: boolean;
+}
+
+export class SkillsBridgeError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SkillsBridgeError";
+	}
+}
+
+function expectedTarget(deps: PaseoSetupDependencies, name: InstallSkillName): string {
+	return path.resolve(deps.paths.agentsSkillsDir, name);
+}
+
+function linkPath(deps: PaseoSetupDependencies, name: InstallSkillName): string {
+	return path.join(deps.paths.bridgeDir, name);
+}
+
+function resolvedLinkTarget(link: string, destination: string): string {
+	return path.resolve(path.dirname(destination), link);
+}
+
+async function entryState(
+	destination: string,
+	expected: string,
+): Promise<
+	| { readonly kind: "absent" }
+	| { readonly kind: "expected"; readonly link: string }
+	| { readonly kind: "dangling"; readonly link: string }
+	| { readonly kind: "conflict" }
+> {
+	try {
+		const stat = await fs.lstat(destination);
+		if (!stat.isSymbolicLink()) return { kind: "conflict" };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+		throw error;
+	}
+	const link = await fs.readlink(destination);
+	if (resolvedLinkTarget(link, destination) !== expected) return { kind: "conflict" };
+	try {
+		await fs.stat(destination);
+		return { kind: "expected", link };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "dangling", link };
+		throw error;
+	}
+}
+
+async function bridgeDirectoryState(bridgeDir: string): Promise<"absent" | "directory" | "conflict"> {
+	try {
+		const stat = await fs.lstat(bridgeDir);
+		return stat.isDirectory() ? "directory" : "conflict";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+		throw error;
+	}
+}
+
+/**
+ * Classify every allowlisted bridge entry without mutating either skill tree.
+ * All conflicts are accumulated so the caller can report them together.
+ */
+export async function preflightSkillsBridge(deps: PaseoSetupDependencies): Promise<SkillsBridgePreflight> {
+	const directory = await bridgeDirectoryState(deps.paths.bridgeDir);
+	const conflicts: string[] = directory === "conflict" ? [deps.paths.bridgeDir] : [];
+	const entries = {} as Record<InstallSkillName, BridgeEntryPlan>;
+
+	for (const name of INSTALL_SKILL_NAMES) {
+		const destination = linkPath(deps, name);
+		const target = expectedTarget(deps, name);
+		const state = directory === "absent" ? { kind: "absent" as const } : await entryState(destination, target);
+		if (state.kind === "conflict") {
+			conflicts.push(destination);
+			continue;
+		}
+		entries[name] = {
+			name,
+			action: state.kind === "expected" ? "noop" : state.kind === "dangling" ? "prune-and-recreate" : "create",
+			linkPath: destination,
+			targetPath: target,
+			...(state.kind === "dangling" ? { danglingTarget: state.link } : {}),
+		};
+	}
+	if (conflicts.length > 0) {
+		throw new SkillsBridgeError(
+			`Refusing to modify Paseo skills bridge; conflicting entries: ${conflicts.join(", ")}`,
+		);
+	}
+	return { bridgeDir: deps.paths.bridgeDir, bridgeDirCreated: directory === "absent", entries };
+}
+
+async function createBridgeDirectory(preflight: SkillsBridgePreflight): Promise<void> {
+	try {
+		await fs.mkdir(preflight.bridgeDir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		throw new SkillsBridgeError(`Paseo skills bridge appeared during creation: ${preflight.bridgeDir}`);
+	}
+}
+
+async function pruneRecordedDangling(entry: BridgeEntryPlan): Promise<void> {
+	if (entry.danglingTarget === undefined)
+		throw new SkillsBridgeError(`Missing dangling-link evidence for ${entry.linkPath}`);
+	const state = await entryState(entry.linkPath, entry.targetPath);
+	if (state.kind !== "dangling" || state.link !== entry.danglingTarget) {
+		throw new SkillsBridgeError(`Paseo skill bridge entry diverged before pruning: ${entry.linkPath}`);
+	}
+	await fs.unlink(entry.linkPath);
+}
+
+async function createNoReplace(entry: BridgeEntryPlan): Promise<void> {
+	try {
+		await fs.symlink(entry.targetPath, entry.linkPath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		const observed = await entryState(entry.linkPath, entry.targetPath);
+		throw new SkillsBridgeError(
+			`Paseo skill bridge entry appeared during creation (${observed.kind}): ${entry.linkPath}`,
+		);
+	}
+}
+
+/** Create only preflight-approved bridge links; symlink publication never replaces an existing entry. */
+export async function installSkillsBridge(preflight: SkillsBridgePreflight): Promise<SkillsBridgeInstallResult> {
+	let bridgeDirCreated = false;
+	if (preflight.bridgeDirCreated) {
+		await createBridgeDirectory(preflight);
+		bridgeDirCreated = true;
+	}
+	const createdEntries: InstallSkillName[] = [];
+	for (const name of INSTALL_SKILL_NAMES) {
+		const entry = preflight.entries[name];
+		if (entry.action === "noop") continue;
+		if (entry.action === "prune-and-recreate") await pruneRecordedDangling(entry);
+		await createNoReplace(entry);
+		createdEntries.push(name);
+	}
+	return { createdEntries, bridgeDirCreated };
+}
+
+/**
+ * Undo exactly the links this run created. A changed link is reported as a
+ * conflict rather than being deleted; this makes compensation safe after edits.
+ */
+export async function inverseSkillsBridge(
+	deps: PaseoSetupDependencies,
+	result: SkillsBridgeInstallResult,
+): Promise<void> {
+	const diverged: string[] = [];
+	for (const name of result.createdEntries) {
+		const destination = linkPath(deps, name);
+		const state = await entryState(destination, expectedTarget(deps, name));
+		if (state.kind !== "expected" || state.link !== expectedTarget(deps, name)) diverged.push(destination);
+	}
+	if (diverged.length > 0) {
+		throw new SkillsBridgeError(`Refusing to remove diverged Paseo skill bridge entries: ${diverged.join(", ")}`);
+	}
+	for (const name of result.createdEntries) await fs.unlink(linkPath(deps, name));
+	if (!result.bridgeDirCreated) return;
+	try {
+		await fs.rmdir(deps.paths.bridgeDir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOTEMPTY") return;
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+}
+
+/** Find Paseo-prefixed bridge or source entries that the locked install allowlist does not repair. */
+export async function scanSkillsBridgeDrift(deps: PaseoSetupDependencies): Promise<readonly DriftReason[]> {
+	const reasons: DriftReason[] = [];
+	const bridgeEntries = await fs.readdir(deps.paths.bridgeDir, { withFileTypes: true }).catch(error => {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	});
+	for (const entry of bridgeEntries) {
+		if (!entry.name.startsWith(PASEO_SKILL_PREFIX) || !entry.isSymbolicLink()) continue;
+		const destination = path.join(deps.paths.bridgeDir, entry.name);
+		try {
+			await fs.stat(destination);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			reasons.push({ code: "orphan-skill", subject: destination, detail: "bridge symlink target no longer exists" });
+		}
+	}
+	const sourceEntries = await fs.readdir(deps.paths.agentsSkillsDir, { withFileTypes: true }).catch(error => {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	});
+	for (const entry of sourceEntries) {
+		if (!entry.name.startsWith(PASEO_SKILL_PREFIX) || (INSTALL_SKILL_NAMES as readonly string[]).includes(entry.name))
+			continue;
+		reasons.push({
+			code: "unlinked-skill",
+			subject: path.join(deps.paths.agentsSkillsDir, entry.name),
+			detail: "Paseo skill is outside GJC's locked bridge allowlist",
+		});
+	}
+	return reasons;
+}
+
+function existingCustomDirectories(current: Readonly<RawSettings>): string[] {
+	const skills = current.skills;
+	if (skills === undefined) return [];
+	if (typeof skills !== "object" || skills === null || Array.isArray(skills)) {
+		throw new SkillsBridgeError("Cannot register Paseo skills bridge: skills config is not an object.");
+	}
+	const directories = (skills as Record<string, unknown>).customDirectories;
+	if (directories === undefined) return [];
+	if (!Array.isArray(directories) || directories.some(directory => typeof directory !== "string")) {
+		throw new SkillsBridgeError(
+			"Cannot register Paseo skills bridge: skills.customDirectories is not a string array.",
+		);
+	}
+	return [...directories];
+}
+
+/** Append the bridge directory without discarding concurrent user config changes. */
+export async function registerSkillsBridgeDirectory(settings: Settings, bridgeDir: string): Promise<CasReceipt> {
+	return settings.commitAtomicBatchWithCurrent(current => {
+		const directories = existingCustomDirectories(current);
+		const next = directories.includes(bridgeDir) ? directories : [...directories, bridgeDir];
+		return [{ path: "skills.customDirectories" as SettingPath, op: "set", value: next }];
+	});
+}

package/src/skill-state/active-state.ts

@@ -10,6 +10,7 @@ import {
 import { resolveGjcSessionForRead, SessionResolutionError } from "../gjc-runtime/session-resolution";
 import {
 	type ActiveSessionScope,
+	type GuardedWriteResult,
 	readActiveEntries,
 	rebuildActiveSnapshot,
 	removeActiveEntry,
@@ -125,6 +126,8 @@ export interface SyncSkillActiveStateOptions {
 	handoff_at?: string;
 	active_subskills?: ActiveSubskillEntry[];
 	sourceRevision?: number;
+	/** Internal seed path: retain the authoritative entry receipt if snapshot rebuilding fails. */
+	bestEffortSnapshot?: boolean;
 }
 
 const HUD_TEXT_LIMIT = 80;
@@ -645,7 +648,7 @@ function comparePipelineEntry(a: SkillActiveEntry, b: SkillActiveEntry): number
 	return 0;
 }
 
-function upstreamPlanningPipelineSkills(skill: string): string[] {
+export function upstreamPlanningPipelineSkills(skill: string): string[] {
 	const rank = planningPipelineRank(skill);
 	if (rank === undefined) return [];
 	return [...PLANNING_PIPELINE_RANK.entries()]
@@ -847,19 +850,19 @@ async function persistActiveEntry(
 	cwd: string,
 	sessionScope: ActiveSessionScope | undefined,
 	entry: SkillActiveEntry,
-): Promise<void> {
+): Promise<GuardedWriteResult | undefined> {
 	if (entry.active === false) {
 		await removeActiveEntry(cwd, sessionScope, entry.skill, {
 			cwd,
 			audit: activeStateWriterAudit("remove-active-entry", sessionScope),
 			sourceRevision: entry.source_state_revision,
 		});
-	} else {
-		await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
-			cwd,
-			audit: activeStateWriterAudit("write-active-entry", sessionScope),
-		});
+		return undefined;
 	}
+	return await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
+		cwd,
+		audit: activeStateWriterAudit("write-active-entry", sessionScope),
+	});
 }
 
 async function writeHandoffEntry(
@@ -908,8 +911,10 @@ async function activeSubskillsForExistingEntry(
 	return existing?.active_subskills;
 }
 
-export async function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void> {
-	if (!options.sessionId) return;
+export async function syncSkillActiveState(
+	options: SyncSkillActiveStateOptions,
+): Promise<GuardedWriteResult | undefined> {
+	if (!options.sessionId) return undefined;
 	const preservedActiveSubskills =
 		options.active_subskills === undefined
 			? await activeSubskillsForExistingEntry(options.cwd, options.sessionId, options.skill)
@@ -939,8 +944,13 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 	};
 	const sessionScope = { sessionId: options.sessionId };
 	await removeSupersededPlanningPipelineEntries(options.cwd, sessionScope, entry);
-	await persistActiveEntry(options.cwd, sessionScope, entry);
-	await rebuildActiveState(options.cwd, sessionScope);
+	const entryWrite = await persistActiveEntry(options.cwd, sessionScope, entry);
+	try {
+		await rebuildActiveState(options.cwd, sessionScope);
+	} catch (error) {
+		if (!options.bestEffortSnapshot) throw error;
+	}
+	return entryWrite;
 }
 
 export interface ApplyHandoffOptions {

package/src/slash-commands/acp-builtins.ts

@@ -15,7 +15,7 @@ export type { AcpBuiltinCommandRuntime, AcpBuiltinSlashCommandResult } from "./t
  * see commands it cannot drive.
  */
 export const ACP_BUILTIN_SLASH_COMMANDS: AvailableCommand[] = BUILTIN_SLASH_COMMANDS_INTERNAL.filter(
-	command => command.handle !== undefined,
+	command => command.handle !== undefined && command.acp !== false,
 ).map(command => {
 	// Honor mode-specific copy: ACP clients receive concise text-mode
 	// descriptions/hints when the spec sets `acpDescription` / `acpInputHint`,
@@ -35,14 +35,22 @@ export const ACP_BUILTIN_SLASH_COMMANDS: AvailableCommand[] = BUILTIN_SLASH_COMM
  * - `{ consumed: true }` when the command handled the input entirely.
  * - `{ prompt }` when the command was handled but a residual prompt should be
  *   sent to the model.
+ * When `disabledOnly` is set, ACP-enabled builtins also return `false` so a
+ * transport can apply only the unavailable-over-ACP policy before forwarding.
  */
 export async function executeAcpBuiltinSlashCommand(
 	text: string,
 	runtime: AcpBuiltinCommandRuntime,
+	options?: { disabledOnly?: boolean },
 ): Promise<AcpBuiltinSlashCommandResult> {
 	const parsed = parseSlashCommand(text);
 	if (!parsed) return false;
 	const command = lookupBuiltinSlashCommand(parsed.name);
+	if (command?.acp === false) {
+		await runtime.output(`Slash command /${parsed.name} is unavailable over ACP.`);
+		return { consumed: true };
+	}
+	if (options?.disabledOnly) return false;
 	if (!command?.handle) {
 		const diagnostic = formatUnknownBuiltinSlashCommandDiagnostic(parsed.name);
 		if (!diagnostic) return false;