@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/engine/claude/tool-safety.ts

@@ -0,0 +1,400 @@
+import { performance } from "node:perf_hooks";
+import { ToolNames } from "../../core/tool-names.js";
+import type { ClassifierCall } from "../../domains/safety/action-classifier.js";
+import {
+	type AutonomyLevel,
+	autonomyAskRejection,
+	autonomyDenyRejection,
+	DEFAULT_AUTONOMY_LEVEL,
+	mapAutonomy,
+} from "../../domains/safety/autonomy.js";
+import type { SafetyContract, SafetyDecision } from "../../domains/safety/contract.js";
+import type { RejectionMessage } from "../../domains/safety/rejection-feedback.js";
+import type { ToolFinishEvent, ToolStartEvent } from "../../tools/agent-tools.js";
+import type { ClioWorkerEvent } from "../worker-events.js";
+
+export interface MappedClaudeToolCall {
+	claudeToolName: string;
+	clioToolName: string;
+	args: Record<string, unknown>;
+	known: boolean;
+}
+
+export type ClaudeToolPermissionDecision =
+	| {
+			kind: "allow";
+			mapped: MappedClaudeToolCall;
+			decision: SafetyDecision;
+			reason: string;
+			reasonCode?: string;
+	  }
+	| {
+			kind: "deny";
+			mapped: MappedClaudeToolCall;
+			decision: SafetyDecision;
+			reason: string;
+			/**
+			 * Reason code of the final decision when a later axis than the policy
+			 * engine denied the call. The carried policy's own reasonCode describes
+			 * the net pass ("allowed") and would misstate an autonomy denial, so
+			 * autonomy-axis denials set this to `autonomy:<level>` to match the
+			 * native registry audit convention (sd-01 §2.5).
+			 */
+			reasonCode?: string;
+			permissionRequired: boolean;
+	  };
+
+export interface EvaluateClaudeToolPermissionInput {
+	toolName: string;
+	input: Record<string, unknown>;
+	safety: SafetyContract;
+	cwd: string;
+	autonomy?: AutonomyLevel;
+	/**
+	 * The worker's admitted tool surface (Clio builtin names), already narrowed
+	 * by any tool_profile. When present, a mapped Claude tool whose Clio builtin
+	 * is not in this set is denied before the safety net runs, so external CLI
+	 * runtimes cannot execute out-of-profile tools even if they ignore the
+	 * SDK/CLI allow options. Absent means no surface check (legacy callers).
+	 */
+	allowedTools?: ReadonlySet<string>;
+	/** Optional canonical per-call budget gate used by mediated SDK workers. */
+	budgetGate?: {
+		attempt(canonicalToolName: string): { kind: "allow" } | { kind: "deny"; reason: string };
+		admit(canonicalToolName: string): { kind: "allow" } | { kind: "deny"; reason: string };
+	};
+}
+
+export interface EmitClaudeToolPermissionInput extends EvaluateClaudeToolPermissionInput {
+	emit(event: ClioWorkerEvent): void;
+	onPermission?: "deny" | "fail";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringField(record: Record<string, unknown>, ...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim().length > 0) return value.trim();
+	}
+	return undefined;
+}
+
+function pathArgs(input: Record<string, unknown>): Record<string, unknown> {
+	const path = stringField(input, "file_path", "filePath", "path", "notebook_path", "source", "target");
+	return path ? { ...input, path } : { ...input };
+}
+
+function commandArgs(input: Record<string, unknown>, cwd: string): Record<string, unknown> {
+	const command = stringField(input, "command", "cmd", "shell", "input", "description") ?? JSON.stringify(input);
+	return { ...input, command, cwd: stringField(input, "cwd") ?? cwd };
+}
+
+function dynamicToolName(name: string): string {
+	return name.trim().length > 0 ? `claude:${name}` : "claude:unknown";
+}
+
+/**
+ * Static map from Claude preset tool names to the Clio builtin they mediate as.
+ * The single source of truth for both `mapClaudeToolCall` (forward, per-call)
+ * and `claudeToolsOutsideProfile` (reverse, for the SDK/CLI disallow list).
+ * Keep in lockstep with the `mapClaudeToolCall` switch below.
+ */
+const CLAUDE_TOOL_TO_CLIO: Readonly<Record<string, string>> = {
+	Bash: ToolNames.Bash,
+	Read: ToolNames.Read,
+	NotebookRead: ToolNames.Read,
+	Edit: ToolNames.Edit,
+	MultiEdit: ToolNames.Edit,
+	Write: ToolNames.Write,
+	Grep: ToolNames.Grep,
+	Glob: ToolNames.Find,
+	LS: ToolNames.Ls,
+	Ls: ToolNames.Ls,
+	WebFetch: ToolNames.WebFetch,
+	WebSearch: ToolNames.WebFetch,
+	Task: ToolNames.Dispatch,
+	// TodoWrite mediates as the tasks tool: both are session-scoped plan
+	// bookkeeping that never mutates the workspace, so it classifies read and
+	// is narrowed away exactly when the profile lacks tasks.
+	TodoWrite: ToolNames.Tasks,
+};
+
+const CLAUDE_CANONICAL_TOOLS = new Set(Object.values(CLAUDE_TOOL_TO_CLIO));
+
+/** Whether the Claude preset exposes at least one vendor alias for this canonical Clio tool. */
+export function isClaudeCanonicalTool(name: string): boolean {
+	return CLAUDE_CANONICAL_TOOLS.has(name);
+}
+
+/**
+ * Claude preset tool names whose Clio builtin is not in the worker's allowed
+ * surface. Fed to the SDK's `disallowedTools` option (and the same list is used
+ * by the mediation gate as the authoritative check). Only mapped/known tools
+ * participate; unmapped Claude-internal tools are left to the safety net.
+ */
+export function claudeToolsOutsideProfile(allowedTools: ReadonlySet<string>): string[] {
+	return Object.entries(CLAUDE_TOOL_TO_CLIO)
+		.filter(([, clioName]) => !allowedTools.has(clioName))
+		.map(([claudeName]) => claudeName);
+}
+
+function mapClaudeToolCall(toolName: string, input: Record<string, unknown>, cwd: string): MappedClaudeToolCall {
+	switch (toolName) {
+		case "Bash":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Bash, args: commandArgs(input, cwd), known: true };
+		case "Read":
+		case "NotebookRead":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Read, args: pathArgs(input), known: true };
+		case "Edit":
+		case "MultiEdit":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Edit, args: pathArgs(input), known: true };
+		case "Write":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Write, args: pathArgs(input), known: true };
+		case "Grep":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Grep, args: pathArgs(input), known: true };
+		case "Glob":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Find, args: pathArgs(input), known: true };
+		case "LS":
+		case "Ls":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Ls, args: pathArgs(input), known: true };
+		case "WebFetch":
+		case "WebSearch":
+			return { claudeToolName: toolName, clioToolName: ToolNames.WebFetch, args: { ...input }, known: true };
+		case "Task":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Dispatch, args: { ...input }, known: true };
+		case "TodoWrite":
+			return { claudeToolName: toolName, clioToolName: ToolNames.Tasks, args: { ...input }, known: true };
+		default:
+			return { claudeToolName: toolName, clioToolName: dynamicToolName(toolName), args: { ...input }, known: false };
+	}
+}
+
+function toAutonomyBlock(decision: SafetyDecision, level: AutonomyLevel, call: ClassifierCall): SafetyDecision {
+	const actionClass = decision.classification.actionClass;
+	return {
+		kind: "block",
+		classification: decision.classification,
+		rejection: autonomyDenyRejection(level, call.tool, actionClass),
+		...(decision.policy !== undefined ? { policy: decision.policy } : {}),
+	};
+}
+
+function toAutonomyAsk(decision: SafetyDecision, level: AutonomyLevel, call: ClassifierCall): SafetyDecision {
+	const actionClass = decision.classification.actionClass;
+	return {
+		kind: "ask",
+		classification: decision.classification,
+		rejection: autonomyAskRejection(level, call.tool, actionClass),
+		...(decision.policy !== undefined ? { policy: decision.policy } : {}),
+	};
+}
+
+function rejectionText(decision: SafetyDecision): string {
+	if (decision.kind === "allow") return decision.policy?.reasonCode ?? "allowed";
+	return decision.rejection.short;
+}
+
+function budgetDenial(
+	input: EvaluateClaudeToolPermissionInput,
+	mapped: MappedClaudeToolCall,
+	call: ClassifierCall,
+	reason: string,
+): ClaudeToolPermissionDecision {
+	const classification = input.safety.classify(call);
+	const rejection: RejectionMessage = { short: reason, detail: reason, hints: [] };
+	const blocked: SafetyDecision = { kind: "block", classification, rejection };
+	input.safety.audit.recordToolCall?.({
+		tool: mapped.clioToolName,
+		classification,
+		decision: "denied",
+		args: mapped.args,
+		reasons: [reason],
+		reasonCode: "worker-budget",
+	});
+	return {
+		kind: "deny",
+		mapped,
+		decision: blocked,
+		reason,
+		reasonCode: "worker-budget",
+		permissionRequired: false,
+	};
+}
+
+export function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput): ClaudeToolPermissionDecision {
+	const mapped = mapClaudeToolCall(input.toolName, input.input, input.cwd);
+	const call: ClassifierCall = { tool: mapped.clioToolName, args: mapped.args };
+	const attempt = input.budgetGate?.attempt(mapped.clioToolName);
+	if (attempt?.kind === "deny") return budgetDenial(input, mapped, call, attempt.reason);
+	// Tool-profile / admitted-surface gate. This is the authoritative narrowing
+	// enforcement for SDK workers: it runs before the safety net so an
+	// out-of-profile tool (e.g. bash under minimal-local) is denied regardless
+	// of the autonomy verdict, and it does not depend on the external CLI
+	// honoring the allow/disallow options. Only mapped (known) Claude tools are
+	// gated; unmapped Claude-internal tools defer to the safety net as before.
+	if (input.allowedTools !== undefined && mapped.known && !input.allowedTools.has(mapped.clioToolName)) {
+		const classification = input.safety.classify(call);
+		const rejection: RejectionMessage = {
+			short: `${mapped.clioToolName} is not in this worker's tool profile`,
+			detail: `Tool '${mapped.clioToolName}' is outside the dispatched worker's admitted tool surface, so the request is denied. Use only the tools granted to this run.`,
+			hints: [],
+		};
+		const blocked: SafetyDecision = { kind: "block", classification, rejection };
+		input.safety.audit.recordToolCall?.({
+			tool: mapped.clioToolName,
+			classification,
+			decision: "denied",
+			args: mapped.args,
+			reasons: [rejection.detail],
+			reasonCode: "tool-profile",
+		});
+		return {
+			kind: "deny",
+			mapped,
+			decision: blocked,
+			reason: rejection.short,
+			reasonCode: "tool-profile",
+			permissionRequired: false,
+		};
+	}
+	const decision = input.safety.evaluate(call);
+	const level = input.autonomy ?? DEFAULT_AUTONOMY_LEVEL;
+	if (decision.kind === "block") {
+		return { kind: "deny", mapped, decision, reason: rejectionText(decision), permissionRequired: false };
+	}
+	if (decision.kind === "ask") {
+		if (level === "read-only") {
+			const blocked = toAutonomyBlock(decision, level, call);
+			return {
+				kind: "deny",
+				mapped,
+				decision: blocked,
+				reason: rejectionText(blocked),
+				reasonCode: `autonomy:${level}`,
+				permissionRequired: false,
+			};
+		}
+		return { kind: "deny", mapped, decision, reason: rejectionText(decision), permissionRequired: true };
+	}
+	const actionClass = decision.classification.actionClass;
+	const disposition = mapAutonomy(level, actionClass, {
+		executeRecognized: decision.policy?.execRecognition !== "unrecognized",
+	});
+	if (disposition === "allow") {
+		const admission = input.budgetGate?.admit(mapped.clioToolName);
+		if (admission?.kind === "deny") return budgetDenial(input, mapped, call, admission.reason);
+		return { kind: "allow", mapped, decision, reason: decision.policy?.reasonCode ?? "allowed" };
+	}
+	if (disposition === "deny") {
+		const blocked = toAutonomyBlock(decision, level, call);
+		return {
+			kind: "deny",
+			mapped,
+			decision: blocked,
+			reason: rejectionText(blocked),
+			reasonCode: `autonomy:${level}`,
+			permissionRequired: false,
+		};
+	}
+	const ask = toAutonomyAsk(decision, level, call);
+	return {
+		kind: "deny",
+		mapped,
+		decision: ask,
+		reason: rejectionText(ask),
+		reasonCode: `autonomy:${level}`,
+		permissionRequired: true,
+	};
+}
+
+function finishDecision(decision: SafetyDecision): NonNullable<ToolFinishEvent["decision"]> {
+	if (decision.kind === "allow") return "allowed";
+	if (decision.kind === "ask") return "permission_requested";
+	return "blocked";
+}
+
+function emitToolFinish(
+	emit: (event: ClioWorkerEvent) => void,
+	mapped: MappedClaudeToolCall,
+	startedAtClock: number,
+	decision: SafetyDecision,
+	outcome: ToolFinishEvent["outcome"],
+	reason: string,
+	reasonCode?: string,
+): void {
+	const event: ToolFinishEvent = {
+		tool: mapped.clioToolName,
+		posture: "operating",
+		durationMs: Math.round(performance.now() - startedAtClock),
+		outcome,
+		actionClass: decision.classification.actionClass,
+		decision: finishDecision(decision),
+	};
+	if (reason.length > 0 && outcome !== "ok") event.reason = reason;
+	if (decision.policy?.ruleId !== undefined) event.ruleId = decision.policy.ruleId;
+	// Prefer an explicit final reasonCode (later-axis denial) over the policy's
+	// own reasonCode, which describes the net pass ("allowed") and would
+	// misstate an autonomy denial. Mirrors audit.ts `reasonCode ?? policy`.
+	const finalReasonCode = reasonCode ?? decision.policy?.reasonCode;
+	if (finalReasonCode !== undefined) event.reasonCode = finalReasonCode;
+	if (decision.policy?.policySource !== undefined) event.policySource = decision.policy.policySource;
+	emit({ type: "clio_tool_finish", payload: event });
+}
+
+export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermissionInput): ClaudeToolPermissionDecision {
+	// Wall read anchors the instant the start event carries; the monotonic twin
+	// spans the decision, so the duration survives a clock correction.
+	const startedAt = Date.now();
+	const startedAtClock = performance.now();
+	const decision = evaluateClaudeToolPermission(input);
+	const start: ToolStartEvent = {
+		tool: decision.mapped.clioToolName,
+		posture: "operating",
+		startedAt,
+	};
+	input.emit({ type: "clio_tool_start", payload: start });
+	if (decision.kind === "allow") {
+		emitToolFinish(
+			input.emit,
+			decision.mapped,
+			startedAtClock,
+			decision.decision,
+			"ok",
+			decision.reason,
+			decision.reasonCode,
+		);
+		return decision;
+	}
+	if (decision.permissionRequired) {
+		const mode = input.onPermission ?? "deny";
+		input.emit({
+			type: "clio_permission_resolved",
+			payload: {
+				tool: decision.mapped.clioToolName,
+				actionClass: decision.decision.classification.actionClass,
+				mode,
+				reason:
+					mode === "fail"
+						? `permission required for ${decision.mapped.clioToolName}; workers.onPermission=fail ends this run`
+						: `permission denied by policy: Claude SDK workers run non-interactively; ${decision.reason}`,
+			},
+		});
+	}
+	emitToolFinish(
+		input.emit,
+		decision.mapped,
+		startedAtClock,
+		decision.decision,
+		"blocked",
+		decision.reason,
+		decision.reasonCode,
+	);
+	return decision;
+}
+
+export function coerceToolInput(value: unknown): Record<string, unknown> {
+	return isRecord(value) ? value : {};
+}

