@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/tools/result-shaping.ts

@@ -0,0 +1,204 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { clioStateDir } from "../core/xdg.js";
+import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
+import { DEFAULT_MAX_BYTES } from "./truncate.js";
+import { byteLength, truncateUtf8 } from "./truncate-utf8.js";
+
+// Backstop for tools without an explicit resultSizePolicy. Sits above the
+// per-observation source cap (src/tools/truncate.ts) so a tool's own truncation
+// notice (with its precise continuation offset) survives shaping instead of
+// being cut again and replaced by a generic hint.
+export const DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES + 2 * 1024;
+const RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
+const RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
+
+type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId">;
+
+function mergeDetails(details: ToolResultDetails | undefined, resultSize: Record<string, unknown>): ToolResultDetails {
+	return { ...(details ?? {}), resultSize };
+}
+
+function maxBytesFor(spec: ToolSpec): number {
+	const configured = spec.metadata?.resultSizePolicy?.maxBytes;
+	return typeof configured === "number" && Number.isFinite(configured) && configured > 0
+		? Math.floor(configured)
+		: DEFAULT_TOOL_RESULT_MAX_BYTES;
+}
+
+function followUpHint(spec: ToolSpec): string {
+	return (
+		spec.metadata?.resultSizePolicy?.followUpHint ??
+		"Use a narrower query, offset/limit arguments, or a more specific tool call to inspect the omitted content."
+	);
+}
+
+function detailsRecord(details: ToolResultDetails | undefined, key: string): Record<string, unknown> | null {
+	const candidate = details?.[key];
+	return candidate !== null && typeof candidate === "object" && !Array.isArray(candidate)
+		? (candidate as Record<string, unknown>)
+		: null;
+}
+
+/**
+ * A result that already spilled its full text to scratch (bash's tail-biased
+ * shaping via `resultSize.offloadPath`, or an OBSERVE tool's envelope via
+ * `observation.offloadPath`) is left alone; the tool shaped it deliberately
+ * and the backstop would only cut the tool's own continuation notice.
+ */
+function existingOffloadPath(details: ToolResultDetails | undefined): string | null {
+	const fromResultSize = detailsRecord(details, "resultSize")?.offloadPath;
+	if (typeof fromResultSize === "string" && fromResultSize.length > 0) return fromResultSize;
+	const fromObservation = detailsRecord(details, "observation")?.offloadPath;
+	return typeof fromObservation === "string" && fromObservation.length > 0 ? fromObservation : null;
+}
+
+function safePathSegment(value: string): string {
+	const safe = value
+		.trim()
+		.replace(/[^A-Za-z0-9._-]/g, "_")
+		.slice(0, 128);
+	return safe.length > 0 ? safe : "unnamed";
+}
+
+function timestampSegment(): string {
+	return new Date().toISOString().replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+function offloadBody(text: string, bytes: number, maxBytes: number): string {
+	if (bytes <= maxBytes) return text;
+	const notice = `\n[clio-coder scratch output truncated at ${maxBytes} bytes; original size ${bytes} bytes]`;
+	const prefixBudget = maxBytes - byteLength(notice);
+	return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
+}
+
+/**
+ * Persist the full text of a tool result to a per-session scratch file and
+ * return its path (or null if the write fails). Callers that truncate their own
+ * display output (for example bash's tail-biased shaping) use this to spill the
+ * complete output before truncating, then set `details.resultSize.offloadPath`
+ * so the registry re-truncation pass leaves the already-shaped result alone.
+ */
+export function writeToolOffload(
+	text: string,
+	context: ToolResultShapeContext | undefined,
+	maxBytes: number = RESULT_OFFLOAD_MAX_BYTES,
+): string | null {
+	try {
+		const bytes = byteLength(text);
+		const sessionId = safePathSegment(context?.sessionId ?? "no-session");
+		const callId = safePathSegment(context?.toolCallId ?? timestampSegment());
+		const dir = join(clioStateDir(), "scratch", sessionId);
+		const path = join(dir, `${callId}.txt`);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(path, offloadBody(text, bytes, maxBytes), "utf8");
+		return path;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The one framing for an offload pointer, shared by every truncation notice.
+ * The path is a read-only overflow copy under Clio's state directory, and a
+ * bare absolute path there reads to a model like somewhere it is working: an
+ * observed run took the pointer as its working directory, wrote its notes
+ * beside it, and never touched the repository again. Naming what the path is
+ * costs a few tokens on truncated results and removes that reading.
+ */
+export const OFFLOAD_POINTER_NOTE = "overflow copy, read-only; not the workspace";
+
+/** `full: <path> (<note>)`, the exact form every truncation notice carries. */
+export function offloadPointer(offloadPath: string): string {
+	return `full: ${offloadPath} (${OFFLOAD_POINTER_NOTE})`;
+}
+
+/**
+ * True when filePath points inside this session's offload scratch directory
+ * (where {@link writeToolOffload} spills full results). Reads of the session's
+ * own offloaded output are exempt from the per-turn observation pool: the
+ * "full: <path>" escape hatch a truncation stub offers must stay readable
+ * exactly when that pool is exhausted, which is when the stub appears.
+ */
+export function isSessionOffloadPath(filePath: string, sessionId: string | undefined): boolean {
+	const dir = join(clioStateDir(), "scratch", safePathSegment(sessionId ?? "no-session"));
+	const rel = relative(dir, resolve(filePath));
+	return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+function bracketedHint(spec: ToolSpec, offloadPath: string | null): string {
+	const hint = followUpHint(spec);
+	if (offloadPath === null) return hint;
+	return `${hint} ${offloadPointer(offloadPath)}; read it with offset and limit to inspect the rest.`;
+}
+
+/**
+ * Backstop for an oversize result that declared itself JSON via
+ * `details.observation.format`. Cutting mid-document would hand the model
+ * unparseable JSON, so the whole payload is offloaded and replaced with a
+ * parseable stub carrying the path and the exact continuation call.
+ */
+function shapeJsonOverflow(
+	spec: ToolSpec,
+	result: ToolResult,
+	text: string,
+	bytes: number,
+	maxBytes: number,
+	context: ToolResultShapeContext | undefined,
+): ToolResult {
+	const observation = detailsRecord(result.details, "observation");
+	const offloadPath = writeToolOffload(text, context);
+	const next =
+		typeof observation?.next === "string" && observation.next.length > 0 ? observation.next : followUpHint(spec);
+	const stub = JSON.stringify({
+		error: `result exceeded ${maxBytes} bytes`,
+		...(offloadPath !== null ? { offloadPath, offloadPathNote: OFFLOAD_POINTER_NOTE } : {}),
+		next,
+	});
+	const resultSize = {
+		bytes,
+		shownBytes: byteLength(stub),
+		maxBytes,
+		truncated: true,
+		policy: spec.metadata?.resultSizePolicy?.kind ?? "truncate",
+		followUpHint: followUpHint(spec),
+		...(offloadPath !== null ? { offloadPath } : {}),
+	};
+	if (result.kind === "ok") {
+		return { ...result, output: stub, details: mergeDetails(result.details, resultSize) };
+	}
+	return { ...result, message: stub, details: mergeDetails(result.details, resultSize) };
+}
+
+export function shapeToolResult(spec: ToolSpec, result: ToolResult, context?: ToolResultShapeContext): ToolResult {
+	if (existingOffloadPath(result.details) !== null) return result;
+	const maxBytes = maxBytesFor(spec);
+	const text = result.kind === "ok" ? result.output : result.message;
+	const bytes = byteLength(text);
+	if (bytes <= maxBytes) return result;
+	const observation = detailsRecord(result.details, "observation");
+	if (observation?.format === "json") return shapeJsonOverflow(spec, result, text, bytes, maxBytes, context);
+	const truncated = truncateUtf8(text, maxBytes, RESULT_TRUNCATION_MARKER);
+	const offloadPath = writeToolOffload(text, context);
+	const resultSize = {
+		bytes,
+		shownBytes: byteLength(truncated),
+		maxBytes,
+		truncated: true,
+		policy: spec.metadata?.resultSizePolicy?.kind ?? "truncate",
+		followUpHint: followUpHint(spec),
+		...(offloadPath !== null ? { offloadPath } : {}),
+	};
+	if (result.kind === "ok") {
+		return {
+			...result,
+			output: `${truncated}\n\n[${bracketedHint(spec, offloadPath)}]`,
+			details: mergeDetails(result.details, resultSize),
+		};
+	}
+	return {
+		...result,
+		message: `${truncated}\n\n[${bracketedHint(spec, offloadPath)}]`,
+		details: mergeDetails(result.details, resultSize),
+	};
+}

package/src/tools/safe-exec.ts

@@ -0,0 +1,128 @@
+import { Type } from "typebox";
+import {
+	combineSafeOutput,
+	runCommandVector,
+	SAFE_EXEC_DEFAULT_MAX_OUTPUT_BYTES,
+	SAFE_EXEC_DEFAULT_TIMEOUT_MS,
+	type SafeCommandResult,
+} from "../core/safe-exec.js";
+import { ToolNames } from "../core/tool-names.js";
+import type { ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
+import { stringEnum } from "./string-enum.js";
+import { truncateUtf8 } from "./truncate-utf8.js";
+
+const TRUNCATION_MARKER = "\n[output truncated]\n";
+
+export function timeoutArg(args: Record<string, unknown>, fallback = SAFE_EXEC_DEFAULT_TIMEOUT_MS): number {
+	return typeof args.timeout_ms === "number" && args.timeout_ms > 0 ? Math.floor(args.timeout_ms) : fallback;
+}
+
+function cwdArg(args: Record<string, unknown>): string | undefined {
+	return typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined;
+}
+
+export function maxOutputArg(args: Record<string, unknown>): number {
+	return typeof args.max_output_bytes === "number" && args.max_output_bytes > 0
+		? Math.floor(args.max_output_bytes)
+		: SAFE_EXEC_DEFAULT_MAX_OUTPUT_BYTES;
+}
+
+/**
+ * The EXECUTE plane's standardized exec record: what ran, where, how it
+ * ended, how long it took, and whether output was capped. Shared by git and
+ * verify so ledgers and observers read one shape.
+ */
+function resultDetails(result: SafeCommandResult): ToolResultDetails {
+	return {
+		command: [result.file, ...result.args].join(" "),
+		cwd: result.cwd,
+		exitCode: result.exitCode,
+		durationMs: result.durationMs,
+		timedOut: result.timedOut,
+		outputCapped: result.outputCapped,
+	};
+}
+
+export async function runVectorTool(
+	action: string,
+	file: string,
+	vectorArgs: ReadonlyArray<string>,
+	args: Record<string, unknown>,
+	options?: { signal?: AbortSignal },
+): Promise<ToolResult> {
+	const timeoutMs = timeoutArg(args);
+	const maxOutputBytes = maxOutputArg(args);
+	try {
+		const runOptions: Parameters<typeof runCommandVector>[2] = { timeoutMs, maxOutputBytes };
+		const cwd = cwdArg(args);
+		if (cwd !== undefined) runOptions.cwd = cwd;
+		if (options?.signal !== undefined) runOptions.signal = options.signal;
+		const result = await runCommandVector(file, vectorArgs, runOptions);
+		const output = truncateUtf8(combineSafeOutput(result), maxOutputBytes, TRUNCATION_MARKER);
+		const details = resultDetails(result);
+		if (result.aborted) return { kind: "error", message: `${action}: aborted`, details };
+		if (result.timedOut) {
+			const status = `${action}: timed out after ${timeoutMs}ms`;
+			return { kind: "error", message: output.trim().length > 0 ? `${status}\n\n${output.trim()}` : status, details };
+		}
+		if (result.outputCapped)
+			return {
+				kind: "error",
+				message:
+					output.trim().length > 0
+						? `${action}: output exceeded ${maxOutputBytes} bytes\n\n${output.trim()}`
+						: `${action}: output exceeded ${maxOutputBytes} bytes`,
+				details,
+			};
+		if (result.exitCode !== 0) {
+			return {
+				kind: "error",
+				message: `${action}: exited with code ${result.exitCode ?? "?"}: ${output.trim()}`,
+				details,
+			};
+		}
+		return { kind: "ok", output, details };
+	} catch (err) {
+		return { kind: "error", message: `${action}: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}
+
+export const gitTool: ToolSpec = {
+	name: ToolNames.Git,
+	description: "Read-only git inspection: op=status (short status), diff, or log (oneline).",
+	parameters: Type.Object({
+		op: stringEnum(["status", "diff", "log"], "Inspection to run."),
+		path: Type.Optional(Type.String({ description: "Limit diff/log to one path." })),
+		cached: Type.Optional(Type.Boolean({ description: "diff: staged changes (--cached)." })),
+		stat: Type.Optional(Type.Boolean({ description: "diff: summary only (--stat)." })),
+		name_only: Type.Optional(Type.Boolean({ description: "diff: file names only." })),
+		limit: Type.Optional(Type.Number({ description: "log: commits to show (default 20, max 200)." })),
+		cwd: Type.Optional(Type.String({ description: "Working directory." })),
+		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in ms (default 120000)." })),
+		max_output_bytes: Type.Optional(Type.Number({ description: "Output cap in bytes (default 600000)." })),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+	async run(args, options) {
+		const op = typeof args.op === "string" ? args.op : "";
+		const pathArg = typeof args.path === "string" && args.path.length > 0 ? args.path : null;
+		if (op === "status") {
+			return runVectorTool("git", "git", ["status", "--short", "--branch"], args, options);
+		}
+		if (op === "diff") {
+			const vector = ["diff"];
+			if (args.cached === true) vector.push("--cached");
+			if (args.stat === true) vector.push("--stat");
+			if (args.name_only === true) vector.push("--name-only");
+			if (pathArg) vector.push("--", pathArg);
+			return runVectorTool("git", "git", vector, args, options);
+		}
+		if (op === "log") {
+			const limit = typeof args.limit === "number" && args.limit > 0 ? Math.min(200, Math.floor(args.limit)) : 20;
+			const vector = ["log", "--oneline", "-n", String(limit)];
+			if (pathArg) vector.push("--", pathArg);
+			return runVectorTool("git", "git", vector, args, options);
+		}
+		return { kind: "error", message: `git: op must be status, diff, or log; got '${op}'` };
+	},
+};

package/src/tools/spawn-hygiene.ts

@@ -0,0 +1,182 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { buildSafeToolEnv } from "../core/safe-exec.js";
+
+/**
+ * Hygienic line-stream spawner for the search binaries (rg, fd). Matches the
+ * containment posture of src/core/safe-exec.ts that git/verify already get:
+ * allowlisted env, cwd pinned to the workspace root, a wall-clock timeout,
+ * and SIGTERM-then-SIGKILL process-group teardown. Callers consume stdout
+ * line-by-line and may stop early (match limit reached) without waiting for
+ * the child to drain.
+ */
+
+export const SEARCH_SPAWN_TIMEOUT_MS = 30_000;
+const KILL_GRACE_MS = 3_000;
+const STDERR_CAP_BYTES = 16 * 1024;
+
+/**
+ * Per-argument byte ceiling for the search binaries. Linux caps a single argv
+ * entry at MAX_ARG_STRLEN (PAGE_SIZE * 32 = 128 KiB); handing spawn a longer
+ * string throws a raw `spawn E2BIG` before the child ever runs. The search
+ * tools guard their one unbounded argument — the caller-supplied pattern — well
+ * under that so an oversized pattern returns a bounded validation error instead
+ * of leaking the platform fault, and the pure-Node fallbacks never compile a
+ * multi-hundred-KB regex either. 64 KiB is far past any real search pattern.
+ */
+export const MAX_SEARCH_PATTERN_BYTES = 64 * 1024;
+
+/**
+ * Validate a search pattern's byte size before it reaches spawn (or a fallback
+ * regex compile). Returns the caller-agnostic message body; each searcher
+ * prefixes it with its own tool name.
+ */
+export function validateSearchPatternSize(pattern: string): { ok: true } | { ok: false; message: string } {
+	const bytes = Buffer.byteLength(pattern, "utf8");
+	if (bytes <= MAX_SEARCH_PATTERN_BYTES) return { ok: true };
+	return {
+		ok: false,
+		message: `pattern too large (${bytes} bytes; max ${MAX_SEARCH_PATTERN_BYTES}). Narrow the pattern before searching.`,
+	};
+}
+
+export interface LineStreamOptions {
+	/** Spawn cwd; defaults to the workspace root (process.cwd()). */
+	cwd?: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	/** Called per stdout line. Invoke `stop()` to kill the child early. */
+	onLine(line: string, stop: () => void): void;
+}
+
+export interface LineStreamResult {
+	exitCode: number | null;
+	stderr: string;
+	timedOut: boolean;
+	aborted: boolean;
+	/** True when the caller's `stop()` killed the child (not an error). */
+	stoppedEarly: boolean;
+	/** Spawn-level failure (binary missing, EACCES); null when the child ran. */
+	spawnError: string | null;
+}
+
+export function spawnLineStream(
+	file: string,
+	args: ReadonlyArray<string>,
+	options: LineStreamOptions,
+): Promise<LineStreamResult> {
+	return new Promise((resolve) => {
+		const timeoutMs = options.timeoutMs ?? SEARCH_SPAWN_TIMEOUT_MS;
+		let timedOut = false;
+		let aborted = false;
+		let stoppedEarly = false;
+		let killSent = false;
+		let settled = false;
+		let stderr = "";
+		let killGraceTimer: ReturnType<typeof setTimeout> | null = null;
+
+		// spawn can throw synchronously (e.g. an argv entry over MAX_ARG_STRLEN
+		// raises E2BIG). Route that through the documented spawnError channel so
+		// callers see a spawn-level failure instead of a rejected promise; the
+		// search tools validate pattern size up front, so this is a backstop. The
+		// IIFE keeps the child's narrowed stdio typing (non-null stdout) that an
+		// explicit ReturnType<typeof spawn> annotation would widen away.
+		const spawned = (() => {
+			try {
+				return {
+					ok: true as const,
+					child: spawn(file, [...args], {
+						cwd: options.cwd ?? process.cwd(),
+						env: buildSafeToolEnv(),
+						detached: process.platform !== "win32",
+						stdio: ["ignore", "pipe", "pipe"],
+					}),
+				};
+			} catch (error) {
+				return { ok: false as const, message: error instanceof Error ? error.message : String(error) };
+			}
+		})();
+		if (!spawned.ok) {
+			resolve({
+				exitCode: null,
+				stderr: "",
+				timedOut: false,
+				aborted: false,
+				stoppedEarly: false,
+				spawnError: spawned.message,
+			});
+			return;
+		}
+		const child = spawned.child;
+		const rl = createInterface({ input: child.stdout });
+
+		const sendSignal = (signalName: NodeJS.Signals): void => {
+			const pid = child.pid;
+			if (pid && process.platform !== "win32") {
+				try {
+					process.kill(-pid, signalName);
+					return;
+				} catch {
+					// Fall through to killing the direct child.
+				}
+			}
+			child.kill(signalName);
+		};
+
+		const killChild = (): void => {
+			if (killSent) return;
+			killSent = true;
+			sendSignal("SIGTERM");
+			killGraceTimer = setTimeout(() => sendSignal("SIGKILL"), KILL_GRACE_MS);
+			killGraceTimer.unref?.();
+		};
+
+		const stop = (): void => {
+			if (stoppedEarly) return;
+			stoppedEarly = true;
+			killChild();
+		};
+
+		const onAbort = (): void => {
+			aborted = true;
+			killChild();
+		};
+
+		const timeoutTimer = setTimeout(() => {
+			timedOut = true;
+			killChild();
+		}, timeoutMs);
+		timeoutTimer.unref?.();
+		if (options.signal?.aborted) onAbort();
+		else options.signal?.addEventListener("abort", onAbort, { once: true });
+
+		const finish = (spawnError: string | null): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutTimer);
+			if (killGraceTimer) clearTimeout(killGraceTimer);
+			options.signal?.removeEventListener("abort", onAbort);
+			rl.close();
+			resolve({
+				exitCode: child.exitCode,
+				stderr,
+				timedOut,
+				aborted,
+				stoppedEarly,
+				spawnError,
+			});
+		};
+
+		rl.on("line", (line) => {
+			// Lines buffered before an early stop still flush through readline;
+			// they no longer count once the caller decided it has enough.
+			if (stoppedEarly || aborted || timedOut) return;
+			options.onLine(line, stop);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			if (stderr.length < STDERR_CAP_BYTES) stderr += chunk.toString("utf8");
+		});
+		child.on("error", (error) => finish(error.message));
+		child.on("close", () => finish(null));
+	});
+}

package/src/tools/steer.ts

@@ -0,0 +1,88 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { DispatchContract } from "../domains/dispatch/contract.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { stringEnum } from "./string-enum.js";
+
+/**
+ * The steer tool: control a running dispatched worker. action=guide injects a
+ * steering message the worker sees at its next turn boundary (native workers
+ * only; the dispatch contract's stdin channel). action=cancel terminates the
+ * run cleanly; the receipt records the cancellation.
+ */
+
+const TERMINAL_STATUSES = new Set(["completed", "failed", "interrupted", "stale", "dead"]);
+
+export interface SteerToolDeps {
+	dispatch: DispatchContract;
+}
+
+function guide(deps: SteerToolDeps, runId: string, message: string): ToolResult {
+	if (message.length === 0) {
+		return { kind: "error", message: "steer: action=guide requires a non-empty message" };
+	}
+	try {
+		deps.dispatch.steer(runId, message);
+	} catch (err) {
+		return { kind: "error", message: err instanceof Error ? err.message : String(err) };
+	}
+	return {
+		kind: "ok",
+		output: `steer queued for run ${runId} (${message.length} chars); the worker sees it as a user message at its next turn boundary.`,
+		details: { action: "guide", runId, chars: message.length },
+	};
+}
+
+function cancel(deps: SteerToolDeps, runId: string): ToolResult {
+	const run = deps.dispatch.getRun(runId);
+	const rootRunId = run?.lineage?.rootRunId ?? runId;
+	const assignment = deps.dispatch.assignments?.getStored(rootRunId) ?? null;
+	if (!run && !assignment) return { kind: "error", message: `steer: unknown run or assignment '${runId}'` };
+	if (assignment?.status === "running") {
+		deps.dispatch.abort(rootRunId);
+		return {
+			kind: "ok",
+			output: `cancellation signalled for assignment ${rootRunId}; its current attempt will finalize and no future attempt will start.`,
+			details: { action: "cancel", runId: rootRunId, assignmentId: rootRunId },
+		};
+	}
+	if (!run || TERMINAL_STATUSES.has(run.status)) {
+		return {
+			kind: "error",
+			message: `steer: run or assignment '${runId}' already finished (state=${assignment?.status ?? run?.outcome ?? run?.status ?? "unknown"}); nothing to cancel`,
+		};
+	}
+	deps.dispatch.abort(runId);
+	return {
+		kind: "ok",
+		output: `cancellation signalled for run ${runId}; the run finalizes with outcome=canceled and its receipt records the cancellation.`,
+		details: { action: "cancel", runId },
+	};
+}
+
+export function createSteerTool(deps: SteerToolDeps): ToolSpec {
+	return {
+		name: ToolNames.Steer,
+		description:
+			"Control a running native worker whose run id is already available. Parent-model mid-run control requires detach:true because ordinary dispatch auto-waits and dispatch/steer are sequential; the interactive operator/TUI may steer an active synchronous native run through the dispatch contract. ACP runs have no input channel.",
+		parameters: Type.Object({
+			run_id: Type.String({ description: "Run id from dispatch output or monitor list." }),
+			action: stringEnum(["guide", "cancel"], "What to do."),
+			message: Type.Optional(Type.String({ description: "action=guide: the steering message." })),
+		}),
+		baseActionClass: "dispatch",
+		executionMode: "sequential",
+		async run(args): Promise<ToolResult> {
+			const runId = typeof args.run_id === "string" ? args.run_id.trim() : "";
+			if (runId.length === 0) return { kind: "error", message: "steer: missing run_id argument" };
+			const action = typeof args.action === "string" ? args.action : "";
+			if (action !== "guide" && action !== "cancel") {
+				return { kind: "error", message: `steer: action must be guide or cancel; got '${action}'` };
+			}
+			if (action === "guide") {
+				return guide(deps, runId, typeof args.message === "string" ? args.message.trim() : "");
+			}
+			return cancel(deps, runId);
+		},
+	};
+}

package/src/tools/string-enum.ts

@@ -0,0 +1,15 @@
+import { Type } from "typebox";
+
+/**
+ * Compact string-enum schema. TypeBox unions of literals serialize as a
+ * verbose `anyOf` of per-value `const` objects; the plain JSON Schema `enum`
+ * keyword carries the same constraint in a fraction of the schema tokens,
+ * which matters because every tool schema rides in the prompt prefix.
+ */
+export function stringEnum<T extends string>(values: ReadonlyArray<T>, description?: string) {
+	return Type.Unsafe<T>({
+		type: "string",
+		enum: [...values],
+		...(description !== undefined ? { description } : {}),
+	});
+}