@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/mux/detect.ts

@@ -0,0 +1,158 @@
+/**
+ * The capability ladder from spec 4.2.
+ *
+ * Guest mode requires all of: `HERDR_ENV=1`, a connectable socket, and a `ping`
+ * answered inside one second. The three conditions are checked in that order
+ * and the first one that fails ends detection, which is what makes the `none`
+ * path free: with `HERDR_ENV` unset nothing here opens a file descriptor, and a
+ * contract test pins that by making `net.connect` throw for the duration of the
+ * call.
+ *
+ * Embedded mode resolves to `none` until Phase 5 lands the session bootstrap.
+ * Asking for it is not an error; it degrades with a reason the doctor surface
+ * can print.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createMuxClient, type MuxClient } from "./socket-client.js";
+import type { MuxLog, MuxMode, MuxSelfLocation, MuxServerInfo } from "./types.js";
+
+/** Spec 4.2 gives the ping one second to answer before the rung is refused. */
+const PING_TIMEOUT_MS = 1_000;
+
+export type MuxEnablement = "auto" | "embedded" | "off";
+
+export interface MuxDetection {
+	mode: MuxMode;
+	socketPath: string | null;
+	server: MuxServerInfo | null;
+	self: MuxSelfLocation;
+	/** Socket paths considered, in resolution order, for doctor output. */
+	candidates: ReadonlyArray<string>;
+	/** Human-readable reason, always set; for `guest` it names the socket that answered. */
+	reason: string;
+}
+
+export interface DetectMuxOptions {
+	env?: NodeJS.ProcessEnv;
+	enabled?: MuxEnablement;
+	pingTimeoutMs?: number;
+	log?: MuxLog;
+	/** Injection seam for tests; production opens a real client. */
+	openClient?: (socketPath: string) => MuxClient;
+}
+
+/**
+ * herdr resolves its config dir through `XDG_CONFIG_HOME` first and falls back
+ * to the platform default, which on Linux is `~/.config/herdr`. Mirroring that
+ * matters: a user with `XDG_CONFIG_HOME` set has no `~/.config/herdr` at all,
+ * and the spec's literal `~/.config/herdr` would miss every one of their
+ * sockets.
+ */
+function herdrConfigDir(env: NodeJS.ProcessEnv): string {
+	const xdg = env.XDG_CONFIG_HOME;
+	if (typeof xdg === "string" && xdg.length > 0) return join(xdg, "herdr");
+	const home = typeof env.HOME === "string" && env.HOME.length > 0 ? env.HOME : homedir();
+	return join(home, ".config", "herdr");
+}
+
+/** Socket paths to try, in the order spec 4.2 fixes. */
+export function resolveSocketCandidates(env: NodeJS.ProcessEnv): ReadonlyArray<string> {
+	const candidates: string[] = [];
+	const explicit = env.HERDR_SOCKET_PATH;
+	if (typeof explicit === "string" && explicit.length > 0) candidates.push(explicit);
+	const configDir = herdrConfigDir(env);
+	const session = env.HERDR_SESSION;
+	if (typeof session === "string" && session.length > 0) {
+		candidates.push(join(configDir, "sessions", session, "herdr.sock"));
+	}
+	candidates.push(join(configDir, "herdr.sock"));
+	return [...new Set(candidates)];
+}
+
+function readSelfLocation(env: NodeJS.ProcessEnv): MuxSelfLocation {
+	const read = (key: string): string | null => {
+		const value = env[key];
+		return typeof value === "string" && value.length > 0 ? value : null;
+	};
+	return {
+		workspaceId: read("HERDR_WORKSPACE_ID"),
+		tabId: read("HERDR_TAB_ID"),
+		paneId: read("HERDR_PANE_ID"),
+	};
+}
+
+function none(reason: string, candidates: ReadonlyArray<string> = []): MuxDetection {
+	return {
+		mode: "none",
+		socketPath: null,
+		server: null,
+		self: { workspaceId: null, tabId: null, paneId: null },
+		candidates,
+		reason,
+	};
+}
+
+/**
+ * The detected rung plus the live client when one was reached. The client is
+ * the same connection the ping went over, so the caller inherits a warm socket
+ * rather than reconnecting.
+ */
+export interface MuxDetectionResult {
+	detection: MuxDetection;
+	client: MuxClient | null;
+}
+
+export async function detectMux(options: DetectMuxOptions = {}): Promise<MuxDetectionResult> {
+	const env = options.env ?? process.env;
+	const enabled = options.enabled ?? "auto";
+	const log = options.log ?? ((): void => undefined);
+
+	if (enabled === "off") {
+		return { detection: none("panes are turned off"), client: null };
+	}
+	if (enabled === "embedded") {
+		// Phase 5 owns the session bootstrap. Until then the honest answer is that
+		// Clio cannot provide panes, not that it failed to find them.
+		return { detection: none("embedded mode is not implemented yet; it ships in phase 5"), client: null };
+	}
+	if (env.HERDR_ENV !== "1") {
+		return { detection: none("HERDR_ENV is not 1, so Clio is not running inside a pane host"), client: null };
+	}
+
+	const candidates = resolveSocketCandidates(env);
+	const openClient = options.openClient ?? ((socketPath: string) => createMuxClient({ socketPath, log }));
+	const pingTimeoutMs = options.pingTimeoutMs ?? PING_TIMEOUT_MS;
+
+	for (const socketPath of candidates) {
+		const client = openClient(socketPath);
+		try {
+			const server = await client.ping({ timeoutMs: pingTimeoutMs });
+			return {
+				detection: {
+					mode: "guest",
+					socketPath,
+					server,
+					self: readSelfLocation(env),
+					candidates,
+					reason: `guest mode on ${socketPath} (herdr ${server.version}, protocol ${server.protocol})`,
+				},
+				client,
+			};
+		} catch (error) {
+			log("debug", `mux ping ${socketPath} failed: ${error instanceof Error ? error.message : String(error)}`);
+			await client.close().catch(() => undefined);
+		}
+	}
+
+	return {
+		detection: none(
+			candidates.length > 0
+				? `no herdr socket answered a ping: tried ${candidates.join(", ")}`
+				: "no herdr socket candidates resolved",
+			candidates,
+		),
+		client: null,
+	};
+}

