@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/tools/gateway/data-surface.ts

@@ -0,0 +1,138 @@
+import { Type } from "typebox";
+import { ToolNames } from "../../core/tool-names.js";
+import { StringEnum } from "../../engine/ai.js";
+import { DATA_FORMATS } from "../data/shared.js";
+import type { ToolSurface } from "../lazy-tool.js";
+import { resolveToCwd } from "../path-utils.js";
+
+/**
+ * The `data` capability's immutable surface, kept apart from its streaming
+ * implementation so the registry can attach the schema and defer the readers
+ * until the first call.
+ */
+
+export const DATA_TOOL_NAME = ToolNames.Data;
+
+export const DATA_OPS = ["inspect", "select", "validate"] as const;
+export type DataOp = (typeof DATA_OPS)[number];
+
+const DESCRIPTION =
+	"Inspect, select, or validate a structured data file without loading it whole: CSV/TSV (delimiter and header detection, per-column types, sentinels such as NA counted, never converted), JSON (document shape, RFC 6901 pointer selection), and JSON Lines (record windows). op=inspect reports schema, dimensions, and a sample; op=select returns a bounded window of rows, records, or the value at a pointer; op=validate checks the whole file against its format. Every result carries view {exact, sampled, converted} and honest counts (rowCount null means the scan stopped early), and large integers or long floats are reported, never rounded. Refuses invalid UTF-8, binary, and unsupported formats (HDF5, NetCDF, Parquet: use run_script with a library) with an actionable reason.";
+
+function numberArg(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim().length > 0) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+export function headerArg(value: unknown): "auto" | boolean | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value === "boolean") return value;
+	if (value === "auto") return "auto";
+	if (value === "true") return true;
+	if (value === "false") return false;
+	return undefined;
+}
+
+function columnsArg(value: unknown): Array<string | number> | undefined {
+	if (typeof value === "string") {
+		const parts = value
+			.split(",")
+			.map((part) => part.trim())
+			.filter((part) => part.length > 0);
+		return parts.length > 0 ? parts : undefined;
+	}
+	if (!Array.isArray(value)) return undefined;
+	const out: Array<string | number> = [];
+	for (const entry of value) {
+		if (typeof entry === "string" || (typeof entry === "number" && Number.isFinite(entry))) out.push(entry);
+	}
+	return out.length > 0 ? out : undefined;
+}
+
+/**
+ * Accept the weak-model argument shapes without teaching every reader about
+ * them: numbers as strings, `columns` as a comma-separated string, `header`
+ * as "true"/"false", and `file`/`file_path` for `path`.
+ */
+export function prepareDataArguments(args: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = { ...args };
+	if (typeof out.path !== "string") {
+		const alias = out.file ?? out.file_path ?? out.filePath;
+		if (typeof alias === "string") out.path = alias;
+	}
+	if (typeof out.path === "string") out.path = out.path.trim();
+	for (const key of ["sample_rows", "offset", "limit"] as const) {
+		const parsed = numberArg(out[key]);
+		if (parsed !== undefined) out[key] = parsed;
+		else if (out[key] !== undefined) delete out[key];
+	}
+	if (out.max_rows !== undefined && out.max_rows !== null) {
+		const parsed = numberArg(out.max_rows);
+		if (parsed !== undefined) out.max_rows = parsed;
+		else delete out.max_rows;
+	}
+	const header = headerArg(out.header);
+	if (header !== undefined) out.header = header;
+	else if (out.header !== undefined) delete out.header;
+	const columns = columnsArg(out.columns);
+	if (columns !== undefined) out.columns = columns;
+	else if (out.columns !== undefined) delete out.columns;
+	return out;
+}
+
+/** Freeze the reader's normalized target before path policy admission. */
+export function prepareDataAdmissionArguments(
+	args: Record<string, unknown>,
+	cwd = process.cwd(),
+): Record<string, unknown> {
+	const prepared = prepareDataArguments(args);
+	if (typeof prepared.path === "string" && prepared.path.length > 0) prepared.path = resolveToCwd(prepared.path, cwd);
+	return prepared;
+}
+
+export const dataToolSurface = {
+	name: DATA_TOOL_NAME,
+	description: DESCRIPTION,
+	parameters: Type.Object({
+		op: StringEnum(DATA_OPS, { description: "inspect, select, or validate." }),
+		path: Type.String({ description: "Data file, relative to the workspace root or absolute." }),
+		format: Type.Optional(
+			StringEnum(DATA_FORMATS, {
+				description: "Format when the extension or content does not say: csv, tsv, json, jsonl.",
+			}),
+		),
+		delimiter: Type.Optional(Type.String({ description: "CSV/TSV: one delimiter character (or \\t)." })),
+		header: Type.Optional(
+			Type.Union([Type.Boolean(), Type.Literal("auto")], {
+				description: 'CSV/TSV: "auto" (default) detects a header row; true or false forces it.',
+			}),
+		),
+		sample_rows: Type.Optional(
+			Type.Number({ description: "inspect: rows or top-level members kept as the sample (default 10, max 1000)." }),
+		),
+		max_rows: Type.Optional(
+			Type.Union([Type.Number(), Type.Null()], {
+				description:
+					"inspect and validate: rows scanned before the view becomes sampled or the verdict partial (default 100000; null scans the whole file).",
+			}),
+		),
+		offset: Type.Optional(Type.Number({ description: "select: 0-based first row, record, or array element." })),
+		limit: Type.Optional(Type.Number({ description: "select: rows returned (default 50, max 1000)." })),
+		columns: Type.Optional(
+			Type.Array(Type.Union([Type.String(), Type.Number()]), {
+				description: "select, CSV/TSV: header names or 0-based indices to project.",
+			}),
+		),
+		pointer: Type.Optional(
+			Type.String({ description: 'select, JSON: RFC 6901 pointer to the value to return; "" is the whole document.' }),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+	prepareArguments: prepareDataArguments,
+	prepareAdmissionArguments: prepareDataAdmissionArguments,
+} satisfies ToolSurface;

package/src/tools/gateway/data-tool.ts

@@ -0,0 +1,201 @@
+import path from "node:path";
+import {
+	type DataRefusal,
+	type InspectDataOptions,
+	type InspectDataResult,
+	inspectData,
+	isDataRefusal,
+	type SelectDataOptions,
+	type SelectDataResult,
+	selectData,
+	type ValidateDataOptions,
+	type ValidateDataResult,
+	validateData,
+} from "../data/index.js";
+import {
+	commitObservationReservation,
+	finalizeObservation,
+	type ObservationUnit,
+	observationBudgetExhausted,
+	releaseObservation,
+	reserveObservation,
+} from "../observation.js";
+import { resolveToCwd } from "../path-utils.js";
+import type { ToolInvokeOptions, ToolResult, ToolSpec } from "../registry.js";
+import { DATA_OBSERVATION_SELF_CAP_BYTES } from "./caps.js";
+import {
+	DATA_OPS,
+	DATA_TOOL_NAME,
+	type DataOp,
+	dataToolSurface,
+	headerArg,
+	prepareDataAdmissionArguments,
+	prepareDataArguments,
+} from "./data-surface.js";
+
+export { DATA_OBSERVATION_SELF_CAP_BYTES } from "./caps.js";
+export { DATA_TOOL_NAME, dataToolSurface, prepareDataArguments } from "./data-surface.js";
+
+/**
+ * The `data` capability: structured-data inspection, selection, and
+ * validation over CSV/TSV, JSON, and JSON Lines through the streaming readers
+ * in src/tools/data. This module owns only the tool contract: argument
+ * normalization, path resolution against the workspace, the observation
+ * envelope for large results, and the mapping of a typed refusal to a tool
+ * error. Every scientific-integrity rule (exact versus sampled views, large
+ * integers reported rather than rounded, sentinels counted rather than
+ * converted) lives in the readers and is reported verbatim.
+ */
+
+export interface DataToolDeps {
+	getCwd?: () => string;
+}
+
+interface CountedResult {
+	unit: ObservationUnit;
+	shownCount: number;
+	totalCount: number | null;
+	truncated: boolean;
+	next?: string;
+}
+
+type DataResult = InspectDataResult | SelectDataResult | ValidateDataResult;
+
+function isDataOp(value: string): value is DataOp {
+	return (DATA_OPS as ReadonlyArray<string>).includes(value);
+}
+
+/** Honest envelope counts read off the reader's own result; the readers never guess. */
+function countResult(op: DataOp, payload: DataResult): CountedResult {
+	if (op === "select") {
+		const result = payload as unknown as Record<string, unknown>;
+		const rows = result.rows ?? result.records ?? result.elements;
+		const returned = typeof result.returned === "number" ? result.returned : Array.isArray(rows) ? rows.length : 1;
+		const offset = typeof result.offset === "number" ? result.offset : 0;
+		const limit = typeof result.limit === "number" ? result.limit : returned;
+		const hasMore = result.hasMore === true;
+		const total = typeof result.total === "number" ? result.total : hasMore ? null : offset + returned;
+		return {
+			unit: "entries",
+			shownCount: returned,
+			totalCount: total,
+			truncated: hasMore,
+			...(hasMore ? { next: `offset=${offset + limit}` } : {}),
+		};
+	}
+	return { unit: "results", shownCount: 1, totalCount: 1, truncated: false };
+}
+
+/**
+ * One word for the reader's view flags, so a transcript row never calls a
+ * budget cut a sample: all three flags false means a value was cut to the
+ * capture budget, which is neither a sampled scan nor a converted one.
+ */
+function describeDataView(view: unknown): string {
+	const flags = typeof view === "object" && view !== null ? (view as Record<string, unknown>) : {};
+	if (flags.exact === true) return "exact";
+	const parts = [...(flags.sampled === true ? ["sampled"] : []), ...(flags.converted === true ? ["converted"] : [])];
+	return parts.length > 0 ? parts.join(", ") : "value cut to budget";
+}
+
+function refusalResult(op: DataOp, refusal: DataRefusal): ToolResult {
+	return {
+		kind: "error",
+		message: `data: ${op} refused (${refusal.reason}): ${refusal.message}`,
+		details: { refusal },
+	};
+}
+
+export function createDataTool(deps: DataToolDeps = {}): ToolSpec {
+	const getCwd = deps.getCwd ?? (() => process.cwd());
+	return {
+		...dataToolSurface,
+		prepareAdmissionArguments: (args) => prepareDataAdmissionArguments(args, getCwd()),
+		async run(rawArgs, options?: ToolInvokeOptions): Promise<ToolResult> {
+			const args = prepareDataArguments(rawArgs);
+			const op = typeof args.op === "string" ? args.op : "";
+			if (!isDataOp(op)) {
+				return { kind: "error", message: `data: op must be inspect, select, or validate; got '${op}'` };
+			}
+			if (typeof args.path !== "string" || args.path.trim().length === 0) {
+				return { kind: "error", message: "data: path is required" };
+			}
+			const target = resolveToCwd(args.path.trim(), getCwd());
+			const reservation = reserveObservation(DATA_OBSERVATION_SELF_CAP_BYTES, options);
+			if (reservation.exhausted) {
+				return observationBudgetExhausted({
+					tool: DATA_TOOL_NAME,
+					unit: op === "select" ? "entries" : "results",
+					reservation,
+					subject: `${op} ${path.relative(getCwd(), target) || target}`,
+					hint: "Continue in a follow-up turn.",
+				});
+			}
+			// The readers stream and await between reserve and finalize, so the
+			// cap is charged up front and reconciled when the result settles.
+			commitObservationReservation(reservation);
+			try {
+				const format = typeof args.format === "string" ? args.format : undefined;
+				const delimiter = typeof args.delimiter === "string" ? args.delimiter : undefined;
+				const header = headerArg(args.header);
+				const signal = options?.signal;
+				let result: DataResult | DataRefusal;
+				if (op === "inspect") {
+					const inspectOptions: InspectDataOptions = {
+						...(format !== undefined ? { format } : {}),
+						...(delimiter !== undefined ? { delimiter } : {}),
+						...(header !== undefined ? { header } : {}),
+						...(typeof args.sample_rows === "number" ? { sampleRows: args.sample_rows } : {}),
+						...(args.max_rows === null || typeof args.max_rows === "number" ? { maxRows: args.max_rows } : {}),
+						signal,
+					};
+					result = await inspectData(target, inspectOptions);
+				} else if (op === "select") {
+					const selectOptions: SelectDataOptions = {
+						...(format !== undefined ? { format } : {}),
+						...(delimiter !== undefined ? { delimiter } : {}),
+						...(header !== undefined ? { header } : {}),
+						...(typeof args.offset === "number" ? { offset: args.offset } : {}),
+						...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+						...(Array.isArray(args.columns) ? { columns: args.columns as Array<string | number> } : {}),
+						...(typeof args.pointer === "string" ? { pointer: args.pointer } : {}),
+						signal,
+					};
+					result = await selectData(target, selectOptions);
+				} else {
+					const validateOptions: ValidateDataOptions = {
+						...(format !== undefined ? { format } : {}),
+						...(delimiter !== undefined ? { delimiter } : {}),
+						...(header !== undefined ? { header } : {}),
+						...(args.max_rows === null || typeof args.max_rows === "number" ? { maxRows: args.max_rows } : {}),
+						signal,
+					};
+					result = await validateData(target, validateOptions);
+				}
+				if (isDataRefusal(result)) {
+					releaseObservation(reservation);
+					return refusalResult(op, result);
+				}
+				const counted = countResult(op, result);
+				return finalizeObservation({
+					tool: DATA_TOOL_NAME,
+					unit: counted.unit,
+					format: "json",
+					output: JSON.stringify(result),
+					shownCount: counted.shownCount,
+					totalCount: counted.totalCount,
+					truncated: counted.truncated,
+					...(counted.next !== undefined ? { next: counted.next } : {}),
+					details: { op, path: target, format: result.format, view: result.view, viewLabel: describeDataView(result.view) },
+					reservation,
+					...(options ? { options } : {}),
+				});
+			} catch (error) {
+				releaseObservation(reservation);
+				return { kind: "error", message: `data: ${error instanceof Error ? error.message : String(error)}` };
+			}
+		},
+	};
+}
+
+export const dataTool: ToolSpec = createDataTool();

package/src/tools/gateway/index.ts

@@ -0,0 +1,342 @@
+import { Type } from "typebox";
+import { isMcpToolName, type ToolName, ToolNames } from "../../core/tool-names.js";
+import type { ActionClass } from "../../domains/safety/action-classifier.js";
+import { StringEnum, validateEngineToolArguments } from "../../engine/ai.js";
+import { wireParameterSchema } from "../agent-tools.js";
+import type { ToolSurface } from "../lazy-tool.js";
+import {
+	commitObservationReservation,
+	finalizeObservation,
+	observationBudgetExhausted,
+	releaseObservation,
+	reserveObservation,
+} from "../observation.js";
+import {
+	nestedBlockedResult,
+	nestedExecutedResult,
+	type ToolInvokeOptions,
+	type ToolRegistry,
+	type ToolResult,
+	type ToolSpec,
+} from "../registry.js";
+import { type GatewayCapabilityKind, gatewayCapabilityKind, toolSpecPlacement } from "../surface.js";
+import { GATEWAY_FIND_SELF_CAP_BYTES } from "./caps.js";
+import type { McpCapabilitySource, McpServerListing } from "./mcp-capabilities.js";
+
+export { GATEWAY_FIND_SELF_CAP_BYTES } from "./caps.js";
+export {
+	createMcpCapabilitySource,
+	type McpCapabilitySource,
+	type McpCapabilitySourceOptions,
+	type McpCloseReport,
+	type McpListing,
+	type McpServerListing,
+	type McpTeardownReport,
+	mcpTrustRemedy,
+} from "./mcp-capabilities.js";
+
+/**
+ * The gateway: one stable find/describe/call schema through which the model
+ * reaches every secondary capability. A call is not a new authority path: the
+ * gateway resolves the capability and invokes it through the registry under
+ * the capability's own name, so the safety net, the skill surface, the
+ * autonomy mapping, parking for approval, before/after hooks, result shaping,
+ * and the audit row all happen exactly as for a direct call. The result is
+ * the capability's result with `details.capability` stamped on it, and a
+ * refused capability refuses the gateway call with the same verdict.
+ */
+
+export const GATEWAY_OPS = ["find", "describe", "call"] as const;
+export type GatewayOp = (typeof GATEWAY_OPS)[number];
+
+/** Entries a find listing returns before it says `truncated` and asks for a narrower query. */
+export const GATEWAY_FIND_MAX_ENTRIES = 300;
+
+export interface GatewayCapabilityEntry {
+	name: string;
+	kind: GatewayCapabilityKind;
+	/** The first sentence of the capability's description. */
+	description: string;
+	actionClass: ActionClass;
+}
+
+export interface GatewayToolDeps {
+	registry: ToolRegistry;
+	/** Local MCP servers, present on the session registry only. */
+	mcp?: McpCapabilitySource;
+}
+
+const DESCRIPTION =
+	'Reach secondary capabilities on demand. op="find" lists them as JSON {name, kind: builtin|extension|mcp, description, actionClass} (query filters by name or description); op="describe" returns one capability\'s full description, JSON parameter schema, and authority notes; op="call" runs one with args under the same admission as a direct tool: its own action class, approval, and evidence apply and the result is the capability\'s result. Capabilities: artifact (terminal plan/review/report documents), web_read (GET-only web reading), web_fetch (full HTTP requests), git (read-only status/diff/log), evidence, credential_present, clio_docs, clio_library, data (CSV/TSV, JSON, JSONL inspection), installed extension commands, and trusted local MCP servers.';
+
+export const gatewayToolSurface = {
+	name: ToolNames.Gateway,
+	description: DESCRIPTION,
+	parameters: Type.Object({
+		op: StringEnum(GATEWAY_OPS, { description: "find, describe, or call." }),
+		capability: Type.Optional(Type.String({ description: "describe and call: the capability name from find." })),
+		query: Type.Optional(Type.String({ description: "find: case-insensitive filter over names and descriptions." })),
+		args: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description: "call: the capability's arguments, matching its describe schema.",
+			}),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "sequential",
+} satisfies ToolSurface;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Accept the weak-model shapes: `args` as a JSON string, `name`/`tool` for
+ * `capability`, and a missing `op` inferred from what else was given.
+ */
+function prepareGatewayArguments(args: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = { ...args };
+	if (typeof out.capability !== "string") {
+		const alias = out.name ?? out.tool;
+		if (typeof alias === "string") out.capability = alias;
+	}
+	if (typeof out.args === "string") {
+		try {
+			const parsed: unknown = JSON.parse(out.args);
+			if (isRecord(parsed)) out.args = parsed;
+		} catch {
+			// The body reports the unparseable string.
+		}
+	}
+	if (typeof out.op !== "string") {
+		if (typeof out.capability === "string" && out.args !== undefined) out.op = "call";
+		else if (typeof out.capability === "string") out.op = "describe";
+		else out.op = "find";
+	}
+	return out;
+}
+
+function firstSentence(text: string): string {
+	const line = text.split("\n")[0]?.trim() ?? "";
+	const match = /^(.*?[.!?])(?:\s|$)/u.exec(line);
+	return (match?.[1] ?? line).slice(0, 240);
+}
+
+function autonomyNote(actionClass: ActionClass): string {
+	switch (actionClass) {
+		case "read":
+			return "Read class: runs at every autonomy level.";
+		case "write":
+			return "Write class: parks for operator approval at suggest, runs at auto-edit and full-auto, and is denied at read-only.";
+		case "execute":
+			return "Execute class: an unrecognized command asks at auto-edit, runs at full-auto, and is denied at read-only.";
+		case "dispatch":
+			return "Dispatch class: plan-scale calls ask below full-auto; denied at read-only.";
+		case "unknown":
+			return "No action class was declared: every call asks for approval and read-only denies it.";
+		default:
+			return `Action class ${actionClass}.`;
+	}
+}
+
+export function createGatewayTool(deps: GatewayToolDeps): ToolSpec {
+	const { registry } = deps;
+
+	const allowedSet = (options: ToolInvokeOptions | undefined): ReadonlySet<string> | null =>
+		options?.allowedTools ? new Set<string>(options.allowedTools) : null;
+
+	const resolveCapability = async (
+		name: string,
+		options: ToolInvokeOptions | undefined,
+	): Promise<{ spec: ToolSpec } | { spec: null; message: string }> => {
+		let spec = registry.get(name as ToolName);
+		if (spec === undefined && isMcpToolName(name) && deps.mcp) {
+			const ensured = await deps.mcp.ensure(name, options?.signal ? { signal: options.signal } : {});
+			if (ensured.spec === null)
+				return { spec: null, message: `gateway: ${ensured.reason ?? `unknown capability ${name}`}` };
+			spec = ensured.spec;
+		}
+		if (spec === undefined) {
+			return {
+				spec: null,
+				message: `gateway: unknown capability "${name}"; run gateway(op="find") to list the capabilities this session offers`,
+			};
+		}
+		if (toolSpecPlacement(spec) === "direct") {
+			return {
+				spec: null,
+				message: `gateway: "${name}" is a direct tool with an attached schema; call it directly, not through the gateway`,
+			};
+		}
+		return { spec };
+	};
+
+	const outsideSurface = (name: string, allowed: ReadonlySet<string>): ToolResult => ({
+		kind: "error",
+		message: `gateway: capability "${name}" is not on this run's admitted tool surface (${[...allowed].sort().join(", ")}); the recipe did not declare it, so the gateway refuses to call it`,
+	});
+
+	const runFind = async (args: Record<string, unknown>, options: ToolInvokeOptions | undefined): Promise<ToolResult> => {
+		const query = typeof args.query === "string" ? args.query.trim().toLowerCase() : "";
+		const allowed = allowedSet(options);
+		const reservation = reserveObservation(GATEWAY_FIND_SELF_CAP_BYTES, options);
+		if (reservation.exhausted) {
+			return observationBudgetExhausted({
+				tool: ToolNames.Gateway,
+				unit: "entries",
+				reservation,
+				subject: query.length > 0 ? `find query=${query}` : "find",
+				hint: "Continue in a follow-up turn.",
+			});
+		}
+		commitObservationReservation(reservation);
+		try {
+			// Trusted MCP servers connect here, lazily, and register their tools
+			// before the registry listing below is taken. Untrusted and stale
+			// servers are described with their remedy and never launched.
+			let servers: McpServerListing[] = [];
+			let diagnostics: string[] = [];
+			if (deps.mcp && allowed === null) {
+				const listing = await deps.mcp.list(options?.signal ? { signal: options.signal } : {});
+				servers = listing.servers;
+				diagnostics = listing.diagnostics;
+			}
+			const entries: GatewayCapabilityEntry[] = registry
+				.listGateway()
+				.filter((spec) => allowed === null || allowed.has(spec.name))
+				.map((spec) => ({
+					name: spec.name,
+					kind: gatewayCapabilityKind(spec.name),
+					description: firstSentence(spec.description),
+					actionClass: spec.baseActionClass,
+				}))
+				.filter(
+					(entry) =>
+						query.length === 0 || entry.name.toLowerCase().includes(query) || entry.description.toLowerCase().includes(query),
+				)
+				.sort((left, right) => left.name.localeCompare(right.name));
+			const total = entries.length;
+			const shown = entries.slice(0, GATEWAY_FIND_MAX_ENTRIES);
+			const truncated = shown.length < total;
+			const payload = {
+				capabilities: shown,
+				count: shown.length,
+				total,
+				...(servers.length > 0 ? { servers } : {}),
+				...(diagnostics.length > 0 ? { diagnostics } : {}),
+				...(truncated ? { note: "listing truncated; narrow it with query" } : {}),
+			};
+			return finalizeObservation({
+				tool: ToolNames.Gateway,
+				unit: "entries",
+				format: "json",
+				output: JSON.stringify(payload),
+				shownCount: shown.length,
+				totalCount: total,
+				truncated,
+				...(truncated ? { next: "query=<narrower terms>" } : {}),
+				details: { op: "find", count: shown.length, total, servers: servers.length },
+				reservation,
+				...(options ? { options } : {}),
+			});
+		} catch (error) {
+			releaseObservation(reservation);
+			return { kind: "error", message: `gateway: find failed: ${error instanceof Error ? error.message : String(error)}` };
+		}
+	};
+
+	const runDescribe = async (
+		args: Record<string, unknown>,
+		options: ToolInvokeOptions | undefined,
+	): Promise<ToolResult> => {
+		const name = typeof args.capability === "string" ? args.capability.trim() : "";
+		if (name.length === 0) return { kind: "error", message: 'gateway: op="describe" requires capability' };
+		const allowed = allowedSet(options);
+		if (allowed !== null && !allowed.has(name)) return outsideSurface(name, allowed);
+		const resolved = await resolveCapability(name, options);
+		if (resolved.spec === null) return { kind: "error", message: resolved.message };
+		const spec = resolved.spec;
+		const kind = gatewayCapabilityKind(spec.name);
+		const authority = [
+			`Runs through the same admission as a direct call, under its own name and action class (${spec.baseActionClass}); the approval overlay, audit row, and ledger record name ${spec.name}, not the gateway.`,
+			autonomyNote(spec.baseActionClass),
+		];
+		if (spec.name === ToolNames.WebFetch) {
+			authority.push(
+				"A non-GET method or a body is an outward action and asks at suggest and auto-edit; use web_read when a plain GET is enough.",
+			);
+		}
+		if (spec.name === ToolNames.Artifact) {
+			authority.push("Terminal: writing the artifact completes the turn, so close the task board before calling it.");
+		}
+		if (kind === "extension") {
+			authority.push(
+				`Harness extension${spec.sourceInfo?.extension ? ` ${spec.sourceInfo.extension.contentDigest.slice(0, 12)}` : ""}: an installed command run with JSON input on the workspace; its argv is classified like a bash command, and running it does not sandbox it.`,
+			);
+		}
+		const mcpNote = kind === "mcp" ? deps.mcp?.authorityNote(spec.name) : null;
+		if (mcpNote) authority.push(mcpNote);
+		const payload = {
+			name: spec.name,
+			kind,
+			description: spec.description,
+			parameters: wireParameterSchema(spec.parameters),
+			actionClass: spec.baseActionClass,
+			executionMode: spec.executionMode ?? "sequential",
+			authority,
+		};
+		return { kind: "ok", output: JSON.stringify(payload), details: { op: "describe", described: spec.name } };
+	};
+
+	const runCall = async (args: Record<string, unknown>, options: ToolInvokeOptions | undefined): Promise<ToolResult> => {
+		const name = typeof args.capability === "string" ? args.capability.trim() : "";
+		if (name.length === 0) return { kind: "error", message: 'gateway: op="call" requires capability' };
+		const allowed = allowedSet(options);
+		if (allowed !== null && !allowed.has(name)) return outsideSurface(name, allowed);
+		const resolved = await resolveCapability(name, options);
+		if (resolved.spec === null) return { kind: "error", message: resolved.message };
+		const spec = resolved.spec;
+		if (args.args !== undefined && !isRecord(args.args)) {
+			return { kind: "error", message: `gateway: args for ${spec.name} must be a JSON object` };
+		}
+		const rawArgs: Record<string, unknown> = isRecord(args.args) ? args.args : {};
+		// The same coercion pi-ai applies to a direct call's arguments before
+		// execute, so "5" reaches a number field as 5 either way.
+		let validated: Record<string, unknown>;
+		try {
+			validated = validateEngineToolArguments(
+				{ name: spec.name, description: spec.description, parameters: spec.parameters },
+				{ type: "toolCall", id: options?.toolCallId ?? "", name: spec.name, arguments: rawArgs },
+			) as Record<string, unknown>;
+		} catch (error) {
+			return {
+				kind: "error",
+				message: `gateway: ${spec.name} arguments rejected: ${error instanceof Error ? error.message : String(error)}. Use gateway(op="describe", capability="${spec.name}") for the schema.`,
+			};
+		}
+		// The nested call keeps the outer options (signal, ids, skill policy,
+		// progress, park accounting) minus any one-shot approval, which was
+		// granted to the gateway call and must not travel to the capability.
+		const { approval: _approval, ...outer } = options ?? {};
+		const verdict = await registry.invoke({ tool: spec.name, args: validated }, { ...outer, nested: true });
+		if (verdict.kind === "not_visible") return { kind: "error", message: `gateway: ${verdict.reason}` };
+		if (verdict.kind === "blocked") return nestedBlockedResult(verdict);
+		return nestedExecutedResult(
+			{ ...verdict.result, details: { ...verdict.result.details, capability: spec.name } },
+			verdict.decision,
+		);
+	};
+
+	return {
+		...gatewayToolSurface,
+		prepareArguments: prepareGatewayArguments,
+		async run(rawArgs, options): Promise<ToolResult> {
+			const args = prepareGatewayArguments(rawArgs);
+			const op = typeof args.op === "string" ? args.op : "";
+			if (op === "find") return runFind(args, options);
+			if (op === "describe") return runDescribe(args, options);
+			if (op === "call") return runCall(args, options);
+			return { kind: "error", message: `gateway: op must be find, describe, or call; got '${op}'` };
+		},
+	};
+}