@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/safety/rejection-feedback.ts

@@ -0,0 +1,102 @@
+/**
+ * Human-readable rejection messages for blocked tool calls. The registry
+ * (slice 6) renders `short` in the UI footer, attaches `detail` to the audit
+ * record, and surfaces `hints` to the worker so the next turn can recover
+ * without another round-trip.
+ */
+
+export interface RejectionContext {
+	tool: string;
+	actionClass: string;
+	posture?: string;
+	reasons: ReadonlyArray<string>;
+	ruleId?: string;
+}
+
+export interface RejectionMessage {
+	short: string;
+	detail: string;
+	hints: ReadonlyArray<string>;
+}
+
+const HARD_BLOCK_CLASSES: ReadonlyArray<string> = ["git_destructive"];
+
+function buildShort(ctx: RejectionContext): string {
+	const postureSuffix = ctx.posture ? ` in ${ctx.posture}` : "";
+	return `${ctx.tool} blocked: ${ctx.actionClass}${postureSuffix}`;
+}
+
+function buildDetail(ctx: RejectionContext): string {
+	const lines: string[] = [`Clio refused to run ${ctx.tool}.`];
+	for (const reason of ctx.reasons) {
+		lines.push(`- ${reason}`);
+	}
+	if (ctx.ruleId) {
+		lines.push(`rule: ${ctx.ruleId}`);
+	}
+	return lines.join("\n");
+}
+
+function buildHints(ctx: RejectionContext): string[] {
+	const hints: string[] = [];
+	const hardBlock = HARD_BLOCK_CLASSES.includes(ctx.actionClass) || ctx.ruleId !== undefined;
+	if (hardBlock) {
+		hints.push("This is a hard block; confirmation cannot override it.");
+		return hints;
+	}
+	if (ctx.actionClass === "system_modify") {
+		hints.push("Operator confirmation is required for this action.");
+	}
+	return hints;
+}
+
+export function formatRejection(ctx: RejectionContext): RejectionMessage {
+	return {
+		short: buildShort(ctx),
+		detail: buildDetail(ctx),
+		hints: buildHints(ctx),
+	};
+}
+
+/**
+ * The model-facing text for a blocked tool call. The short label alone
+ * ("read blocked: read") tells the model nothing about why the call failed
+ * or how to recover, which is how blocked-call retry spirals start: the next
+ * turn re-tries the same target through another tool because nothing said
+ * the gate applies everywhere. Compose the verdict reason (which a loop
+ * guard may already have replaced with its own recovery feedback) with the
+ * rejection's detail and hints, deduplicated line by line, and close with
+ * the standing pivot instruction, which always closes the message. Output is
+ * enforced-bounded: lines cap at 300 characters and the message at 16 lines,
+ * because reason strings interpolate caller data (paths, commands) verbatim.
+ */
+const MODEL_REJECTION_PIVOT =
+	"Do not retry this action through another tool unless a hint above names one; pivot or report the blocker.";
+const MODEL_REJECTION_MAX_LINES = 16;
+const MODEL_REJECTION_MAX_LINE_CHARS = 300;
+
+export function formatModelRejection(reason: string, rejection?: RejectionMessage): string {
+	const lines: string[] = [];
+	const seen = new Set<string>();
+	const push = (line: string): void => {
+		const bounded =
+			line.length > MODEL_REJECTION_MAX_LINE_CHARS ? `${line.slice(0, MODEL_REJECTION_MAX_LINE_CHARS)}…` : line;
+		const trimmed = bounded.trim();
+		if (trimmed.length === 0) return;
+		const normalized = trimmed.replace(/^-\s+/, "");
+		if (seen.has(normalized) || normalized === MODEL_REJECTION_PIVOT) return;
+		seen.add(normalized);
+		lines.push(trimmed);
+	};
+	for (const line of reason.split("\n")) push(line);
+	if (rejection) {
+		for (const line of rejection.detail.split("\n")) push(line);
+		for (const hint of rejection.hints) push(hint);
+	}
+	// Bound the body and close with the standing pivot instruction, always
+	// last: recovery guidance must be the final thing the model reads even
+	// when a policy author pre-seeds the same sentence into the detail.
+	const bodyBudget = MODEL_REJECTION_MAX_LINES - 1;
+	const body = lines.length > bodyBudget ? [...lines.slice(0, bodyBudget - 1), "(further detail elided)"] : lines;
+	return [...body, MODEL_REJECTION_PIVOT].join("\n");
+}