package/src/domains/mux/extension.ts

@@ -0,0 +1,47 @@
+/**
+ * Domain wiring for the pane layer.
+ *
+ * `createExtension` runs the detection ladder once at boot. This module only
+ * loads on a `--with-panes` boot (src/entry/with-panes.ts), so a plain session
+ * never reaches this code at all; within an active session, detection failures
+ * are never fatal, and a wedged herdr server delays boot by at most the
+ * one-second ping budget per socket candidate.
+ */
+
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { createMuxRuntime, type MuxContract } from "./contract.js";
+import { detectMux, type MuxEnablement } from "./detect.js";
+import type { MuxLog } from "./types.js";
+
+export interface MuxDomainOptions {
+	/** `off` skips detection entirely; `embedded` degrades to `none` until phase 5. */
+	enabled?: MuxEnablement;
+	env?: NodeJS.ProcessEnv;
+	log?: MuxLog;
+}
+
+export async function createMuxBundle(
+	_context: DomainContext,
+	options: MuxDomainOptions = {},
+): Promise<DomainBundle<MuxContract>> {
+	const log = options.log ?? ((): void => undefined);
+	const { detection, client } = await detectMux({
+		...(options.enabled ? { enabled: options.enabled } : {}),
+		...(options.env ? { env: options.env } : {}),
+		log,
+	});
+	log(detection.mode === "none" ? "debug" : "info", `mux mode ${detection.mode}: ${detection.reason}`);
+
+	const runtime = createMuxRuntime({ detection, client, log });
+
+	const extension: DomainExtension = {
+		async start(): Promise<void> {
+			await runtime.start();
+		},
+		async stop(): Promise<void> {
+			await runtime.stop();
+		},
+	};
+
+	return { extension, contract: runtime.contract };
+}

package/src/domains/mux/index.ts