package/src/engine/external-subprocess.ts

@@ -0,0 +1,23 @@
+import type { ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+
+export type SubprocessWithStdio = ChildProcessByStdio<null, Readable, Readable>;
+
+export async function readStderr(child: { stderr: Readable }): Promise<string> {
+	let stderr = "";
+	for await (const chunk of child.stderr) {
+		stderr += String(chunk);
+		if (stderr.length > 8192) stderr = stderr.slice(-8192);
+	}
+	return stderr;
+}
+
+export function waitForClose(child: {
+	once(event: "error", listener: (err: Error) => void): unknown;
+	once(event: "close", listener: (code: number | null) => void): unknown;
+}): Promise<number> {
+	return new Promise((resolve) => {
+		child.once("error", () => resolve(1));
+		child.once("close", (code: number | null) => resolve(code ?? 1));
+	});
+}

package/src/engine/harmony-response.ts

@@ -0,0 +1,165 @@
+/**
+ * Streaming parser for OpenAI Harmony response markers used by GPT-OSS.
+ *
+ * Some local OpenAI-compatible servers return the model's raw chat-template
+ * text instead of normalized `content` / `reasoning_content` fields. In that
+ * mode GPT-OSS can leak markers like
+ * `<|start|>assistant<|channel|>final<|message|>` into visible output. This
+ * parser consumes those markers and routes channel payloads into Clio's text
+ * or thinking streams.
+ */
+
+import {
+	type HarmonyReasoningEffort,
+	harmonyReasoningEffort,
+	isHarmonyThinkingFormat,
+} from "../domains/providers/model-runtime-capabilities.js";
+
+const START = "<|start|>";
+const CHANNEL = "<|channel|>";
+const CONSTRAIN = "<|constrain|>";
+const MESSAGE = "<|message|>";
+const RECIPIENT = "<|recipient|>";
+const END = "<|end|>";
+const RETURN = "<|return|>";
+
+const MARKERS: ReadonlyArray<string> = [START, CHANNEL, CONSTRAIN, MESSAGE, RECIPIENT, END, RETURN];
+const HEADER_METADATA_MARKERS: ReadonlyArray<string> = [CONSTRAIN, RECIPIENT];
+const MAX_MARKER_LENGTH = MARKERS.reduce((max, marker) => Math.max(max, marker.length), 0);
+
+export interface HarmonyParsedChunk {
+	text: string;
+	thinking: string;
+}
+
+type HarmonyRoute = "text" | "thinking";
+
+export { type HarmonyReasoningEffort, harmonyReasoningEffort, isHarmonyThinkingFormat };
+
+export class HarmonyResponseParser {
+	private buffer = "";
+	private route: HarmonyRoute = "text";
+
+	push(chunk: string): HarmonyParsedChunk {
+		if (!chunk) return emptyParsed();
+		this.buffer += chunk;
+		return this.drain(false);
+	}
+
+	flush(): HarmonyParsedChunk {
+		return this.drain(true);
+	}
+
+	private drain(final: boolean): HarmonyParsedChunk {
+		let text = "";
+		let thinking = "";
+		const emit = (value: string): void => {
+			if (!value) return;
+			if (this.route === "thinking") thinking += value;
+			else text += value;
+		};
+
+		while (this.buffer.length > 0) {
+			const parsedFrame = this.consumeFrameHeader();
+			if (parsedFrame) continue;
+
+			if (this.consumeExact(END) || this.consumeExact(RETURN)) continue;
+
+			const markerIndex = firstMarkerIndex(this.buffer);
+			if (markerIndex > 0) {
+				emit(this.buffer.slice(0, markerIndex));
+				this.buffer = this.buffer.slice(markerIndex);
+				continue;
+			}
+
+			if (markerIndex === 0) {
+				if (!final) break;
+				// Unknown complete-ish marker at end of stream: drop only the
+				// marker bytes and preserve following ordinary text if any.
+				const marker = MARKERS.find((candidate) => this.buffer.startsWith(candidate));
+				if (!marker) break;
+				this.buffer = this.buffer.slice(marker.length);
+				continue;
+			}
+
+			const hold = final ? 0 : harmonyPrefixTailLength(this.buffer);
+			const emitLength = this.buffer.length - hold;
+			if (emitLength <= 0) break;
+			emit(this.buffer.slice(0, emitLength));
+			this.buffer = this.buffer.slice(emitLength);
+		}
+
+		if (final && this.buffer.length > 0) {
+			emit(this.buffer);
+			this.buffer = "";
+		}
+
+		return { text, thinking };
+	}
+
+	private consumeFrameHeader(): boolean {
+		if (this.buffer.startsWith(START)) {
+			const channelIndex = this.buffer.indexOf(CHANNEL, START.length);
+			if (channelIndex === -1) return false;
+			const messageIndex = this.buffer.indexOf(MESSAGE, channelIndex + CHANNEL.length);
+			if (messageIndex === -1) return false;
+			this.setChannel(this.buffer.slice(channelIndex + CHANNEL.length, messageIndex));
+			this.buffer = this.buffer.slice(messageIndex + MESSAGE.length);
+			return true;
+		}
+
+		if (this.buffer.startsWith(CHANNEL)) {
+			const messageIndex = this.buffer.indexOf(MESSAGE, CHANNEL.length);
+			if (messageIndex === -1) return false;
+			this.setChannel(this.buffer.slice(CHANNEL.length, messageIndex));
+			this.buffer = this.buffer.slice(messageIndex + MESSAGE.length);
+			return true;
+		}
+
+		return false;
+	}
+
+	private consumeExact(marker: string): boolean {
+		if (!this.buffer.startsWith(marker)) return false;
+		this.buffer = this.buffer.slice(marker.length);
+		return true;
+	}
+
+	private setChannel(rawChannel: string): void {
+		const metadataIndex = firstHeaderMetadataIndex(rawChannel);
+		const channelText = metadataIndex === -1 ? rawChannel : rawChannel.slice(0, metadataIndex);
+		const channel = (channelText.trim().split(/\s+/, 1)[0] ?? "").toLowerCase();
+		this.route = channel === "final" ? "text" : "thinking";
+	}
+}
+
+function emptyParsed(): HarmonyParsedChunk {
+	return { text: "", thinking: "" };
+}
+
+function firstMarkerIndex(value: string): number {
+	let first = -1;
+	for (const marker of MARKERS) {
+		const idx = value.indexOf(marker);
+		if (idx !== -1 && (first === -1 || idx < first)) first = idx;
+	}
+	return first;
+}
+
+function firstHeaderMetadataIndex(value: string): number {
+	let first = -1;
+	for (const marker of HEADER_METADATA_MARKERS) {
+		const idx = value.indexOf(marker);
+		if (idx !== -1 && (first === -1 || idx < first)) first = idx;
+	}
+	return first;
+}
+
+function harmonyPrefixTailLength(value: string): number {
+	const max = Math.min(value.length, MAX_MARKER_LENGTH - 1);
+	for (let len = max; len > 0; len--) {
+		const tail = value.slice(value.length - len);
+		if (MARKERS.some((marker) => marker.startsWith(tail))) return len;
+	}
+	return 0;
+}