omp-multi-harness 0.1.0

package/src/tools/ask-agent.ts

@@ -0,0 +1,230 @@
+/**
+ * `ask_codex` / `ask_claude`. Both tools are the same surface over a different adapter, so
+ * they are built from one factory (_spec/06-tools.md).
+ */
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { MODE_DEFAULT_READ_ONLY, type AgentMode, type AgentName } from "../agents/types.ts";
+import type { MultiHarnessConfig } from "../config/schema.ts";
+import type { RunRegistry, RunView } from "../runs/types.ts";
+import { AgentError, agentDisabled } from "../process/process-error.ts";
+import { buildHandoff, summarize, truncateMiddle } from "../routing/handoff.ts";
+import { resolveWorkerModel } from "../routing/route.ts";
+
+const MODES = ["analyze", "plan", "implement", "debug", "review", "test"] as const;
+
+const DESCRIPTION: Record<AgentName, string> = {
+	codex:
+		"Delegate a coding task to the Codex CLI, which runs in this repository with its own tools and its own session. " +
+		"Best for implementation, debugging, refactoring, tests, and targeted code review. " +
+		"State the task as a self-contained instruction: the worker cannot see this conversation. " +
+		"Prefer a read-only review before giving any agent write access to the same files.",
+	claude:
+		"Delegate a task to the Claude Code CLI, which runs in this repository with its own tools and its own session. " +
+		"Best for architecture analysis, planning, design review, broad repository reasoning, and second opinions. " +
+		"State the task as a self-contained instruction: the worker cannot see this conversation. " +
+		"Prefer a read-only review before giving any agent write access to the same files.",
+};
+
+/** What the schema below accepts. OMP's Static<> inference does not survive the
+ *  `pi.zod` builder handed to an extension, so `execute` casts to this once. */
+interface AskAgentParams {
+	task: string;
+	mode?: AgentMode;
+	context?: string;
+	readOnly?: boolean;
+	continueSession?: boolean;
+	model?: string;
+	background?: boolean;
+}
+
+export interface AskAgentDeps {
+	pi: ExtensionAPI;
+	agent: AgentName;
+	getConfig: () => MultiHarnessConfig;
+	/** Taken as a getter so this module never imports the registry implementation. */
+	getRegistry: () => RunRegistry;
+}
+
+export function registerAskAgentTool({ pi, agent, getConfig, getRegistry }: AskAgentDeps): void {
+	const z = pi.zod;
+
+	pi.registerTool({
+		name: `ask_${agent}`,
+		label: agent === "codex" ? "Ask Codex" : "Ask Claude",
+		description: DESCRIPTION[agent],
+		// NOTE: OMP's ToolDefinition has no promptSnippet/promptGuidelines (those are upstream
+		// pi's API). Routing guidance is carried by the description instead — see T-503.
+		approval: "exec",
+		parameters: z.object({
+			task: z.string().describe("A self-contained instruction. The worker cannot see this conversation."),
+			mode: z.enum(MODES).optional().describe("Shapes the instruction and the default read-only setting."),
+			context: z.string().optional().describe("Compact handoff context. Never paste the whole conversation."),
+			readOnly: z.boolean().optional().describe("Force read-only. Defaults from mode."),
+			continueSession: z.boolean().optional().describe("Reuse this session's worker session. Default true."),
+			model: z.string().optional().describe("Worker model override. Omit to use the CLI's own configuration."),
+			background: z
+				.boolean()
+				.optional()
+				.describe("Return a run id immediately instead of waiting. Check it with agent_runs or /sessions."),
+		}),
+		async execute(_toolCallId, rawParams, signal, _onUpdate, ctx: ExtensionContext) {
+			const params = rawParams as AskAgentParams;
+			const config = getConfig();
+			const agentConfig = config[agent];
+
+			if (!config.enabled || !agentConfig.enabled) {
+				const error = agentDisabled(agent);
+				return { content: [{ type: "text" as const, text: error.message }], isError: true };
+			}
+
+			const mode = params.mode;
+			const readOnly = params.readOnly ?? (mode ? MODE_DEFAULT_READ_ONLY[mode] : false);
+
+			const task = buildHandoff({
+				task: params.task,
+				mode,
+				context: params.context,
+				maxChars: config.limits.maxHandoffChars,
+			});
+
+			// Both paths go through the registry, not straight to the adapter: that is what gives
+			// every call the workspace write lock, the concurrency cap, and a row in `/sessions`.
+			const registry = getRegistry();
+			const started = registry.start({
+				agent,
+				task,
+				summary: summarize(params.task),
+				cwd: ctx.cwd,
+				mode,
+				readOnly,
+				model: params.model,
+				continueSession: params.continueSession,
+				background: params.background === true,
+			});
+
+			// T-507 precedence lives in one place; this tool must not re-derive it.
+			const resolvedModel = resolveWorkerModel(params.model, agentConfig.model).model ?? null;
+
+			if (params.background === true) {
+				// Detached by design. `.catch` is mandatory — an unhandled rejection here would
+				// escape into the OMP session (_spec/01 §2).
+				registry
+					.wait(started.id)
+					.then((finished) => {
+						if (finished) deliverBackgroundResult({ pi, ctx, run: finished, config });
+					})
+					.catch((e) => pi.logger.warn?.(`[multi-harness] background run ${started.id}: ${(e as Error).message}`));
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text:
+								`Started ${agent} run \`${started.id}\` in the background (${started.status}).\n` +
+								`Check it with \`agent_runs\` (action: "status" or "wait") or \`/sessions\`.`,
+						},
+					],
+					details: { agent, runId: started.id, status: started.status, background: true, model: resolvedModel },
+				};
+			}
+
+			try {
+				const abort = signal ?? new AbortController().signal;
+				const onAbort = () => void registry.cancel(started.id);
+				abort.addEventListener("abort", onAbort, { once: true });
+
+				const unsubscribe = registry.subscribe((run) => {
+					if (run.id === started.id) ctx.ui.setStatus("multi-harness", `${agent}: ${run.phase}`);
+				});
+
+				try {
+					const finished = await registry.wait(started.id);
+					if (!finished) {
+						return { content: [{ type: "text" as const, text: `Run ${started.id} disappeared from the registry.` }], isError: true };
+					}
+					if (finished.status !== "done") {
+						const detail = finished.errorMessage ?? `run ${finished.status}`;
+						return {
+							content: [{ type: "text" as const, text: `${finished.errorCode ?? finished.status.toUpperCase()}: ${detail}` }],
+							isError: true,
+							details: { agent, runId: finished.id, status: finished.status },
+						};
+					}
+
+					const { text, truncated } = truncateMiddle(finished.output ?? "", config.limits.maxOutputChars);
+					return {
+						content: [{ type: "text" as const, text }],
+						details: {
+							agent,
+							runId: finished.id,
+							sessionId: finished.workerSessionId,
+							durationMs: finished.elapsedMs,
+							// The adapter's claim, derived from the argv it actually built — not the
+							// caller's request. Absent metadata means the adapter could not prove it.
+							readOnlyRequested: readOnly,
+							readOnlyEnforced: finished.metadata?.readOnlyEnforced === true,
+							readOnlyMechanism: finished.metadata?.readOnlyMechanism ?? null,
+							truncated,
+							model: resolvedModel,
+							routedBy: "explicit" as const,
+						},
+					};
+				} finally {
+					unsubscribe();
+					abort.removeEventListener("abort", onAbort);
+				}
+			} catch (e) {
+				const message =
+					e instanceof AgentError
+						? `${e.code}: ${e.message}`
+						: `Unexpected failure delegating to ${agent}: ${(e as Error).message}`;
+				return { content: [{ type: "text" as const, text: message }], isError: true };
+			} finally {
+				ctx.ui.setStatus("multi-harness", undefined);
+			}
+		},
+	});
+}
+
+export interface BackgroundDeliveryDeps {
+	pi: ExtensionAPI;
+	ctx: ExtensionContext;
+	run: RunView;
+	config: MultiHarnessConfig;
+}
+
+/**
+ * Called when a `background: true` run reaches a terminal status. The supervisor is very
+ * likely mid-turn on something else by now, so how loudly this lands is a policy choice —
+ * see the TODO below.
+ */
+export function deliverBackgroundResult({ pi, ctx, run, config }: BackgroundDeliveryDeps): void {
+	// Always durable first: spec 08 requires a finished background run to survive a reload,
+	// and `appendEntry` is state-only (never sent to the LLM), so it is safe unconditionally.
+	pi.appendEntry("multi-harness-run", {
+		runId: run.id,
+		agent: run.agent,
+		status: run.status,
+		workerSessionId: run.workerSessionId,
+		summary: run.summary,
+		elapsedMs: run.elapsedMs,
+	});
+
+	// Deliberately a notification, not a `pi.sendUserMessage` injection. A background run
+	// finishes at an arbitrary moment — very likely while the supervisor is mid-turn on
+	// something unrelated — and injecting the worker's output there would derail that turn.
+	// The caller was handed a run id and told to poll, so `agent_runs` and `/sessions` are
+	// the retrieval path; this only has to make sure a finished run is never *missed*.
+	const label = `${run.agent} run ${run.id}`;
+	if (run.status === "done") {
+		const { text } = truncateMiddle(run.output ?? "", Math.min(240, config.limits.maxOutputChars));
+		const preview = text.replace(/\s+/g, " ").trim();
+		ctx.ui.notify(`${label} finished. ${preview || "(no output)"}`, "info");
+		return;
+	}
+
+	// A silent failure costs more than a silent success: the caller may still be waiting on
+	// work that will never arrive, so failures and cancellations always say why.
+	const reason = run.errorMessage ?? run.status;
+	ctx.ui.notify(`${label} ${run.status}: ${run.errorCode ? `${run.errorCode} — ` : ""}${reason}`, "error");
+}