@@ -0,0 +1,96 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import type { MuxContract } from "./contract.js";
+import { createMuxBundle, type MuxDomainOptions } from "./extension.js";
+import { MuxManifest } from "./manifest.js";
+
+/** Zero-configuration module: guest when detected, `none` otherwise. */
+export const MuxDomainModule: DomainModule<MuxContract> = {
+	manifest: MuxManifest,
+	createExtension: (context) => createMuxBundle(context),
+};
+
+/** Parameterized module for callers that gate panes off or on explicitly. */
+export function createMuxDomainModule(options: MuxDomainOptions): DomainModule<MuxContract> {
+	return {
+		manifest: MuxManifest,
+		createExtension: (context) => createMuxBundle(context, options),
+	};
+}
+
+export type {
+	MuxContract,
+	MuxNotifyRequest,
+	MuxOpenUtilityPaneRequest,
+	MuxRuntime,
+	MuxRuntimeOptions,
+} from "./contract.js";
+export { createMuxRuntime } from "./contract.js";
+export { detectMux, type MuxDetection, type MuxEnablement, resolveSocketCandidates } from "./detect.js";
+export type { MuxDomainOptions } from "./extension.js";
+export { MuxManifest } from "./manifest.js";
+export { createPaneRegistry, type MuxPaneRegistry, paneRecord } from "./pane-registry.js";
+export { MUX_METHOD_MIN_PROTOCOL, type MuxGatedMethod, muxSupportsMethod } from "./protocol.js";
+export { createMuxClient, type MuxClient, type MuxClientOptions, type MuxSubscription } from "./socket-client.js";
+export {
+	type MuxAgentState,
+	MuxError,
+	type MuxErrorKind,
+	type MuxEvent,
+	type MuxEventKind,
+	type MuxLog,
+	type MuxMode,
+	type MuxNotificationSound,
+	type MuxPanePurpose,
+	type MuxPaneRecord,
+	type MuxPaneRef,
+	type MuxReportableAgentState,
+	MuxRequestTimeout,
+	type MuxSelfLocation,
+	type MuxSelfReport,
+	type MuxServerInfo,
+	type MuxSnapshot,
+	type MuxTab,
+	muxErrorKind,
+} from "./types.js";
+export { clioCliEntryPath, type ViewerCommandOptions, watchViewerCommand } from "./viewer-command.js";
+export {
+	createYaziEventStream,
+	parseYaziEventLine,
+	YAZI_STREAM_MAX_BYTES,
+	YAZI_STREAM_POLL_MS,
+	type YaziCdEvent,
+	type YaziEvent,
+	type YaziEventStream,
+	type YaziEventStreamOptions,
+	type YaziEventStreamStats,
+	type YaziEventStreamStopReason,
+	type YaziPickEvent,
+} from "./yazi/event-stream.js";
+export {
+	describeYaziProfile,
+	ensureYaziProfile,
+	hashYaziAssetTree,
+	inspectCurrentYaziProfile,
+	inspectYaziProfile,
+	renderYaziKeymap,
+	resetYaziProfile,
+	userYaziConfigDir,
+	type YaziProfile,
+	type YaziProfileInspection,
+	type YaziProfileOptions,
+	type YaziProfileStamp,
+	type YaziProfileState,
+	yaziProfileDir,
+} from "./yazi/profile.js";
+export {
+	createYaziSession,
+	type YaziChooserResult,
+	type YaziProfileMode,
+	type YaziResolvedBinaries,
+	type YaziSession,
+	type YaziSessionMode,
+	type YaziSessionOpenResult,
+	type YaziSessionOptions,
+	type YaziSessionSnapshot,
+} from "./yazi/session.js";
+export { renderYaziTheme } from "./yazi/theme.js";

package/src/domains/mux/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const MuxManifest: DomainManifest = {
+	name: "mux",
+	dependsOn: [],
+};

package/src/domains/mux/operations.ts