package/src/domains/safety/rigor.ts

@@ -0,0 +1,72 @@
+/**
+ * Rigor is a single attribute, orthogonal to the autonomy permission levels.
+ * Permission (`read-only` / `suggest` / `auto-edit` / `full-auto`) says what an
+ * agent may touch; rigor says what evidence "done" requires. It has two values:
+ *
+ * - `normal`: the finish-contract advisory stays a soft `warn` reminder.
+ * - `high`: an unvalidated completion claim re-prompts the model to run
+ *   validation or state a limitation before the turn settles.
+ *
+ * Rigor resolves from a per-session / per-dispatch override (the `CLIO_CODER_RIGOR`
+ * env var today) layered over a repo-derived default. The repo-derived default
+ * is `high` when the workspace declares a scientific-validation contract by the
+ * documented path convention below, and `normal` otherwise. This keeps the
+ * evidence bar derived from what the repo actually is rather than from a global
+ * toggle.
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export type Rigor = "normal" | "high";
+
+/**
+ * Workspace-root files that declare a scientific-validation contract. Presence
+ * of any one of these raises the repo-derived rigor default to `high`. The
+ * convention is intentionally small and explicit: a project opts into a higher
+ * evidence bar by committing a validation contract at its root.
+ */
+const VALIDATION_CONTRACT_FILES: ReadonlyArray<string> = [
+	path.join(".clio-coder", "validation.yaml"),
+	path.join(".clio-coder", "validation.yml"),
+	"validation.yaml",
+	"validation.yml",
+	"VALIDATION.md",
+];
+
+/**
+ * Resolve the effective rigor. An explicit override (`"high"` | `"normal"`)
+ * always wins; otherwise the repo-derived default keys off the presence of a
+ * validation contract at the workspace root.
+ */
+export function resolveRigor(options: { cwd?: string; override?: Rigor | null }): Rigor {
+	if (options.override === "high" || options.override === "normal") return options.override;
+	const cwd = options.cwd ?? process.cwd();
+	return hasValidationContract(cwd) ? "high" : "normal";
+}
+
+/**
+ * Parse a rigor override string (e.g. from the `CLIO_CODER_RIGOR` env var). Accepts
+ * `"high"` or `"normal"` case-insensitively after trimming; anything else
+ * yields `null` (no override).
+ */
+export function parseRigorOverride(value: string | null | undefined): Rigor | null {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	if (normalized === "high") return "high";
+	if (normalized === "normal") return "normal";
+	return null;
+}
+
+/**
+ * True when the workspace declares a scientific-validation contract by the
+ * documented path convention. Pure and resilient: any filesystem error is
+ * swallowed and treated as "no contract".
+ */
+function hasValidationContract(cwd: string): boolean {
+	try {
+		return VALIDATION_CONTRACT_FILES.some((relative) => existsSync(path.join(cwd, relative)));
+	} catch {
+		return false;
+	}
+}

package/src/domains/safety/rule-compiler.ts

