@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/tools/policy.ts

@@ -0,0 +1,154 @@
+import { type BuiltinToolName, isBuiltinToolName, type ToolName, ToolNames } from "../core/tool-names.js";
+import { type ActionClass, classify } from "../domains/safety/action-classifier.js";
+import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { readMaxBytes } from "./read.js";
+import type { ToolExecutionMode, ToolSpec } from "./registry.js";
+
+/**
+ * Surface invariants for the builtin toolkit. Asserted once at bootstrap so
+ * drift between the plane design, the classifier, the metadata table, and the
+ * registered specs fails loudly instead of shipping a surface that behaves
+ * differently from what the policy engine assumes.
+ */
+
+export type ToolPlane = "observe" | "mutate" | "execute" | "orchestrate" | "retrieve" | "interact" | "artifact";
+
+interface PlaneExpectation {
+	plane: ToolPlane;
+	actionClass: ActionClass;
+	executionMode: ToolExecutionMode;
+}
+
+/** One row per registered tool: plane, action class, and concurrency rule. */
+export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> = {
+	[ToolNames.Read]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Grep]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Ls]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.CodeNav]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Context]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.CredentialPresent]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Write]: { plane: "mutate", actionClass: "write", executionMode: "sequential" },
+	[ToolNames.Edit]: { plane: "mutate", actionClass: "write", executionMode: "sequential" },
+	[ToolNames.Bash]: { plane: "execute", actionClass: "execute", executionMode: "sequential" },
+	// git is read-only inspection on the safe-exec spine: EXECUTE plane for
+	// its containment posture, read class for its safety disposition.
+	[ToolNames.Git]: { plane: "execute", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Verify]: { plane: "execute", actionClass: "execute", executionMode: "sequential" },
+	[ToolNames.Dispatch]: { plane: "orchestrate", actionClass: "dispatch", executionMode: "sequential" },
+	// monitor never mutates a run, so it stays read class and parallel.
+	[ToolNames.Monitor]: { plane: "orchestrate", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.Steer]: { plane: "orchestrate", actionClass: "dispatch", executionMode: "sequential" },
+	// tasks orchestrates the agent's own work rather than workers: read class
+	// (session-ledger bookkeeping, no workspace mutation), sequential so two
+	// board mutations in one batch never interleave.
+	[ToolNames.Tasks]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	// ledger reads a local mirror and posts over the one-way control lane, so it
+	// mutates no workspace and stays read class. Reviewers and judges run pinned
+	// to read-only autonomy, and a write class there would block exactly the peer
+	// review the board depends on. Sequential so two posts in one batch do not
+	// interleave against the local post cap.
+	[ToolNames.Ledger]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	[ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
+	[ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" },
+};
+
+/**
+ * OBSERVE envelope members and their self-caps. The registry policy cap must
+ * sit at or above self cap + slack so the envelope's own notice line survives
+ * the backstop. credential_present sits in the OBSERVE plane but returns a
+ * typed boolean, so it carries no envelope cap.
+ */
+const OBSERVE_ENVELOPE_SELF_CAPS: ReadonlyArray<[BuiltinToolName, () => number]> = [
+	[ToolNames.Read, () => readMaxBytes()],
+	[ToolNames.Grep, () => OBSERVE_SELF_CAPS.grepContent],
+	[ToolNames.Find, () => OBSERVE_SELF_CAPS.find],
+	[ToolNames.Ls, () => OBSERVE_SELF_CAPS.ls],
+	[ToolNames.CodeNav, () => OBSERVE_SELF_CAPS.codeNav],
+	[
+		ToolNames.Context,
+		() => Math.max(OBSERVE_SELF_CAPS.contextDocs, OBSERVE_SELF_CAPS.contextSkills, OBSERVE_SELF_CAPS.contextWorkspace),
+	],
+];
+
+const SESSION_BOUND_TOOLS = new Set<ToolName>([]);
+const DISPATCH_BOUND_TOOLS = new Set<ToolName>([ToolNames.Dispatch, ToolNames.Monitor, ToolNames.Steer]);
+const INTERACTIVE_BOUND_TOOLS = new Set<ToolName>([ToolNames.AskUser]);
+/** The RETRIEVE plane, omitted wholesale by a hermetic run (tools/network-policy.ts). */
+const NETWORK_BOUND_TOOLS = new Set<ToolName>([ToolNames.WebFetch]);
+
+export interface BuiltinToolPolicyOptions {
+	includeSessionTools?: boolean;
+	includeDispatchTools?: boolean;
+	includeInteractiveTools?: boolean;
+	/**
+	 * Unlike the other three, this defaults to true: every registry registers
+	 * the network plane unless a run explicitly asked to be hermetic, so an
+	 * unset option must keep demanding it.
+	 */
+	includeNetworkTools?: boolean;
+}
+
+function validateBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: BuiltinToolPolicyOptions = {}): string[] {
+	const errors: string[] = [];
+	const registered = new Map<ToolName, ToolSpec>();
+
+	for (const spec of specs) {
+		if (!isBuiltinToolName(spec.name)) {
+			errors.push(`registered tool ${spec.name} is not in ToolNames`);
+			continue;
+		}
+		registered.set(spec.name, spec);
+
+		const expectation = TOOL_PLANES[spec.name];
+		const classified = classify({ tool: spec.name }).actionClass;
+		if (classified !== spec.baseActionClass) {
+			errors.push(`tool ${spec.name} baseActionClass=${spec.baseActionClass} but classifier returns ${classified}`);
+		}
+		if (spec.baseActionClass !== expectation.actionClass) {
+			errors.push(
+				`tool ${spec.name} baseActionClass=${spec.baseActionClass} but plane ${expectation.plane} expects ${expectation.actionClass}`,
+			);
+		}
+		if (spec.executionMode !== expectation.executionMode) {
+			errors.push(
+				`tool ${spec.name} executionMode=${spec.executionMode ?? "unset"} but plane ${expectation.plane} expects ${expectation.executionMode}`,
+			);
+		}
+	}
+
+	// Envelope caps: the registry backstop must never cut an envelope notice.
+	for (const [tool, selfCap] of OBSERVE_ENVELOPE_SELF_CAPS) {
+		const spec = registered.get(tool);
+		if (!spec) continue;
+		const policyCap = spec.metadata?.resultSizePolicy?.maxBytes ?? 0;
+		const required = selfCap() + OBSERVATION_POLICY_SLACK_BYTES;
+		if (policyCap < required) {
+			errors.push(`tool ${tool} policy cap ${policyCap}B sits below self cap + slack (${required}B)`);
+		}
+	}
+
+	const includeSessionTools = options.includeSessionTools ?? false;
+	const includeDispatchTools = options.includeDispatchTools ?? false;
+	const includeInteractiveTools = options.includeInteractiveTools ?? false;
+	const includeNetworkTools = options.includeNetworkTools ?? true;
+	const required = new Set<ToolName>(Object.values(ToolNames));
+	for (const tool of [...required]) {
+		if (!includeSessionTools && SESSION_BOUND_TOOLS.has(tool)) required.delete(tool);
+		if (!includeDispatchTools && DISPATCH_BOUND_TOOLS.has(tool)) required.delete(tool);
+		if (!includeInteractiveTools && INTERACTIVE_BOUND_TOOLS.has(tool)) required.delete(tool);
+		if (!includeNetworkTools && NETWORK_BOUND_TOOLS.has(tool)) required.delete(tool);
+	}
+	for (const tool of required) {
+		if (!registered.has(tool)) errors.push(`builtin tool ${tool} is not registered`);
+	}
+
+	return errors;
+}
+
+export function assertBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: BuiltinToolPolicyOptions = {}): void {
+	const errors = validateBuiltinToolPolicy(specs, options);
+	if (errors.length === 0) return;
+	throw new Error(`tool policy drift:\n${errors.map((line) => `- ${line}`).join("\n")}`);
+}