@@ -0,0 +1,164 @@
+/**
+ * The operator- and model-facing pane vocabulary: presets, results, and the
+ * one operations interface both `/panes` and the `panes` tool drive.
+ *
+ * It is a leaf with no imports, and it lives in the domain rather than beside
+ * either caller because both callers are forbidden from reaching the other's
+ * tree. `src/interactive/slash-commands.ts` is a CLI seam whose value closure
+ * must stay off the render graph, and `src/tools/**` may not import
+ * `src/interactive/**` at all (boundaries rule4). A shared leaf here is the
+ * only place both can name the same preset ids and the same result shapes.
+ *
+ * Presets are the only utility panes the model may open. Arbitrary argv stays
+ * operator-only through the slash command, which is what keeps the tool out of
+ * shell-escape territory (spec 4.8, and the risk register's "tool misuse" row).
+ */
+
+/** Utility pane presets, in the order `/panes open` lists them. */
+export const PANES_PRESETS = [
+	{
+		id: "yazi",
+		/** Probed through the toolchain resolution ladder before the pane is split. */
+		binary: "yazi",
+		summary: "file manager rooted at the workspace",
+		/** Printed verbatim when the probe finds nothing. */
+		installHint: "clio-coder tools install yazi",
+	},
+	{
+		id: "logs",
+		binary: "tail",
+		summary: "follow the newest dispatched run's event journal",
+		installHint: "install coreutils so `tail` is on PATH",
+	},
+	{
+		id: "shell",
+		binary: "bash",
+		summary: "a plain shell in the workspace",
+		installHint: "install bash, or open a shell with `/panes open <argv>`",
+	},
+] as const;
+
+export type PanesPresetId = (typeof PANES_PRESETS)[number]["id"];
+
+export const PANES_PRESET_IDS: ReadonlyArray<PanesPresetId> = PANES_PRESETS.map((preset) => preset.id);
+
+export function isPanesPresetId(value: string): value is PanesPresetId {
+	return PANES_PRESETS.some((preset) => preset.id === value);
+}
+
+/** One pane Clio owns, flattened for display. */
+export interface PanesInventoryEntry {
+	paneId: string;
+	tabId: string;
+	purpose: "watch" | "utility";
+	label: string;
+	adopted: boolean;
+	/** An open operation admitted locally but not yet reconciled into the mux registry. */
+	pending?: boolean;
+}
+
+/** Effective pane settings, as `/panes` prints them. */
+export interface PanesEffectiveSettings {
+	enabled: string;
+	notifications: string;
+	journal: boolean;
+	yazi: {
+		enabled: boolean;
+		mode: "companion" | "chooser";
+		profile: "managed" | "user";
+		followCwd: boolean;
+	};
+}
+
+/** File-pane return-path state flattened for `/panes` and the model tool. */
+export interface PanesYaziStatus {
+	mode: "companion" | "chooser" | "closed";
+	paneId: string | null;
+	paneCwd: string | null;
+	lastLineAt: number | null;
+	droppedLines: number;
+}
+
+/** What `/panes` with no subcommand answers. */
+export interface PanesStatus {
+	mode: "embedded" | "guest" | "none";
+	available: boolean;
+	/** Why the mux resolved the way it did, straight from detection. */
+	reason: string;
+	socketPath: string | null;
+	server: { version: string; protocol: number } | null;
+	settings: PanesEffectiveSettings;
+	yazi: PanesYaziStatus;
+	panes: ReadonlyArray<PanesInventoryEntry>;
+}
+
+export type PanesShowResult =
+	| { status: "watching"; runId: string; agentId: string; opened: boolean }
+	| { status: "not-found"; target: string; candidates: ReadonlyArray<string> }
+	| { status: "refused"; reason: string }
+	| { status: "unavailable"; reason: string };
+
+/** What one watch call settles to; the controller lives in src/interactive/watch-pane.ts. */
+export type PanesWatchResult =
+	| { status: "watching"; runId: string; paneId: string; opened: boolean }
+	| { status: "unavailable"; reason: string };
+
+/**
+ * Interactive-only watch-pane controller, attached after the TUI exists. A
+ * structural interface here for the same reason {@link PanesYaziController}
+ * is: neither the domain nor the tool may import the interactive tree.
+ */
+export interface PanesWatchController {
+	/** Point the watch pane at a run, opening or adopting the pane first if needed. */
+	watch(runId: string): Promise<PanesWatchResult>;
+	/** Retarget only; false when no watch pane is open or the write failed. */
+	follow(runId: string): boolean;
+	isOpen(): boolean;
+	dispose(): void;
+}
+
+export type PanesOpenResult =
+	| { status: "opened"; label: string; paneId: string | null }
+	| { status: "missing-binary"; preset: string; binary: string; installHint: string; detail: string }
+	| { status: "refused"; reason: string }
+	| { status: "unavailable"; reason: string };
+
+export type PanesCloseResult =
+	| { status: "closed"; closed: number; labels: ReadonlyArray<string> }
+	| { status: "not-found"; target: string }
+	| { status: "unavailable"; reason: string };
+
+/**
+ * Interactive-only controller attached after the composer and TUI exist.
+ *
+ * This structural interface stays in the shared leaf so the panes domain does
+ * not import the interactive implementation and the tool does not gain a path
+ * into `src/interactive/**`.
+ */
+export interface PanesYaziController {
+	open(options?: {
+		once?: boolean;
+	}): Promise<
+		| { status: "opened"; mode: "companion" | "chooser"; paneId: string | null; existing: boolean }
+		| { status: "missing-binary"; binary: "yazi" | "ya"; detail: string }
+		| { status: "profile-error"; reason: string }
+		| { status: "unavailable"; reason: string }
+	>;
+	status(): Readonly<PanesYaziStatus>;
+}
+
+/**
+ * The operations both callers drive. The tool sees a narrower door: its schema
+ * has no argv field at all, and `open` refuses one even if a caller fabricates
+ * it.
+ */
+export interface PanesOperations {
+	status(): PanesStatus;
+	show(target: string): Promise<PanesShowResult>;
+	open(request: { preset?: string; argv?: ReadonlyArray<string>; once?: boolean }): Promise<PanesOpenResult>;
+	close(target: string): Promise<PanesCloseResult>;
+	/** Bind the composer-facing Yazi bridge without rebuilding this shared object. */
+	attachYazi(controller: PanesYaziController): () => void;
+	/** Bind the workers-view watch controller; `show` routes runs through it. */
+	attachWatch(controller: PanesWatchController): () => void;
+}