package/src/tools/delegate.ts

@@ -0,0 +1,196 @@
+/**
+ * `delegate` (T-501) — one entry point that picks the agent for you.
+ *
+ * Same surface as `ask_codex` / `ask_claude` plus `agent: "auto" | "codex" | "claude"` and
+ * `background`. Routing is done by `routing/route.ts` and always reported back in `details`
+ * (`routedBy` + the reason), so no delegation is a black box (_spec/06-tools.md).
+ */
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { detect } from "../agents/availability.ts";
+import { MODE_DEFAULT_READ_ONLY, type AgentAvailability, type AgentMode, type AgentName } from "../agents/types.ts";
+import type { MultiHarnessConfig } from "../config/schema.ts";
+import { buildHandoff, summarize } from "../routing/handoff.ts";
+import { createModelRouter, resolveWorkerModel, route, usabilityFrom, type RouterModelFn } from "../routing/route.ts";
+import type { RunRegistry } from "../runs/types.ts";
+import { renderRunView } from "./agent-runs.ts";
+
+const AGENTS = ["auto", "codex", "claude"] as const;
+const MODES = ["analyze", "plan", "implement", "debug", "review", "test"] as const;
+
+const DESCRIPTION =
+	"Delegate one self-contained task to an external coding CLI running in this repository. " +
+	"agent: \"auto\" lets the harness route it — Codex for implementation, debugging, refactoring and tests, " +
+	"Claude for architecture analysis, planning, review and second opinions — and the result says how it routed. " +
+	"Use ask_codex / ask_claude when you already know which one you want. " +
+	"With background: true it returns a run id immediately; join it later with agent_runs.";
+
+/** What the schema below accepts — see the cast note in `ask-agent.ts`. */
+interface DelegateParams {
+	agent?: "auto" | AgentName;
+	task: string;
+	mode?: AgentMode;
+	context?: string;
+	readOnly?: boolean;
+	continueSession?: boolean;
+	background?: boolean;
+	model?: string;
+}
+
+export interface DelegateDeps {
+	pi: ExtensionAPI;
+	getConfig: () => MultiHarnessConfig;
+	/** Taken as a getter so this module never imports the registry implementation. */
+	getRegistry: () => RunRegistry;
+	/** Injected so tests never spawn a process. Defaults to the cached detector. */
+	getAvailability?: (agent: AgentName, config: MultiHarnessConfig, cwd: string) => Promise<AgentAvailability | undefined>;
+	/** Injected so tests never make a network call. Returning undefined forces the rules path. */
+	createRouter?: (ctx: ExtensionContext, config: MultiHarnessConfig) => RouterModelFn | undefined;
+}
+
+const defaultAvailability = async (agent: AgentName, config: MultiHarnessConfig, cwd: string) =>
+	// Auth is not probed here: it costs a process spawn per call, and an unauthenticated
+	// worker fails loudly on its own with an actionable error.
+	detect(agent, config[agent], { cwd, skipAuth: true });
+
+const defaultRouter = (ctx: ExtensionContext, config: MultiHarnessConfig): RouterModelFn | undefined =>
+	config.routing.mode === "model"
+		? createModelRouter(ctx, [config.routing.model, ...config.routing.modelFallbacks])
+		: undefined;
+
+export function registerDelegateTool({ pi, getConfig, getRegistry, getAvailability, createRouter }: DelegateDeps): void {
+	const z = pi.zod;
+	const availabilityOf = getAvailability ?? defaultAvailability;
+	const routerFor = createRouter ?? defaultRouter;
+
+	pi.registerTool({
+		name: "delegate",
+		label: "Delegate",
+		description: DESCRIPTION,
+		// NOTE: OMP's ToolDefinition has no promptSnippet/promptGuidelines (upstream pi only).
+		// Broader guidance lives in routing/prompt.ts — see T-503.
+		approval: "exec",
+		parameters: z.object({
+			agent: z.enum(AGENTS).optional().describe("Which agent to use. Default \"auto\" — the harness routes it."),
+			task: z.string().describe("A self-contained instruction. The worker cannot see this conversation."),
+			mode: z.enum(MODES).optional().describe("Shapes the instruction, the default read-only setting, and routing."),
+			context: z.string().optional().describe("Compact handoff context. Never paste the whole conversation."),
+			readOnly: z.boolean().optional().describe("Force read-only. Defaults from mode."),
+			continueSession: z.boolean().optional().describe("Reuse this session's worker session. Default true."),
+			background: z
+				.boolean()
+				.optional()
+				.describe("Return a run id immediately instead of waiting. Join it with agent_runs."),
+			model: z.string().optional().describe("Worker model override. Omit to use the CLI's own configuration."),
+		}),
+		async execute(_toolCallId, rawParams, signal, _onUpdate, ctx: ExtensionContext) {
+			const params = rawParams as DelegateParams;
+			const config = getConfig();
+
+			if (!config.enabled) {
+				return { content: [{ type: "text" as const, text: "multi-harness is disabled (multiHarness.enabled: false)." }], isError: true };
+			}
+
+			const detected: Partial<Record<AgentName, AgentAvailability>> = {};
+			for (const agent of ["codex", "claude"] as const) {
+				if (!config[agent].enabled) continue;
+				try {
+					detected[agent] = await availabilityOf(agent, config, ctx.cwd);
+				} catch {
+					// Detection is advisory; a failure here must not stop a delegation.
+				}
+			}
+
+			const decision = await route(
+				{ agent: params.agent, task: params.task, mode: params.mode },
+				{
+					config,
+					usability: usabilityFrom(config, detected),
+					askModel: routerFor(ctx, config),
+					signal: signal ?? undefined,
+				},
+			);
+
+			if (!decision.ok) {
+				return { content: [{ type: "text" as const, text: decision.reason }], isError: true };
+			}
+
+			const agent = decision.agent;
+			const mode = params.mode;
+			const readOnly = params.readOnly ?? (mode ? MODE_DEFAULT_READ_ONLY[mode] : false);
+			const worker = resolveWorkerModel(params.model, config[agent].model);
+			if (worker.warning) pi.logger.warn?.(`[multi-harness] ${worker.warning}`);
+
+			const task = buildHandoff({
+				task: params.task,
+				mode,
+				context: params.context,
+				maxChars: config.limits.maxHandoffChars,
+			});
+
+			const routing = { routedBy: decision.routedBy, routingReason: decision.reason };
+
+			try {
+				const started = getRegistry().start({
+					agent,
+					task,
+					summary: summarize(params.task),
+					cwd: ctx.cwd,
+					mode,
+					readOnly,
+					model: worker.model,
+					continueSession: params.continueSession,
+					background: params.background === true,
+				});
+
+				if (params.background === true) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text:
+									`[${agent} · running · ${started.id}] routed by ${decision.routedBy}: ${decision.reason}\n` +
+									`Started in the background. Join it with agent_runs (action "wait", runId "${started.id}").`,
+							},
+						],
+						details: { runId: started.id, status: "running" as const, agent, model: worker.model ?? null, ...routing },
+					};
+				}
+
+				// Foreground: a caller-side abort must stop the child, not just stop waiting.
+				const onAbort = () => void getRegistry().cancel(started.id);
+				signal?.addEventListener("abort", onAbort, { once: true });
+				try {
+					const view = (await getRegistry().wait(started.id)) ?? getRegistry().get(started.id);
+					if (!view) {
+						return { content: [{ type: "text" as const, text: `Run ${started.id} disappeared before it produced a result.` }], isError: true };
+					}
+					const rendered = renderRunView(view, config.limits.maxOutputChars);
+					return {
+						content: [{ type: "text" as const, text: `${rendered.text}\n\nrouted by ${decision.routedBy}: ${decision.reason}` }],
+						details: {
+							runId: view.id,
+							agent,
+							sessionId: view.workerSessionId,
+							status: view.status,
+							durationMs: view.elapsedMs,
+							readOnlyEnforced: readOnly,
+							truncated: rendered.truncated,
+							model: worker.model ?? null,
+							...routing,
+						},
+						isError: view.status === "failed",
+					};
+				} finally {
+					signal?.removeEventListener("abort", onAbort);
+					ctx.ui.setStatus("multi-harness", undefined);
+				}
+			} catch (e) {
+				return {
+					content: [{ type: "text" as const, text: `Could not delegate to ${agent}: ${(e as Error).message}` }],
+					details: { agent, ...routing },
+					isError: true,
+				};
+			}
+		},
+	});
+}