@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/cli/modes/json-stream.ts

@@ -57,6 +57,8 @@ export function projectHeadlessJsonEvent(event: ChatLoopEvent): unknown | null {
  * Only an assistant message streams: its `text` and `thinking` blocks arrive
  * incrementally as `text_delta` and `thinking_delta` keyed by the same
  * `contentIndex` this array is indexed by, so a reader reassembles them itself.
+ * Provider replay signatures stay in the durable session, not this observation
+ * stream; encrypted signatures can dwarf the actual answer on every turn.
  * `toolCall` blocks never stream and are kept whole. A `user` or `toolResult`
  * message is returned untouched, because no delta ever carried it.
  */
@@ -65,11 +67,11 @@ function withoutStreamedContent<T>(message: T): T {
 	const content = message.content.map((block: unknown) => {
 		if (!isRecord(block)) return block;
 		if (block.type === "text" && typeof block.text === "string") {
-			const { text: _text, ...rest } = block;
+			const { text: _text, textSignature: _signature, ...rest } = block;
 			return { ...rest, streamed: true, textLength: block.text.length };
 		}
 		if (block.type === "thinking" && typeof block.thinking === "string") {
-			const { thinking: _thinking, ...rest } = block;
+			const { thinking: _thinking, thinkingSignature: _signature, ...rest } = block;
 			return { ...rest, streamed: true, thinkingLength: block.thinking.length };
 		}
 		return block;

package/src/cli/modes/print.ts

@@ -1,4 +1,4 @@
-import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
+import { readClioVersion } from "../../core/package-root.js";
 import {
 	addResponseModelIdObservationCounts,
 	emptyResponseModelIdObservationCounts,
@@ -10,13 +10,27 @@ import {
 	skillActivationFromToolDetails,
 } from "../../core/skill-activation.js";
 import { getTerminationCoordinator } from "../../core/termination.js";
-import { ToolNames } from "../../core/tool-names.js";
+import { type BuiltinToolName, ToolNames } from "../../core/tool-names.js";
+import type { TurnConstraints } from "../../core/turn-constraints.js";
+import { runStatusForOutcome } from "../../domains/dispatch/outcome.js";
 import { createRunReceiptQuality } from "../../domains/dispatch/receipt-findings.js";
 import { newRunId, openLedger } from "../../domains/dispatch/state.js";
-import type { RunKind, RunOutcome, RunReceiptDraft, RunStatus, ToolCallStat } from "../../domains/dispatch/types.js";
+import type {
+	RunKind,
+	RunOutcome,
+	RunReceiptDraft,
+	RunReceiptSafetySummary,
+	RunStatus,
+	SafetyBlockedAttempt,
+	ToolCallStat,
+} from "../../domains/dispatch/types.js";
+import type { ActionClass } from "../../domains/safety/action-classifier.js";
+import { readPiMonoVersion } from "../../engine/pi-mono-names.js";
 import type { AgentMessage, ImageContent } from "../../engine/types.js";
+import type { HeadlessRunDeadline } from "../../entry/boot-options.js";
 import type { ChatLoop, ChatLoopEvent } from "../../interactive/chat-loop.js";
 import { type RunUsageSummary, sumRunUsage } from "../../interactive/chat-loop-messages.js";
+import { TOOL_PLANES } from "../../tools/policy.js";
 import { flushRawStdout, writeRawStdout } from "../output-guard.js";
 import { setupSteerChannel } from "../steer-channel.js";
 import { projectHeadlessJsonEvent } from "./json-stream.js";
@@ -46,6 +60,7 @@ export interface HeadlessShutdownHooks {
 
 export interface HeadlessMainAgentOptions {
 	prompt: string;
+	constraints?: TurnConstraints;
 	images?: ReadonlyArray<ImageContent>;
 	workingContextPaths?: ReadonlyArray<string>;
 	sampling?: HeadlessSamplingOverrides;
@@ -55,6 +70,17 @@ export interface HeadlessMainAgentOptions {
 	steerChannel?: string;
 	getSessionHeader?: () => unknown | null;
 	shutdown?: HeadlessShutdownHooks;
+	/**
+	 * Also fail when all attempted tools failed without a block. Blocked runs
+	 * without recovery or a successful write, and explicit limitations, fail unconditionally.
+	 */
+	failOnNoop?: boolean;
+	/**
+	 * `clio-coder run --timeout`. When it expired, the shutdown it started seals
+	 * outcome `timed_out` instead of `canceled`, so a driver can tell its own
+	 * wall-clock limit from an external signal.
+	 */
+	deadline?: HeadlessRunDeadline;
 }
 
 interface HeadlessMainAgentResult {
@@ -93,6 +119,56 @@ interface HeadlessMainAgentReceiptStats {
 	toolStats: Map<string, ToolCallStat>;
 	skillActivations: SkillActivation[];
 	usage: RunUsageSummary | null;
+	/** The decision axis, counted the way a worker receipt counts it. */
+	decisions: RunReceiptSafetySummary["decisions"];
+	/** Every call whose outcome was blocked, in the worker receipt's shape, up to `BLOCKED_ATTEMPTS_LIMIT`. */
+	blockedAttempts: SafetyBlockedAttempt[];
+	/** Blocked attempts past `BLOCKED_ATTEMPTS_LIMIT`, counted but not listed. */
+	blockedAttemptsTruncated: number;
+	/** Successful calls the registry classified as `MUTATING_ACTION_CLASS`. */
+	mutatingSucceeded: number;
+	/** Blocked action classes not followed by successful substantive work of that class. */
+	unresolvedBlocks: Set<string>;
+}
+
+/**
+ * The registry action class a successful call must carry to count as a
+ * mutation for the no-op rule. It is the class autonomy `auto-edit` runs
+ * without asking (`mapAutonomy` in domains/safety/autonomy.ts): write, edit,
+ * and an outward web_fetch. The class comes from the registry's own admission
+ * of each call, so an extension tool that declares a write base class counts
+ * too. `execute` is left out on purpose: a shell command's class says that it
+ * ran, not that it wrote, and counting it would let one successful
+ * `git status` after a denied write hide the no-op this rule exists to catch.
+ * A terminating result is left out too (see `recordToolEnd`).
+ */
+const MUTATING_ACTION_CLASS: ActionClass = "write";
+
+/**
+ * Bounds on `safety.blockedAttempts`. A model retrying a denied call appends
+ * an entry per attempt, each carrying the full rejection text, so the list is
+ * capped and each reason clipped. Attempts past the cap are counted in
+ * `safety.blockedAttemptsTruncated`; the per-tool blocked counts in
+ * `toolStats` stay exact either way.
+ */
+export const BLOCKED_ATTEMPTS_LIMIT = 50;
+export const BLOCKED_ATTEMPT_REASON_MAX_CHARS = 500;
+
+/** Append one blocked attempt within the receipt bounds above. */
+export function recordBlockedAttempt(
+	stats: { blockedAttempts: SafetyBlockedAttempt[]; blockedAttemptsTruncated: number },
+	attempt: SafetyBlockedAttempt,
+): void {
+	if (stats.blockedAttempts.length >= BLOCKED_ATTEMPTS_LIMIT) {
+		stats.blockedAttemptsTruncated += 1;
+		return;
+	}
+	const reason = attempt.reason;
+	stats.blockedAttempts.push(
+		reason !== undefined && reason.length > BLOCKED_ATTEMPT_REASON_MAX_CHARS
+			? { ...attempt, reason: `${reason.slice(0, BLOCKED_ATTEMPT_REASON_MAX_CHARS)}…` }
+			: attempt,
+	);
 }
 
 function assistantText(message: AgentMessage | undefined): string {
@@ -193,6 +269,74 @@ function recordToolEnd(stats: HeadlessMainAgentReceiptStats, event: ChatLoopEven
 		else stat.ok += 1;
 	}
 	stats.toolStats.set(tool, stat);
+	// Safety bookkeeping mirrors the worker receipt's fold of its own tool
+	// finish events (domains/dispatch/extension.ts), so the two receipts carry
+	// the same facts under the same names.
+	const detail = event as {
+		ruleId?: unknown;
+		reasonCode?: unknown;
+		policySource?: unknown;
+		blockReason?: unknown;
+		deniedPark?: unknown;
+	};
+	const decision = (event as { decision?: unknown }).decision;
+	// A call that parked for approval and was denied because a headless run has
+	// no operator arrives as a registry block: parkAnsweredBlockedVerdict
+	// rewrites the ask. The summary's contract counts that call as a permission
+	// request, which is where a worker's non-interactive denial lands, so the
+	// registry's `deniedPark` flag routes it there. The flag, not the reason
+	// text, is the signal: the loop guard replaces the reason of a repeated
+	// denied call with its own guidance. `decisions.blocked` keeps meaning a
+	// hard block by a rule or a guard.
+	const deniedAsk = decision === "blocked" && detail.deniedPark === true;
+	if (decision === "allowed") stats.decisions.allowed += 1;
+	else if (decision === "permission_requested" || deniedAsk) stats.decisions.permissionRequested += 1;
+	else if (decision === "blocked") stats.decisions.blocked += 1;
+	const actionClass = (event as { actionClass?: unknown }).actionClass;
+	if (outcome === "blocked" || decision === "blocked") {
+		const attempt: SafetyBlockedAttempt = { tool };
+		if (typeof actionClass === "string") attempt.actionClass = actionClass;
+		if (typeof detail.ruleId === "string") attempt.ruleId = detail.ruleId;
+		if (typeof detail.reasonCode === "string") attempt.reasonCode = detail.reasonCode;
+		if (typeof detail.policySource === "string") attempt.policySource = detail.policySource;
+		if (typeof detail.blockReason === "string") attempt.reason = detail.blockReason;
+		recordBlockedAttempt(stats, attempt);
+	}
+	// A terminating result (the artifact tool's plan, review, or report) is the
+	// turn's answer written to a file, not the workspace change the task asked
+	// for. Counting it let a run whose every edit was blocked seal as a success
+	// by writing a report about the failure. `terminate` is the registry's own
+	// marker for that kind of result and survives the gateway hop, where the
+	// call's tool name is `gateway` rather than `artifact`.
+	const terminating = (event.result as { terminate?: unknown } | undefined)?.terminate === true;
+	const action = typeof actionClass === "string" ? actionClass : "unknown";
+	if (outcome === "blocked" || decision === "blocked") {
+		stats.unresolvedBlocks.add(action);
+	} else if (outcome === "ok" || (outcome === undefined && !event.isError)) {
+		const capability =
+			tool === ToolNames.Gateway
+				? (event.result as { details?: { capability?: unknown } } | undefined)?.details?.capability
+				: tool;
+		const plane =
+			typeof capability === "string" && Object.hasOwn(TOOL_PLANES, capability)
+				? TOOL_PLANES[capability as BuiltinToolName].plane
+				: undefined;
+		// A later alternate read/command can recover its blocked action class.
+		// Bookkeeping, discovery, limitation, and terminal reports cannot.
+		if (
+			!terminating &&
+			capability !== ToolNames.Context &&
+			capability !== ToolNames.CredentialPresent &&
+			(plane === "observe" || plane === "retrieve" || plane === "execute" || plane === "mutate")
+		) {
+			stats.unresolvedBlocks.delete(action);
+			// A read may be useful progress after a denied command, but cannot
+			// attest that command's requirement (for example a test) was met.
+			// An independent task verifier can accept an alternate workflow;
+			// this event fold has no authority to infer semantic substitution.
+		}
+	}
+	if (outcome === "ok" && actionClass === MUTATING_ACTION_CLASS && !terminating) stats.mutatingSucceeded += 1;
 	if (tool === ToolNames.Context) {
 		const rawTurnId = (event as { turnId?: unknown }).turnId;
 		const turnId = typeof rawTurnId === "string" ? rawTurnId : undefined;
@@ -226,6 +370,38 @@ function addRunUsage(left: RunUsageSummary, right: RunUsageSummary): RunUsageSum
 	};
 }
 
+/**
+ * Ticket #378: a run whose every write was denied, and whose model then wrote
+ * an apology, used to seal as a success. The receipt now says so in one bit.
+ * A run is a no-op when a block remains unresolved and no mutating call succeeded, or
+ * when it ran tools and none of them succeeded. A run that called no tool and
+ * answered in prose is not a no-op; answering a question is a legitimate run.
+ */
+function headlessNoop(stats: HeadlessMainAgentReceiptStats): boolean {
+	const totals = toolTotals(stats.toolStats);
+	if (stats.unresolvedBlocks.size > 0 && stats.mutatingSucceeded === 0) return true;
+	return totals.calls > 0 && totals.succeeded === 0;
+}
+
+function toolTotals(stats: Map<string, ToolCallStat>): { calls: number; succeeded: number; blocked: number } {
+	const totals = { calls: 0, succeeded: 0, blocked: 0 };
+	for (const stat of stats.values()) {
+		totals.calls += stat.count;
+		totals.succeeded += stat.ok;
+		totals.blocked += stat.blocked;
+	}
+	return totals;
+}
+
+function noopFailureMessage(stats: HeadlessMainAgentReceiptStats, failOnNoop: boolean): string {
+	const totals = toolTotals(stats.toolStats);
+	const cause =
+		stats.unresolvedBlocks.size > 0 && stats.mutatingSucceeded === 0
+			? `${totals.blocked} tool call${totals.blocked === 1 ? " was" : "s were"} blocked without recovery and no write succeeded`
+			: `${totals.calls} tool call${totals.calls === 1 ? "" : "s"} ran and none succeeded`;
+	return `clio-coder run: no-op${failOnNoop ? " under --fail-on-noop" : ""}: ${cause}`;
+}
+
 function sortedToolStats(stats: Map<string, ToolCallStat>): ToolCallStat[] {
 	return [...stats.values()].sort((a, b) => (a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0));
 }
@@ -274,6 +450,8 @@ interface HeadlessTerminalOutcome {
 	outcome: RunOutcome;
 	status: RunStatus;
 	failureMessage: string | null;
+	/** Machine-readable receipt detail; absent means the failure message is the detail. */
+	outcomeDetail?: string;
 }
 
 async function recordHeadlessMainAgentReceipt(input: {
@@ -297,7 +475,7 @@ async function recordHeadlessMainAgentReceipt(input: {
 	const reasoningTokenCount = usage?.reasoning ?? 0;
 	const costUsd = usage?.costUsd ?? 0;
 	const { exitCode, outcome, status } = input.terminal;
-	const outcomeDetail = input.terminal.failureMessage;
+	const outcomeDetail = input.terminal.outcomeDetail ?? input.terminal.failureMessage;
 	const ledger = openLedger();
 	const envelope = ledger.create({
 		id: input.runId,
@@ -389,6 +567,16 @@ async function recordHeadlessMainAgentReceipt(input: {
 		toolStats,
 		skillActivations: input.stats.skillActivations,
 		autonomyEnforcement: { grade: "mediated", autonomy: snapshot.autonomy },
+		// Sealed on every main-agent receipt, flag or no flag, so a driver can
+		// apply its own no-op rule to a run that exited 0.
+		safety: {
+			decisions: { ...input.stats.decisions },
+			blockedAttempts: [...input.stats.blockedAttempts],
+			...(input.stats.blockedAttemptsTruncated > 0
+				? { blockedAttemptsTruncated: input.stats.blockedAttemptsTruncated }
+				: {}),
+		},
+		noop: headlessNoop(input.stats),
 		...(snapshot.runtimeResolution ? { runtimeResolution: snapshot.runtimeResolution } : {}),
 		sessionId: snapshot.sessionId ?? input.chat.getSessionId(),
 	};
@@ -425,6 +613,11 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 		toolStats: new Map<string, ToolCallStat>(),
 		skillActivations: [],
 		usage: null,
+		decisions: { allowed: 0, blocked: 0, permissionRequested: 0 },
+		blockedAttempts: [],
+		blockedAttemptsTruncated: 0,
+		mutatingSucceeded: 0,
+		unresolvedBlocks: new Set<string>(),
 	};
 	// The receipt is this run's accounting, so it has to exist on the costly
 	// failure paths too. Two callers can reach it: the turn's own completion
@@ -457,12 +650,23 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 	// completion path and this hook race. Interruption is a fact both read from
 	// the coordinator rather than a winner of that race: whichever seals first
 	// seals the same canceled outcome.
-	const interruptedTerminal = (): HeadlessTerminalOutcome => ({
-		exitCode: termination.getExitCode(),
-		outcome: "canceled",
-		status: "interrupted",
-		failureMessage: result.abortReason ?? "clio-coder run: interrupted before the turn completed",
-	});
+	const interruptedTerminal = (): HeadlessTerminalOutcome =>
+		options.deadline?.expired() === true
+			? {
+					exitCode: termination.getExitCode(),
+					outcome: "timed_out",
+					// The status a dispatched worker's timed_out receipt seals with.
+					// Orphan recovery re-derives the status from the outcome with
+					// this same mapping when it re-verifies a receipt.
+					status: runStatusForOutcome("timed_out"),
+					failureMessage: `clio-coder run: timed out after ${options.deadline.seconds}s (--timeout)`,
+				}
+			: {
+					exitCode: termination.getExitCode(),
+					outcome: "canceled",
+					status: "interrupted",
+					failureMessage: result.abortReason ?? "clio-coder run: interrupted before the turn completed",
+				};
 	// Registered after the composition root's chat drain hook, which disposes
 	// the loop and awaits settlement, so the stats folded below are final by
 	// the time this runs.
@@ -543,6 +747,7 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 	try {
 		if (mode === "json" && jsonEvents === "terminal") writeTerminalTurnStart();
 		const submitOptions = {
+			...(options.constraints ? { constraints: options.constraints } : {}),
 			hostRun: { runId, lineage: { parentRunId: null, rootRunId: runId, depth: 0, attempt: 0 } },
 			...(options.images && options.images.length > 0 ? { images: options.images } : {}),
 			...(options.workingContextPaths && options.workingContextPaths.length > 0
@@ -566,6 +771,11 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 		}
 		unsubscribe();
 	}
+	// The turn has settled. Nothing between here and the seal yields to a
+	// timer, so a deadline that has not fired by now never will, and one that
+	// did has already put the coordinator into shutdown, which the first branch
+	// below reads.
+	options.deadline?.settle();
 
 	const endedAt = new Date().toISOString();
 	let terminal: HeadlessTerminalOutcome = {
@@ -601,23 +811,40 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 		stderrMessage = failureMessage;
 		if (mode === "text" && result.text.length > 0) stdoutMessage = result.text;
 	} else if (result.text.length === 0 && !result.sawTerminatingToolResult) {
-		const failureMessage =
-			result.lastNotice !== null
-				? `clio-coder run: no assistant response (${result.lastNotice})`
-				: "clio-coder run: no assistant response";
+		const failureMessage = "clio-coder run: provider stream ended without an assistant response or terminal tool result";
 		terminal = { exitCode: 1, outcome: "failed", status: "failed", failureMessage };
 		stderrMessage = failureMessage;
-	} else if (mode === "text") {
-		// A terminating tool ends the turn in place of an assistant message, so its
-		// result is the answer and any assistant text before it is mid-workflow
-		// chatter the model never offered as a reply. Printing that chatter instead
-		// hands the operator a dangling "let me try..." for a turn that succeeded.
-		stdoutMessage =
-			result.sawTerminatingToolResult && result.terminatingToolText.length > 0
-				? result.terminatingToolText
-				: result.text.length > 0
-					? result.text
-					: null;
+	} else {
+		// A normal provider stop does not erase an explicit limitation or a
+		// block with no applied change. Judge settled tool outcomes, not prose
+		// or the presence of a validation contract. Recovered failures may succeed.
+		const limited = (receiptStats.toolStats.get(ToolNames.Limitation)?.ok ?? 0) > 0;
+		const blockedWithoutChange = receiptStats.unresolvedBlocks.size > 0 && receiptStats.mutatingSucceeded === 0;
+		if (limited || blockedWithoutChange || (options.failOnNoop === true && headlessNoop(receiptStats))) {
+			const failureMessage = limited
+				? "clio-coder run: the agent recorded an explicit limitation; the task is incomplete"
+				: noopFailureMessage(receiptStats, options.failOnNoop === true);
+			terminal = {
+				exitCode: 1,
+				outcome: "failed",
+				status: "failed",
+				failureMessage,
+				outcomeDetail: limited ? "limitation" : "noop",
+			};
+			stderrMessage = failureMessage;
+		}
+		if (mode === "text") {
+			// A terminating tool ends the turn in place of an assistant message, so its
+			// result is the answer and any assistant text before it is mid-workflow
+			// chatter the model never offered as a reply. Printing that chatter instead
+			// hands the operator a dangling "let me try..." for a turn that succeeded.
+			stdoutMessage =
+				result.sawTerminatingToolResult && result.terminatingToolText.length > 0
+					? result.terminatingToolText
+					: result.text.length > 0
+						? result.text
+						: null;
+		}
 	}
 	const exitCode = terminal.exitCode;