package/src/domains/mux/pane-registry.ts

@@ -0,0 +1,90 @@
+/**
+ * The set of panes Clio created, and the only panes Clio will ever act on.
+ *
+ * The ownership rule forbids closing, renaming, reporting state on, or sending
+ * input to a pane Clio did not create, so every mutating path in `contract.ts`
+ * asks this registry first. `pane.closed` and `pane.exited` events feed
+ * `forget`, and a post-reconnect `session.snapshot` feeds `reconcile`, so a
+ * pane the user closed behind Clio's back stops being in the inventory either
+ * way.
+ */
+
+import type { MuxPanePurpose, MuxPaneRecord, MuxPaneRef } from "./types.js";
+
+export interface MuxPaneRegistry {
+	/** Record a pane Clio just created. Replaces any record with the same pane id. */
+	record(entry: MuxPaneRecord): void;
+	byPaneId(paneId: string): MuxPaneRecord | null;
+	/** Newest pane of one purpose, e.g. the watch pane. */
+	byPurpose(purpose: MuxPanePurpose): MuxPaneRecord | null;
+	/** Whether Clio created this pane, and therefore may act on it. */
+	owns(paneId: string): boolean;
+	/** Drop one pane; returns the dropped record so callers can log what went. */
+	forget(paneId: string): MuxPaneRecord | null;
+	/**
+	 * Drop every record whose pane is absent from `livePaneIds`. Returns the
+	 * dropped records, oldest first.
+	 */
+	reconcile(livePaneIds: Iterable<string>): ReadonlyArray<MuxPaneRecord>;
+	list(): ReadonlyArray<MuxPaneRecord>;
+	clear(): void;
+}
+
+export function createPaneRegistry(): MuxPaneRegistry {
+	// Insertion-ordered, which is what makes `list()` read oldest-pane-first.
+	const byPane = new Map<string, MuxPaneRecord>();
+
+	return {
+		record(entry: MuxPaneRecord): void {
+			byPane.set(entry.ref.paneId, entry);
+		},
+		byPaneId(paneId: string): MuxPaneRecord | null {
+			return byPane.get(paneId) ?? null;
+		},
+		byPurpose(purpose: MuxPanePurpose): MuxPaneRecord | null {
+			let newest: MuxPaneRecord | null = null;
+			for (const entry of byPane.values()) {
+				if (entry.purpose === purpose) newest = entry;
+			}
+			return newest;
+		},
+		owns(paneId: string): boolean {
+			return byPane.has(paneId);
+		},
+		forget(paneId: string): MuxPaneRecord | null {
+			const entry = byPane.get(paneId);
+			if (!entry) return null;
+			byPane.delete(paneId);
+			return entry;
+		},
+		reconcile(livePaneIds: Iterable<string>): ReadonlyArray<MuxPaneRecord> {
+			const live = new Set(livePaneIds);
+			const dropped: MuxPaneRecord[] = [];
+			for (const [paneId, entry] of byPane) {
+				if (!live.has(paneId)) dropped.push(entry);
+			}
+			for (const entry of dropped) byPane.delete(entry.ref.paneId);
+			return dropped;
+		},
+		list(): ReadonlyArray<MuxPaneRecord> {
+			return [...byPane.values()];
+		},
+		clear(): void {
+			byPane.clear();
+		},
+	};
+}
+
+/** Convenience for building a registry entry from a freshly created pane. */
+export function paneRecord(
+	ref: MuxPaneRef,
+	fields: { purpose: MuxPanePurpose; label: string; openedAt: number; adopted?: boolean },
+): MuxPaneRecord {
+	return {
+		ref,
+		purpose: fields.purpose,
+		label: fields.label,
+		openedAt: fields.openedAt,
+		...(fields.adopted === true ? { adopted: true } : {}),
+	};
+}

