@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/tools/monitor.ts

@@ -2,6 +2,12 @@ import { readFileSync } from "node:fs";
 import { sleep } from "../core/timers.js";
 import { renderAgentLedgerBoard } from "../domains/dispatch/agent-ledger-store.js";
 import type { DurableAssignmentRecord } from "../domains/dispatch/assignment-store.js";
+import {
+	formatBudgetPolicy,
+	formatBudgetReasons,
+	formatBudgetRequest,
+	formatEffectiveBudget,
+} from "../domains/dispatch/budget-envelope.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import { UNVERIFIABLE_RECEIPT_VERIFICATION } from "../domains/dispatch/receipt-findings.js";
 import type { ReceiptIntegrityResult } from "../domains/dispatch/receipt-integrity.js";
@@ -117,6 +123,19 @@ function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 		`started=${run.startedAt} ended=${run.endedAt ?? "n/a"} exit=${run.exitCode ?? "n/a"}`,
 		`tokens=${run.tokenCount} cost=${formatCostAggregate(costAggregateForAmount(run.costUsd, run.costProvenance)) ?? COST_NOT_MEASURED} receipt=${run.receiptPath ?? "n/a"}`,
 	];
+	if (run.council !== undefined || run.gate?.role === "synthesis") {
+		lines.push(
+			`council: role=${run.gate?.role === "synthesis" ? "synthesis" : "member"} group=${run.council?.group ?? run.gate?.group ?? "unknown"}${run.council?.label ? ` label=${run.council.label}` : ""}`,
+		);
+	}
+	if (run.budget !== undefined) {
+		lines.push(
+			`recipe policy: ${formatBudgetPolicy(run.budget)}`,
+			`requested envelope: ${formatBudgetRequest(run.budget)}`,
+			`effective envelope: ${formatEffectiveBudget(run.budget)}`,
+			`clamp or escalation reason: ${formatBudgetReasons(run.budget)}`,
+		);
+	}
 	if (live) {
 		lines.push(
 			`live: phase=${live.outcomePhase} heartbeat=${live.heartbeat} elapsed=${Math.round(live.elapsedMs / 1000)}s tokens=${live.tokens.total}`,
@@ -143,6 +162,16 @@ function runStatus(deps: MonitorToolDeps, runId: string): ToolResult {
 			tokenCount: run.tokenCount,
 			costUsd: run.costUsd,
 			costProvenance: run.costProvenance ?? "unknown",
+			budget: run.budget ?? null,
+			...(run.council !== undefined || run.gate?.role === "synthesis"
+				? {
+						council: {
+							role: run.gate?.role === "synthesis" ? "synthesis" : "member",
+							group: run.council?.group ?? run.gate?.group ?? null,
+							...(run.council !== undefined ? { label: run.council.label, round: run.council.round } : {}),
+						},
+					}
+				: {}),
 			receiptPath: run.receiptPath,
 			running: live !== null,
 		},
@@ -363,6 +392,7 @@ function runReceipt(deps: MonitorToolDeps, runId: string): ToolResult {
 			...(receipt !== null && receiptIntegrity.ok
 				? {
 						evidenceVerification: receipt.verification,
+						hostVerification: receipt.hostVerification ?? null,
 						briefing: receipt.briefing ?? null,
 						projectContext: receipt.projectContext ?? null,
 					}
@@ -702,6 +732,7 @@ async function runCollect(
 					receiptIntegrity: row.evidence.integrity,
 					trustStatus: row.evidence.trustStatus,
 					evidenceVerification: row.evidence.verification,
+					hostVerification: row.evidence.receipt?.hostVerification ?? null,
 					briefing: row.evidence.receipt?.briefing ?? null,
 					projectContext: row.evidence.receipt?.projectContext ?? null,
 					...(output ? { output: { state: output.state, bytes: output.bytes, truncated: output.truncated } } : {}),

package/src/tools/profiles.ts

@@ -1,8 +1,13 @@
 import { type BuiltinToolName, isBuiltinToolName, type ToolName, ToolNames } from "../core/tool-names.js";
 
-export type ToolProfileName = "minimal-local" | "science-local" | "full-agent";
+export type ToolProfileName = "minimal-local" | "science-local" | "full-agent" | "council-read-only";
 
-export const TOOL_PROFILE_NAMES: ReadonlyArray<ToolProfileName> = ["minimal-local", "science-local", "full-agent"];
+export const TOOL_PROFILE_NAMES: ReadonlyArray<Exclude<ToolProfileName, "council-read-only">> = [
+	"minimal-local",
+	"science-local",
+	"full-agent",
+];
+const ALL_TOOL_PROFILE_NAMES: ReadonlyArray<ToolProfileName> = [...TOOL_PROFILE_NAMES, "council-read-only"];
 const CODEWIKI_TOOL_NAMES: ReadonlyArray<BuiltinToolName> = [ToolNames.CodeNav];
 
 export interface ToolProfileContext {
@@ -24,14 +29,23 @@ const MINIMAL_LOCAL_TOOLS: ReadonlyArray<BuiltinToolName> = [
 ];
 
 const SCIENCE_LOCAL_TOOLS: ReadonlyArray<BuiltinToolName> = [...MINIMAL_LOCAL_TOOLS, ToolNames.Verify];
+const COUNCIL_READ_ONLY_TOOLS: ReadonlyArray<BuiltinToolName> = [
+	ToolNames.Read,
+	ToolNames.Grep,
+	ToolNames.Find,
+	ToolNames.Ls,
+	ToolNames.CodeNav,
+	ToolNames.Context,
+];
 
 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),
+	"council-read-only": new Set(COUNCIL_READ_ONLY_TOOLS),
 };
 
 export function isToolProfileName(value: string): value is ToolProfileName {
-	return (TOOL_PROFILE_NAMES as ReadonlyArray<string>).includes(value);
+	return (ALL_TOOL_PROFILE_NAMES as ReadonlyArray<string>).includes(value);
 }
 
 /**
@@ -72,7 +86,7 @@ export function applyToolProfile(
 		const allowed = NARROW_TOOL_PROFILES[profile];
 		profiled = unique.filter((tool): tool is BuiltinToolName => isBuiltinToolName(tool) && allowed.has(tool));
 	}
-	return applyCodewikiWorkerPolicy(profiled, context);
+	return profile === "council-read-only" ? profiled : applyCodewikiWorkerPolicy(profiled, context);
 }
 
 function uniquePreservingOrder(tools: ReadonlyArray<ToolName>): ToolName[] {

package/src/tools/registry.ts

@@ -22,13 +22,14 @@ import {
 	mapAutonomy,
 } from "../domains/safety/autonomy.js";
 import type { SafetyContract, SafetyDecision } from "../domains/safety/contract.js";
+import type { DecisionPresentation } from "../domains/safety/decision-presentation.js";
 import { hashToolCall } from "../domains/safety/loop-detector.js";
 import { detectValidationCommand } from "../domains/safety/protected-artifacts.js";
 import { askUserExposure } from "./ask-user.js";
 import { type DispatchPlanView, describeDispatchPlan } from "./dispatch-plan.js";
 import type { ToolPresentationPolicy } from "./presentation.js";
-import type { ToolResultDisposition } from "./result-disposition.js";
-import { DEFAULT_TOOL_RESULT_MAX_BYTES, shapeToolResult } from "./result-shaping.js";
+import type { ToolResultDigest, ToolResultDisposition } from "./result-disposition.js";
+import { DEFAULT_TOOL_RESULT_MAX_BYTES, shapeToolResult, toolResultDigestFor } from "./result-shaping.js";
 
 /**
  * Tool registry. Admission point for every tool call. Delegates classification
@@ -200,6 +201,8 @@ export interface ToolInvokeOptions {
 	correlationId?: string;
 	pendingSkillPolicy?: PendingSkillToolPolicy;
 	askUserPolicy?: AskUserToolPolicy;
+	/** Host-derived display copy for an ask_user round. It has no admission authority. */
+	decisionPresentation?: DecisionPresentation;
 	/** Registry-authenticated one-shot operator approval for this execution. */
 	approval?: { requestId: string; requestedBy: string; actionClass: ActionClass };
 	/**
@@ -259,6 +262,8 @@ export interface AskUserToolPolicy {
 	sessionId?: string;
 	turnId?: string;
 	transcriptPath?: string;
+	/** Monotonic exposure fact for live presentation and durable replay. */
+	exposure?: AutonomyExposure;
 	summary?: string;
 	rounds: AskUserTranscriptRound[];
 	decisions: AskUserTranscriptDecision[];
@@ -421,13 +426,15 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 				const preparedArgs = prepareToolArgs(spec, call.args ?? {});
 				resultDisposition = resolveToolResultDisposition(spec, preparedArgs);
 				const result = await spec.run(preparedArgs, options);
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
+				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				const finalResult = shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition);
 				return { kind: "ok", result: finalResult, decision };
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
 				const result: ToolResult = { kind: "error", message };
-				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result);
+				const digest = toolResultDigestFor(spec, result, resultDisposition);
+				const afterEffects = runToolHook("after_tool", spec, call, decision, options, result, digest);
 				return {
 					kind: "ok",
 					result: shapeToolResult(spec, applyToolResultEffects(result, afterEffects), options, resultDisposition),
@@ -446,9 +453,10 @@ export function createRegistry(deps: RegistryDeps): ToolRegistry {
 		decision: SafetyDecision,
 		options: ToolInvokeOptions | undefined,
 		result?: ToolResult,
+		resultDigest?: ToolResultDigest,
 	): ReadonlyArray<MiddlewareEffect> => {
 		if (!deps.middleware) return [];
-		const input = buildToolHookInput(hook, spec, call, decision, "operating", options, result);
+		const input = buildToolHookInput(hook, spec, call, decision, "operating", options, result, resultDigest);
 		const effects = deps.middleware.runHook(input).effects;
 		try {
 			deps.onMiddlewareEffects?.(effects, input);
@@ -1135,6 +1143,7 @@ function buildToolHookInput(
 	posture: string,
 	options: ToolInvokeOptions | undefined,
 	result: ToolResult | undefined,
+	resultDigest: ToolResultDigest | undefined,
 ): MiddlewareHookInput {
 	const metadata: Record<string, MiddlewareMetadataValue> = {
 		posture,
@@ -1171,6 +1180,7 @@ function buildToolHookInput(
 	};
 	if (call.args !== undefined) input.toolArgs = call.args;
 	if (result?.details !== undefined) input.toolResultDetails = result.details;
+	if (resultDigest !== undefined) input.toolResultDigest = resultDigest;
 	if (options?.runId !== undefined) input.runId = options.runId;
 	if (options?.sessionId !== undefined) input.sessionId = options.sessionId;
 	if (options?.turnId !== undefined) input.turnId = options.turnId;

package/src/tools/result-disposition.ts

@@ -52,6 +52,23 @@ export interface ToolResultSummaryProvenance {
 	redactions?: number;
 }
 
+export const TOOL_RESULT_DIGEST_MAX_BYTES = 240;
+
+export interface ToolResultDigestProvenance {
+	producer: "code";
+	source: "canonical-result-disposition" | "legacy-fallback";
+	algorithm: "redacted-context-digest-v1" | "redacted-legacy-digest-v1";
+	contextMode?: AppliedToolResultContextMode;
+	summaryAlgorithm?: ToolResultSummaryProvenance["algorithm"];
+	redactions?: number;
+}
+
+/** A bounded diagnostic that is safe to pass to task memory. */
+export interface ToolResultDigest {
+	text: string;
+	provenance: ToolResultDigestProvenance;
+}
+
 export interface ToolResultDispositionMetadata {
 	version: 1;
 	applications: 1;
@@ -223,6 +240,14 @@ function capUtf8(text: string, maxBytes: number): string {
 	return byteLength(text) <= maxBytes ? text : utf8Prefix(text, maxBytes);
 }
 
+function capDigestUtf8(text: string, maxBytes: number): string {
+	if (byteLength(text) <= maxBytes) return text;
+	const marker = "…";
+	const markerBytes = byteLength(marker);
+	if (markerBytes >= maxBytes) return utf8Prefix(text, maxBytes);
+	return `${utf8Prefix(text, maxBytes - markerBytes).trimEnd()}${marker}`;
+}
+
 /** A deterministic, UTF-8-safe excerpt whose total bytes never exceed maxBytes. */
 function boundedToolResultExcerpt(text: string, maxBytes: number, bias: ToolResultExcerptBias = "head-tail"): string {
 	if (maxBytes <= 0) return "";
@@ -504,6 +529,137 @@ export function projectToolResultContext(input: ProjectToolResultContextInput):
 	};
 }
 
+const DIGEST_FACT_KEYS = [
+	"outcome",
+	"exitCode",
+	"timedOut",
+	"aborted",
+	"outputCapped",
+	"signal",
+	"status",
+	"error",
+	"decision",
+	"next",
+] as const;
+
+function digestFactText(details: ToolResultDetails | undefined): string {
+	if (details === undefined) return "";
+	const facts: string[] = [];
+	for (const key of DIGEST_FACT_KEYS) {
+		if (details[key] !== undefined) facts.push(`${key}=${stableJson(details[key])}`);
+	}
+	return facts.join(" ");
+}
+
+function projectionBody(input: ProjectToolResultContextInput, projection: ToolResultContextProjection): string {
+	if (projection.appliedMode === "metadata-only") return "";
+	if (projection.appliedMode === "full") {
+		const trailer = fullTrailer(input);
+		return trailer.length > 0 && projection.text.endsWith(`\n\n${trailer}`)
+			? projection.text.slice(0, -(trailer.length + 2))
+			: projection.text;
+	}
+	const header = contextHeader(input, projection.appliedMode, projection.truncated, projection.summaryProvenance);
+	const prefix = `${header}\n`;
+	return projection.text.startsWith(prefix) ? projection.text.slice(prefix.length) : "";
+}
+
+function digestText(
+	status: string,
+	facts: string,
+	body: string,
+	redactions: number,
+	maxBytes: number,
+): { text: string; redactions: number } {
+	const tally = createRedactionTally();
+	const safeStatus = redactSecretsText(status, tally);
+	const safeFacts = redactSecretsText(facts, tally);
+	const statusAndFacts = [safeStatus, safeFacts].filter((value) => value.length > 0).join(" ");
+	const bodyBudget = Math.max(0, maxBytes - byteLength(statusAndFacts) - 2);
+	const selected = deterministicDiagnosticSummary(body, bodyBudget, true);
+	const candidate = [statusAndFacts, selected.text.replace(/\s+/gu, " ").trim()]
+		.filter((value) => value.length > 0)
+		.join("; ");
+	return {
+		text: capDigestUtf8(candidate, maxBytes),
+		redactions: redactions + tally.count + selected.redactions,
+	};
+}
+
+/**
+ * Reuse the applied model-context projection as task memory's diagnostic
+ * source. Metadata-only never contributes captured content, and bounded or
+ * summarized modes contribute only the body admitted by that projection.
+ */
+export function deterministicToolResultDigest(
+	input: ProjectToolResultContextInput,
+	maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES,
+): ToolResultDigest {
+	const projection = projectToolResultContext(input);
+	const status = [
+		`kind=${input.kind}`,
+		`mode=${projection.appliedMode}`,
+		`truncated=${String(projection.truncated)}`,
+		...(projection.appliedMode === "metadata-only" || projection.truncated
+			? [`capturedBytes=${input.capturedBytes}`]
+			: []),
+	].join(" ");
+	const digest = digestText(
+		status,
+		digestFactText(input.details),
+		projectionBody(input, projection),
+		projection.summaryProvenance?.redactions ?? 0,
+		Math.max(1, Math.floor(maxBytes)),
+	);
+	return {
+		text: digest.text,
+		provenance: {
+			producer: "code",
+			source: "canonical-result-disposition",
+			algorithm: "redacted-context-digest-v1",
+			contextMode: projection.appliedMode,
+			...(projection.summaryProvenance === undefined ? {} : { summaryAlgorithm: projection.summaryProvenance.algorithm }),
+			...(digest.redactions > 0 ? { redactions: digest.redactions } : {}),
+		},
+	};
+}
+
+/** Deterministic compatibility path for results without a canonical disposition. */
+export function legacyToolResultDigest(
+	text: string,
+	options: { outcome: "ok" | "error"; maxBytes?: number },
+): ToolResultDigest {
+	const maxBytes = Math.max(1, Math.floor(options.maxBytes ?? TOOL_RESULT_DIGEST_MAX_BYTES));
+	const fallback = options.outcome === "error" && text.trim().length === 0 ? "an unknown tool error" : text;
+	const digest = digestText("", "", fallback, 0, maxBytes);
+	return {
+		text: digest.text,
+		provenance: {
+			producer: "code",
+			source: "legacy-fallback",
+			algorithm: "redacted-legacy-digest-v1",
+			...(digest.redactions > 0 ? { redactions: digest.redactions } : {}),
+		},
+	};
+}
+
+/** Reapply the memory boundary's redaction and byte cap to a supplied digest. */
+export function sanitizeToolResultDigest(
+	digest: ToolResultDigest,
+	maxBytes = TOOL_RESULT_DIGEST_MAX_BYTES,
+): ToolResultDigest {
+	const tally = createRedactionTally();
+	const safe = redactSecretsText(digest.text, tally).replace(/\s+/gu, " ").trim();
+	const redactions = (digest.provenance.redactions ?? 0) + tally.count;
+	return {
+		text: capDigestUtf8(safe, Math.max(1, Math.floor(maxBytes))),
+		provenance: {
+			...digest.provenance,
+			...(redactions > 0 ? { redactions } : {}),
+		},
+	};
+}
+
 /** The text inserted into the provider conversation for a registry result. */
 export function toolResultContextText(result: ToolResult): string {
 	if (result.modelContext !== undefined) return result.modelContext;

package/src/tools/result-shaping.ts

@@ -1,11 +1,14 @@
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { clioStateDir } from "../core/xdg.js";
 import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
 import {
+	deterministicToolResultDigest,
+	legacyToolResultDigest,
 	normalizeToolResultDisposition,
 	projectToolResultContext,
+	type ToolResultDigest,
 	type ToolResultDisposition,
 	type ToolResultDispositionFallback,
 	type ToolResultDispositionMetadata,
@@ -21,6 +24,7 @@ export const DEFAULT_TOOL_RESULT_MAX_BYTES = DEFAULT_MAX_BYTES + 2 * 1024;
 const RESULT_TRUNCATION_MARKER = "\n[tool result truncated]";
 const RESULT_OFFLOAD_MAX_BYTES = 10 * 1024 * 1024;
 const TAIL_NOTICE_RESERVE_BYTES = 512;
+export const TOOL_OFFLOAD_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
 
 type ToolResultShapeContext = Pick<ToolInvokeOptions, "sessionId" | "toolCallId">;
 
@@ -49,6 +53,34 @@ function offloadMaxBytesFor(spec: ToolSpec): number {
 		: RESULT_OFFLOAD_MAX_BYTES;
 }
 
+/**
+ * Build the task-memory diagnostic from the same normalized disposition that
+ * will shape model context. Legacy tools use the explicit compatibility path.
+ */
+export function toolResultDigestFor(
+	spec: ToolSpec,
+	result: ToolResult,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResultDigest {
+	const text = resultText(result);
+	const disposition = normalizeToolResultDisposition(spec, maxBytesFor(spec), requestedDisposition);
+	if (disposition === null) {
+		const projected = shapeLegacyToolResult(spec, result);
+		return legacyToolResultDigest(resultText(projected), { outcome: result.kind });
+	}
+	const capturedBytes = capturedBytesFor(result, text);
+	return deterministicToolResultDigest({
+		text,
+		kind: result.kind,
+		details: result.details,
+		disposition,
+		capturedBytes,
+		displayedBytes: Math.min(capturedBytes, disposition.presentation.maxBytes),
+		offloadPath: existingOffloadPath(result.details),
+		followUpHint: followUpHint(spec),
+	});
+}
+
 function detailsRecord(details: ToolResultDetails | undefined, key: string): Record<string, unknown> | null {
 	const candidate = details?.[key];
 	return candidate !== null && typeof candidate === "object" && !Array.isArray(candidate)
@@ -91,6 +123,32 @@ function offloadBody(text: string, bytes: number, maxBytes: number): string {
 	return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
 }
 
+/** Remove regular offload files older than the boot retention cap. */
+export function sweepExpiredToolOffloads(now = Date.now()): number {
+	const root = join(clioStateDir(), "scratch");
+	const cutoff = now - TOOL_OFFLOAD_MAX_AGE_MS;
+	let removed = 0;
+	try {
+		for (const session of readdirSync(root, { withFileTypes: true })) {
+			if (!session.isDirectory()) continue;
+			const sessionDir = join(root, session.name);
+			for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+				if (!entry.isFile()) continue;
+				const path = join(sessionDir, entry.name);
+				try {
+					if (statSync(path).mtimeMs >= cutoff) continue;
+					rmSync(path, { force: true });
+					removed += 1;
+				} catch {}
+			}
+			try {
+				if (readdirSync(sessionDir).length === 0) rmdirSync(sessionDir);
+			} catch {}
+		}
+	} catch {}
+	return removed;
+}
+
 /**
  * Persist the full text of a tool result to a per-session scratch file and
  * return its path (or null if the write fails). Self-shaping callers use this