package/src/tools/profiles.ts

@@ -0,0 +1,108 @@
+import { type BuiltinToolName, isBuiltinToolName, type ToolName, ToolNames } from "../core/tool-names.js";
+
+export type ToolProfileName = "minimal-local" | "science-local" | "full-agent";
+
+export const TOOL_PROFILE_NAMES: ReadonlyArray<ToolProfileName> = ["minimal-local", "science-local", "full-agent"];
+const CODEWIKI_TOOL_NAMES: ReadonlyArray<BuiltinToolName> = [ToolNames.CodeNav];
+
+export interface ToolProfileContext {
+	agentId?: string;
+	task?: string;
+}
+
+const MINIMAL_LOCAL_TOOLS: ReadonlyArray<BuiltinToolName> = [
+	ToolNames.Read,
+	ToolNames.Grep,
+	ToolNames.Find,
+	ToolNames.Ls,
+	ToolNames.Git,
+	ToolNames.Context,
+	ToolNames.CodeNav,
+	// A narrowed read-only scout swarm is the surface that most needs to see
+	// what its peers already staked.
+	ToolNames.Ledger,
+];
+
+const SCIENCE_LOCAL_TOOLS: ReadonlyArray<BuiltinToolName> = [...MINIMAL_LOCAL_TOOLS, ToolNames.Verify];
+
+const NARROW_TOOL_PROFILES: Readonly<Record<Exclude<ToolProfileName, "full-agent">, ReadonlySet<BuiltinToolName>>> = {
+	"minimal-local": new Set(MINIMAL_LOCAL_TOOLS),
+	"science-local": new Set(SCIENCE_LOCAL_TOOLS),
+};
+
+export function isToolProfileName(value: string): value is ToolProfileName {
+	return (TOOL_PROFILE_NAMES as ReadonlyArray<string>).includes(value);
+}
+
+/**
+ * True when the profile narrows the builtin tool surface below the recipe's
+ * declared set. Black-box external CLI runtimes that cannot mediate per-tool
+ * calls use this to refuse a profile they would otherwise silently ignore.
+ * `full-agent` and `undefined` impose no narrowing.
+ */
+function narrowsToolSurface(profile: ToolProfileName | undefined): boolean {
+	return profile !== undefined && profile in NARROW_TOOL_PROFILES;
+}
+
+/**
+ * Fail closed when a narrowing profile is requested on a runtime that cannot
+ * enforce it. Black-box external CLIs run their own tool surface and never see
+ * Clio's per-tool mediation, so honoring a narrowing profile is impossible;
+ * refusing is safer than running the full surface under a profile that promised
+ * to restrict it.
+ */
+export function assertToolProfileEnforceable(profile: ToolProfileName | undefined, runtimeLabel: string): void {
+	if (narrowsToolSurface(profile)) {
+		throw new Error(
+			`${runtimeLabel} runtime cannot enforce tool_profile '${profile}': it runs its own tool surface without Clio per-tool mediation. Dispatch to a native or claude-sdk worker, or use tool_profile full-agent.`,
+		);
+	}
+}
+
+export function applyToolProfile(
+	tools: ReadonlyArray<ToolName>,
+	profile: ToolProfileName | undefined,
+	context?: ToolProfileContext,
+): ReadonlyArray<ToolName> {
+	const unique = uniquePreservingOrder(tools);
+	let profiled: ReadonlyArray<ToolName>;
+	if (profile === undefined || profile === "full-agent") {
+		profiled = unique;
+	} else {
+		const allowed = NARROW_TOOL_PROFILES[profile];
+		profiled = unique.filter((tool): tool is BuiltinToolName => isBuiltinToolName(tool) && allowed.has(tool));
+	}
+	return applyCodewikiWorkerPolicy(profiled, context);
+}
+
+function uniquePreservingOrder(tools: ReadonlyArray<ToolName>): ToolName[] {
+	const seen = new Set<ToolName>();
+	const unique: ToolName[] = [];
+	for (const tool of tools) {
+		if (seen.has(tool)) continue;
+		seen.add(tool);
+		unique.push(tool);
+	}
+	return unique;
+}
+
+function isCodewikiTool(tool: ToolName): boolean {
+	return (CODEWIKI_TOOL_NAMES as ReadonlyArray<ToolName>).includes(tool);
+}
+
+function isNavigationHeavyTask(task: string | undefined): boolean {
+	if (!task) return false;
+	return /\b(?:codewiki|symbol|symbols|entry\s*points?|where\s+is|code_nav|call\s*sites?|references?|imports?|exports?|map|mapping|navigate|navigation|topology|architecture|boundar(?:y|ies)|ownership|trace|locate|find\s+(?:the\s+)?(?:implementation|definition|module|file|path))\b|(?:^|\s)(?:src|tests?|cmd|pkg|lib)\/|\.(?:[cm]?[tj]sx?|py|pyw|go|rs|c|h|cc|cpp|cxx|hpp|hh|hxx|java|rb)\b/i.test(
+		task,
+	);
+}
+
+function applyCodewikiWorkerPolicy(
+	tools: ReadonlyArray<ToolName>,
+	context: ToolProfileContext | undefined,
+): ReadonlyArray<ToolName> {
+	if (!context?.agentId) return tools;
+	if (context.agentId === "scout") return tools;
+	if (isNavigationHeavyTask(context.task)) return tools;
+	return tools.filter((tool) => !isCodewikiTool(tool));
+}