@@ -0,0 +1,48 @@
+import type { DamageControlRule } from "./damage-control.js";
+
+interface RawRule {
+	id?: unknown;
+	description?: unknown;
+	pattern?: unknown;
+	class?: unknown;
+	block?: unknown;
+	ask?: unknown;
+}
+
+function asString(value: unknown, ruleId: string, field: string): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`damage-control rule '${ruleId}': expected string for ${field}`);
+	}
+	return value;
+}
+
+export function compileDamageControlRule(raw: RawRule, index: number): DamageControlRule {
+	if (typeof raw.id !== "string" || raw.id.length === 0) {
+		throw new Error(`damage-control rule at index ${index}: missing or non-string 'id'`);
+	}
+	const id = raw.id;
+	const description = asString(raw.description, id, "description");
+	const patternString = asString(raw.pattern, id, "pattern");
+	const klass = asString(raw.class, id, "class");
+	if (typeof raw.block !== "boolean") {
+		throw new Error(`damage-control rule '${id}': expected boolean for block`);
+	}
+	if (raw.ask !== undefined && typeof raw.ask !== "boolean") {
+		throw new Error(`damage-control rule '${id}': expected boolean for ask`);
+	}
+	let pattern: RegExp;
+	try {
+		pattern = new RegExp(patternString, "i");
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`damage-control rule '${id}': invalid pattern: ${msg}`);
+	}
+	return {
+		id,
+		description,
+		pattern,
+		class: klass,
+		block: raw.block,
+		...(raw.ask !== undefined ? { ask: raw.ask } : {}),
+	};
+}

package/src/domains/safety/rule-pack-loader.ts