package/src/domains/mux/protocol.ts

@@ -0,0 +1,49 @@
+/**
+ * Protocol floors for the wire methods that are not universal.
+ *
+ * Phase 1 recorded `protocol` and `version` from the `ping` handshake and gated
+ * nothing on them, because every method phase 1 used exists across the whole
+ * protocol range Clio cares about. Phase 3 adds two that do not, and Phase 4
+ * adds the worktree family: a herdr old
+ * enough to predate them answers `invalid_request`, and the honest response is
+ * to take the documented fallback rather than to log a failure per call.
+ * (`agent.focus` was gated here too until the per-run focus ladder was
+ * removed with the run viewer panes; nothing drives it any more.)
+ *
+ * The floors are protocol introductions checked against herdr's changelog and
+ * then re-verified with `herdr api schema --json` from PATH 0.7.5/protocol 17
+ * and pinned 0.8.2/protocol 21. Worktrees arrived in protocol 10; notification.show
+ * arrived in 17. Lower one only after checking the schema of
+ * the release you are lowering it to.
+ */
+
+import type { MuxServerInfo } from "./types.js";
+
+/** Wire methods this file gates. Phase 1 methods are unconditional and absent here. */
+export type MuxGatedMethod =
+	| "notification.show"
+	| "pane.rename"
+	| "worktree.list"
+	| "worktree.create"
+	| "worktree.open"
+	| "worktree.remove";
+
+export const MUX_METHOD_MIN_PROTOCOL: Readonly<Record<MuxGatedMethod, number>> = {
+	"notification.show": 17,
+	"pane.rename": 17,
+	"worktree.list": 10,
+	"worktree.create": 10,
+	"worktree.open": 10,
+	"worktree.remove": 10,
+};
+
+/**
+ * Whether the server that answered detection is new enough for `method`.
+ *
+ * A missing server record means detection never completed a handshake, which is
+ * the `none` rung: nothing is supported because nothing is there.
+ */
+export function muxSupportsMethod(server: MuxServerInfo | null, method: MuxGatedMethod): boolean {
+	if (server === null) return false;
+	return server.protocol >= MUX_METHOD_MIN_PROTOCOL[method];
+}