package/src/tools/read.ts

@@ -0,0 +1,173 @@
+import { readFileSync, statSync } from "node:fs";
+import { Type } from "typebox";
+import { GUARDRAIL_DEFAULTS, GUARDRAIL_ENV_VARS, resolveGuardrail } from "../core/guardrails.js";
+import { ToolNames } from "../core/tool-names.js";
+import { finalizeObservation, observationBudgetExhausted, reserveObservation } from "./observation.js";
+import { resolveReadPath } from "./path-utils.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { isSessionOffloadPath } from "./result-shaping.js";
+import {
+	DEFAULT_MAX_LINES,
+	formatSize,
+	splitLinesForCounting,
+	type TruncationResult,
+	truncateHead,
+	truncateTail,
+} from "./truncate.js";
+import { truncateUtf8 } from "./truncate-utf8.js";
+
+// Per-call read cap. Raised from the 16KB per-observation source cap toward
+// pi's 50KB so large source/generated files finish in fewer calls (a 144KB file
+// took ~9 sequential 16KB reads before). The per-turn observation budget
+// (src/tools/observation.ts) still bounds the aggregate. Value, settings key,
+// and env override (CLIO_CODER_READ_MAX_BYTES) live in core/guardrails.ts.
+export const DEFAULT_READ_MAX_BYTES = GUARDRAIL_DEFAULTS.readMaxBytes;
+export const READ_MAX_BYTES_ENV = GUARDRAIL_ENV_VARS.readMaxBytes;
+const MIN_READ_CAP_BYTES = 1024;
+
+export function readMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+	return Math.max(MIN_READ_CAP_BYTES, resolveGuardrail("readMaxBytes", env));
+}
+
+export const readTool: ToolSpec = {
+	name: ToolNames.Read,
+	description: `Read a UTF-8 text file. Output is capped at ${DEFAULT_MAX_LINES} lines or ${
+		DEFAULT_READ_MAX_BYTES / 1024
+	}KB per call; truncated results say how to continue with offset/limit. Pass tail=N to read the last N lines (jump to EOF) instead of paging from the top.`,
+	parameters: Type.Object({
+		path: Type.String({ description: "File path (relative or absolute)." }),
+		offset: Type.Optional(Type.Number({ description: "1-indexed start line." })),
+		limit: Type.Optional(Type.Number({ description: "Max lines to read." })),
+		tail: Type.Optional(
+			Type.Number({ description: "Read the last N lines of the file (jump to EOF). Overrides offset/limit." }),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+	async run(args, options): Promise<ToolResult> {
+		const pathArg = typeof args.path === "string" ? args.path : null;
+		if (!pathArg) return { kind: "error", message: "read: missing path argument" };
+		const filePath = resolveReadPath(pathArg);
+		const offset = typeof args.offset === "number" && args.offset > 0 ? Math.floor(args.offset) : 1;
+		const limit = typeof args.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : null;
+		const tail = typeof args.tail === "number" && args.tail > 0 ? Math.floor(args.tail) : null;
+		// Reading the session's own offload files bypasses the shared turn pool
+		// (an optionless reservation is untracked): the "full: <path>" escape
+		// hatch appears exactly when the pool is exhausted, so charging these
+		// reads to it made the hatch a dead end. The per-call byte cap still
+		// bounds each slice.
+		const reservation = isSessionOffloadPath(filePath, options?.sessionId)
+			? reserveObservation(readMaxBytes())
+			: reserveObservation(readMaxBytes(), options);
+		try {
+			const stat = statSync(filePath);
+			if (!stat.isFile()) return { kind: "error", message: `read: not a file: ${filePath}` };
+			if (stat.size > 20_000_000) {
+				return {
+					kind: "error",
+					message: `read: file too large (${stat.size}B > 20MB). Use grep/find to locate the relevant section or read a smaller generated/source file; use shell access only when byte-level inspection is explicitly needed.`,
+				};
+			}
+			if (reservation.exhausted) {
+				return observationBudgetExhausted({
+					tool: ToolNames.Read,
+					unit: "lines",
+					reservation,
+					subject: `reading ${pathArg}`,
+					hint: "Use offset/limit in a follow-up turn or grep/find for a narrower section.",
+				});
+			}
+			const content = readFileSync(filePath, "utf8");
+			// Slice from the raw split (keeps the trailing newline on selections that
+			// reach EOF); count lines honestly (a trailing "\n" is a terminator, not
+			// a phantom extra line) so continuation notices never over-report by one.
+			const allLines = content.split("\n");
+			const totalLines = splitLinesForCounting(content).length;
+			const totalBytes = Buffer.byteLength(content, "utf8");
+			const startIndex = Math.min(offset - 1, totalLines);
+			if (tail === null && offset > 1 && startIndex >= totalLines) {
+				// The anchor matters for weak models: a bare "beyond end of file"
+				// reads as a paging mistake and triggers a tail-re-reading walk. Say
+				// plainly that nothing exists past the last line and that re-reading
+				// cannot produce new content.
+				return {
+					kind: "error",
+					message:
+						`read: offset ${offset} is beyond end of file (${totalLines} lines total). The file ends at line ` +
+						`${totalLines} and has no further content; do not page past it or re-read the tail — a read covering ` +
+						`line ${totalLines} has already returned everything.`,
+				};
+			}
+			const cap = reservation.callCapBytes;
+
+			if (tail !== null) {
+				// Jump to EOF: keep the last N lines, then bound by the byte cap from
+				// the end (reusing truncateTail) so the very tail always survives.
+				const startLine = Math.max(0, totalLines - tail);
+				const tailContent = allLines.slice(startLine).join("\n");
+				const truncation = truncateTail(tailContent, { maxBytes: cap, maxLines: tail });
+				const shownLines = truncation.outputLines;
+				const firstShown = Math.max(1, totalLines - shownLines + 1);
+				const truncated = startLine > 0 || truncation.truncated;
+				return finalizeObservation({
+					tool: ToolNames.Read,
+					unit: "lines",
+					output: truncation.content,
+					shownCount: shownLines,
+					totalCount: totalLines,
+					totalBytes,
+					truncated,
+					...(truncated ? { next: `offset=${Math.max(1, firstShown - shownLines)} limit=${shownLines}` } : {}),
+					reservation,
+					...(options ? { options } : {}),
+				});
+			}
+
+			const selected =
+				limit !== null ? allLines.slice(startIndex, startIndex + limit).join("\n") : allLines.slice(startIndex).join("\n");
+			const truncation: TruncationResult = truncateHead(selected, { maxBytes: cap });
+			if (truncation.firstLineExceedsLimit) {
+				const firstLineSize = formatSize(Buffer.byteLength(allLines[startIndex] ?? "", "utf8"));
+				const linePrefix = truncateUtf8(allLines[startIndex] ?? "", cap, "\n[line truncated]");
+				const output = `${linePrefix}\n\n[Line ${startIndex + 1} is ${firstLineSize}, exceeding the ${formatSize(cap)} read limit. Showing the UTF-8 prefix only. Use grep with a narrower literal/regex or edit with exact surrounding text; use shell access only when byte-level inspection is required.]`;
+				return finalizeObservation({
+					tool: ToolNames.Read,
+					unit: "lines",
+					output,
+					shownCount: 0,
+					totalCount: totalLines,
+					totalBytes,
+					truncated: true,
+					omitNotice: true,
+					reservation,
+					...(options ? { options } : {}),
+				});
+			}
+			const endDisplay = startIndex + truncation.outputLines;
+			const moreAfter = endDisplay < totalLines;
+			const truncated = truncation.truncated || (limit !== null && moreAfter);
+			return finalizeObservation({
+				tool: ToolNames.Read,
+				unit: "lines",
+				output: truncation.content,
+				shownCount: truncation.outputLines,
+				totalCount: totalLines,
+				totalBytes,
+				truncated,
+				...(truncated && moreAfter ? { next: `offset=${endDisplay + 1}` } : {}),
+				reservation,
+				...(options ? { options } : {}),
+			});
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			const code = (err as NodeJS.ErrnoException | undefined)?.code;
+			if (code === "ENOENT") {
+				return {
+					kind: "error",
+					message: `read: ${msg}. File not found at ${pathArg}. The path may be wrong. Try: code_nav, find, or ls to locate it.`,
+				};
+			}
+			return { kind: "error", message: `read: ${msg}` };
+		}
+	},
+};