@@ -0,0 +1,92 @@
+/**
+ * Layered rule pack loader for damage-control-rules.yaml (schema v2).
+ *
+ * v2 stores the always-on hard blocks in a named base pack.
+ *
+ * v1 schema is tolerated for backward compatibility: a top-level `rules:`
+ * array is mapped to packs[base].
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import type { DamageControlRule, DamageControlRuleset } from "./damage-control.js";
+import { compileDamageControlRule } from "./rule-compiler.js";
+
+export type PackId = "base";
+
+export interface RulePacks {
+	base: DamageControlRuleset;
+}
+
+interface RawPack {
+	id?: unknown;
+	rules?: unknown;
+}
+
+interface RawDocument {
+	version?: unknown;
+	packs?: unknown;
+	rules?: unknown;
+}
+
+function compilePackRules(rawRules: unknown, packId: string): DamageControlRule[] {
+	if (rawRules === undefined || rawRules === null) return [];
+	if (!Array.isArray(rawRules)) {
+		throw new Error(`damage-control pack '${packId}': expected array at 'rules'`);
+	}
+	return rawRules.map((rule, index) => compileDamageControlRule(rule as Record<string, unknown>, index));
+}
+
+function emptyRuleset(version: number): DamageControlRuleset {
+	return { version, rules: [] };
+}
+
+function loadRulePacks(yamlPath: string): RulePacks {
+	const raw = readFileSync(yamlPath, "utf8");
+	const parsed = parseYaml(raw) as RawDocument | null;
+	if (!parsed || typeof parsed !== "object") {
+		throw new Error(`damage-control rules at ${yamlPath}: expected mapping at document root`);
+	}
+	const version = typeof parsed.version === "number" ? parsed.version : 0;
+
+	if (version === 1) {
+		// v1: flat `rules:` becomes the base pack.
+		const baseRules = compilePackRules(parsed.rules, "base");
+		return {
+			base: { version: 1, rules: baseRules },
+		};
+	}
+
+	if (version !== 2) {
+		throw new Error(`damage-control rules at ${yamlPath}: unsupported version ${String(parsed.version)}`);
+	}
+
+	if (!Array.isArray(parsed.packs)) {
+		throw new Error(`damage-control rules at ${yamlPath}: expected array at 'packs'`);
+	}
+	const out: RulePacks = {
+		base: emptyRuleset(2),
+	};
+	for (const rawPack of parsed.packs as RawPack[]) {
+		const packId = rawPack.id;
+		if (packId !== "base") {
+			throw new Error(`damage-control rules at ${yamlPath}: unknown pack id ${String(packId)}`);
+		}
+		const rules = compilePackRules(rawPack.rules, packId);
+		out[packId] = { version: 2, rules };
+	}
+	return out;
+}
+
+function loadDefaultRulePacks(): RulePacks {
+	return loadRulePacks(join(resolvePackageRoot(), "damage-control-rules.yaml"));
+}
+
+let cachedPacks: RulePacks | null = null;
+
+export function getCachedDefaultRulePacks(): RulePacks {
+	if (cachedPacks === null) cachedPacks = loadDefaultRulePacks();
+	return cachedPacks;
+}

package/src/domains/safety/run-effects.ts

@@ -0,0 +1,197 @@
+import path from "node:path";
+import { ToolNames } from "../../core/tool-names.js";
+import { typedValidationSummary } from "./finish-contract.js";
+import {
+	detectValidationCommand,
+	extractCommandDeleteTargets,
+	extractCommandWriteTargets,
+	tokenizeShellLike,
+	toolMutationPaths,
+	type ValidationCommandScope,
+} from "./protected-artifacts.js";
+
+/**
+ * What a run's own tool calls show it did to the workspace.
+ *
+ * A mutation report claims paths and validations. Neither claim means anything
+ * on its own: the run's tool calls are the only record of what it actually
+ * touched and what it actually ran. This is the write-side counterpart of the
+ * observed read spans that ground a Scout citation, recorded from the same tool
+ * event stream so the worker's bounded repair round and the orchestrator's
+ * sealed validation judge one set of facts.
+ *
+ * `mutatedPaths` is deliberately generous. Its only job is to answer "could
+ * this run have produced this path", so a write channel it cannot enumerate (a
+ * bash command that writes through a script) leaves the path absent from the
+ * set and the validator falls back to the filesystem rather than to a failed
+ * conformance.
+ */
+export interface RunEffects {
+	/** Absolute paths the run's successful tool calls aimed a mutation at. */
+	mutatedPaths: ReadonlySet<string>;
+	/**
+	 * Absolute paths whose only mutation attempt came back blocked or errored.
+	 * Observed live (receipt 182h2ai478p5): a coder's edit was refused by the
+	 * worker permission policy and the report still claimed the file as mutated.
+	 * The file existed, so presence could not tell the claim from the truth; the
+	 * run's own failed tool result can.
+	 */
+	failedMutationPaths: ReadonlySet<string>;
+	/** Canonical validation commands the run ran to a clean exit. */
+	validationCommands: ReadonlySet<string>;
+	/**
+	 * The same commands read under the wider `grounding` vocabulary, which adds
+	 * read verification (`git diff`), ad-hoc checks (`node -e`) and the runners
+	 * the strict set omits (`npx vitest`, `tsc --noEmit`). Always a superset of
+	 * `validationCommands`, because the grounding scope falls back to the strict
+	 * matcher first.
+	 *
+	 * The two sets exist because their readers pay different prices for a match.
+	 * `validationCommands` opens a gate: `result-contract.ts` reads
+	 * `validationCommands.size > 0` as the difference between a mutation report
+	 * sealing `pass` and sealing `unmeasured`, and a run whose only command was
+	 * `git diff` has asserted nothing about correctness. `verificationCommands`
+	 * only decides whether a receipt prints `unmatched validation: ...`, where a
+	 * miss and a false match both cost one line of noise, so it can afford the
+	 * wider set.
+	 */
+	verificationCommands: ReadonlySet<string>;
+}
+
+export interface RunEffectsRecorder {
+	/** Record a tool call's mutation targets and validation identity. */
+	start(toolCallId: string, toolName: string, args: Record<string, unknown> | undefined): void;
+	/** Commit a call's effects, or drop them when the call did not succeed. */
+	finish(toolCallId: string, failed: boolean): void;
+	snapshot(): RunEffects;
+}
+
+interface PendingEffects {
+	paths: ReadonlyArray<string>;
+	validationCommand: string | null;
+	verificationCommand: string | null;
+}
+
+/**
+ * Git subcommands that move or remove named path operands. The shared
+ * write-target extractor classifies bare `mv`/`rm`, not their git spellings,
+ * and it stays that way: widening it would change what the finish-contract gate
+ * treats as a mutating turn. Grounding wants the wider set, because a path this
+ * misses can only produce a false conformance failure.
+ */
+const GIT_PATH_MUTATIONS: ReadonlySet<string> = new Set(["mv", "rm"]);
+
+function gitPathOperands(command: string): string[] {
+	const targets: string[] = [];
+	for (const segment of splitCommandSegments(command)) {
+		if (segment[0] !== "git") continue;
+		const subcommand = segment[1];
+		if (subcommand === undefined || !GIT_PATH_MUTATIONS.has(subcommand)) continue;
+		for (const token of segment.slice(2)) {
+			if (token.startsWith("-")) continue;
+			targets.push(token);
+		}
+	}
+	return targets;
+}
+
+/**
+ * Split the shared tokenizer's output on command separators. Only the
+ * git-operand scan above needs segments, and it needs them after tokenization
+ * rather than off the raw string.
+ */
+function splitCommandSegments(command: string): string[][] {
+	const segments: string[][] = [];
+	let current: string[] = [];
+	for (const token of tokenizeShellLike(command)) {
+		if (token === ";" || token === "&&" || token === "||" || token === "|") {
+			if (current.length > 0) segments.push(current);
+			current = [];
+			continue;
+		}
+		current.push(token);
+	}
+	if (current.length > 0) segments.push(current);
+	return segments;
+}
+
+function commandOf(args: Record<string, unknown> | undefined): string | null {
+	const command = args?.command;
+	return typeof command === "string" && command.length > 0 ? command : null;
+}
+
+function mutationTargets(toolName: string, args: Record<string, unknown> | undefined): string[] {
+	if (toolName !== ToolNames.Bash) return toolMutationPaths(toolName, args);
+	const command = commandOf(args);
+	if (command === null) return [];
+	return [...extractCommandWriteTargets(command), ...extractCommandDeleteTargets(command), ...gitPathOperands(command)];
+}
+
+/**
+ * The canonical identity of a call's check under one scope. A typed
+ * verification tool carries the same identity under both scopes: the scope only
+ * widens which bash spellings are recognized as a check at all.
+ */
+function validationCommandOf(
+	toolName: string,
+	args: Record<string, unknown> | undefined,
+	scope: ValidationCommandScope,
+): string | null {
+	if (toolName === ToolNames.Bash) {
+		const command = commandOf(args);
+		if (command === null) return null;
+		const detected = detectValidationCommand(command, scope);
+		return detected.kind === "validation" ? detected.matched : null;
+	}
+	return typedValidationSummary(toolName, { args: args ?? {} });
+}
+
+/**
+ * Fold a run's tool calls into its observed effects. A call's effects land only
+ * when its result comes back clean: a blocked write and a red command are not
+ * evidence that the workspace changed or that a check passed.
+ */
+export function createRunEffectsRecorder(cwd: string): RunEffectsRecorder {
+	const pending = new Map<string, PendingEffects>();
+	const mutatedPaths = new Set<string>();
+	const failedMutationPaths = new Set<string>();
+	const validationCommands = new Set<string>();
+	const verificationCommands = new Set<string>();
+	return {
+		start(toolCallId, toolName, args) {
+			const paths = mutationTargets(toolName, args);
+			const validationCommand = validationCommandOf(toolName, args, "finish-contract");
+			const verificationCommand = validationCommandOf(toolName, args, "grounding");
+			if (paths.length === 0 && validationCommand === null && verificationCommand === null) return;
+			// A bash call may re-base its relative paths with its own cwd argument.
+			const base = typeof args?.cwd === "string" && args.cwd.length > 0 ? path.resolve(cwd, args.cwd) : cwd;
+			pending.set(toolCallId, {
+				paths: paths.map((target) => path.resolve(base, target)),
+				validationCommand,
+				verificationCommand,
+			});
+		},
+		finish(toolCallId, failed) {
+			const effects = pending.get(toolCallId);
+			pending.delete(toolCallId);
+			if (effects === undefined) return;
+			if (failed) {
+				for (const target of effects.paths) failedMutationPaths.add(target);
+				return;
+			}
+			for (const target of effects.paths) mutatedPaths.add(target);
+			if (effects.validationCommand !== null) validationCommands.add(effects.validationCommand);
+			if (effects.verificationCommand !== null) verificationCommands.add(effects.verificationCommand);
+		},
+		snapshot() {
+			// A path written after an earlier attempt was refused is written, so
+			// the successful set always wins the overlap.
+			return {
+				mutatedPaths: new Set(mutatedPaths),
+				failedMutationPaths: new Set([...failedMutationPaths].filter((target) => !mutatedPaths.has(target))),
+				validationCommands: new Set(validationCommands),
+				verificationCommands: new Set(verificationCommands),
+			};
+		},
+	};
+}

package/src/domains/safety/scope.ts

@@ -0,0 +1,61 @@
+import path from "node:path";
+import type { ActionClass } from "./action-classifier.js";
+
+/**
+ * Scope rules for worker-vs-orchestrator privilege checks. Phase 2 ships the
+ * shapes and the subset predicate. Phase 6 consumes isSubset at dispatch
+ * admission so a worker scope never escalates past the orchestrator.
+ */
+
+export interface ScopeSpec {
+	allowedActions: ReadonlySet<ActionClass>;
+	allowedWriteRoots: ReadonlyArray<string>;
+	allowNetwork: boolean;
+	allowDispatch: boolean;
+}
+
+function normalizeRoot(root: string): string {
+	return path.resolve(root);
+}
+
+function isUnder(child: string, parent: string): boolean {
+	const c = normalizeRoot(child);
+	const p = normalizeRoot(parent);
+	if (c === p) return true;
+	const rel = path.relative(p, c);
+	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+export function isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean {
+	for (const action of worker.allowedActions) {
+		if (!orchestrator.allowedActions.has(action)) return false;
+	}
+	for (const root of worker.allowedWriteRoots) {
+		const covered = orchestrator.allowedWriteRoots.some((outer) => isUnder(root, outer));
+		if (!covered) return false;
+	}
+	if (worker.allowNetwork && !orchestrator.allowNetwork) return false;
+	if (worker.allowDispatch && !orchestrator.allowDispatch) return false;
+	return true;
+}
+
+export const READONLY_SCOPE: ScopeSpec = {
+	allowedActions: new Set<ActionClass>(["read"]),
+	allowedWriteRoots: [],
+	allowNetwork: true,
+	allowDispatch: false,
+};
+
+export const WORKSPACE_SCOPE: ScopeSpec = {
+	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch"]),
+	allowedWriteRoots: [process.cwd()],
+	allowNetwork: true,
+	allowDispatch: true,
+};
+
+export const CONFIRMED_SCOPE: ScopeSpec = {
+	allowedActions: new Set<ActionClass>(["read", "write", "execute", "dispatch", "system_modify"]),
+	allowedWriteRoots: [process.cwd()],
+	allowNetwork: true,
+	allowDispatch: true,
+};

package/src/domains/scheduling/budget.ts

@@ -0,0 +1,35 @@
+/**
+ * Session budget state. checkCeiling reports whether the current spend is at
+ * or above the ceiling; dispatch admission stays informational for v0.1 per
+ * the Phase 10 scope, so the caller decides whether to enforce.
+ */
+
+export type BudgetVerdict = "under" | "at" | "over";
+
+export interface BudgetState {
+	ceilingUsd: number;
+	checkCeiling(currentUsd: number): BudgetVerdict;
+	raise(newCeilingUsd: number): void;
+}
+
+export function createBudgetState(initialCeilingUsd: number): BudgetState {
+	if (initialCeilingUsd < 0) throw new Error(`budget: ceiling must be >= 0 (got ${initialCeilingUsd})`);
+	let ceiling = initialCeilingUsd;
+
+	return {
+		get ceilingUsd() {
+			return ceiling;
+		},
+		checkCeiling(currentUsd) {
+			if (currentUsd > ceiling) return "over";
+			if (currentUsd === ceiling) return "at";
+			return "under";
+		},
+		raise(newCeilingUsd) {
+			if (newCeilingUsd < ceiling) {
+				throw new Error(`budget.raise: new ceiling ${newCeilingUsd} below current ${ceiling}`);
+			}
+			ceiling = newCeilingUsd;
+		},
+	};
+}