@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/tools/result-shaping.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { INSTRUCTION_SHAPED_WARNING } from "../core/untrusted-content.js";
 import { clioStateDir } from "../core/xdg.js";
 import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
 import {
@@ -24,7 +25,10 @@ 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" | "toolResultMaxBytes">;
+type ToolResultShapeContext = Pick<
+	ToolInvokeOptions,
+	"sessionId" | "toolCallId" | "toolResultMaxBytes" | "supportsImages"
+>;
 
 function mergeDetails(details: ToolResultDetails | undefined, resultSize: Record<string, unknown>): ToolResultDetails {
 	return { ...(details ?? {}), resultSize };
@@ -127,11 +131,17 @@ function offloadBody(text: string, bytes: number, maxBytes: number): string {
 	return `${truncateUtf8(text, Math.max(0, prefixBudget), "")}${notice}`;
 }
 
+export interface ToolOffloadSweepResult {
+	removed: number;
+	skipped: number;
+}
+
 /** Remove regular offload files older than the boot retention cap. */
-export function sweepExpiredToolOffloads(now = Date.now()): number {
+export function sweepExpiredToolOffloads(now = Date.now()): ToolOffloadSweepResult {
 	const root = join(clioStateDir(), "scratch");
 	const cutoff = now - TOOL_OFFLOAD_MAX_AGE_MS;
 	let removed = 0;
+	let skipped = 0;
 	try {
 		for (const session of readdirSync(root, { withFileTypes: true })) {
 			if (!session.isDirectory()) continue;
@@ -143,14 +153,20 @@ export function sweepExpiredToolOffloads(now = Date.now()): number {
 					if (statSync(path).mtimeMs >= cutoff) continue;
 					rmSync(path, { force: true });
 					removed += 1;
-				} catch {}
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+				}
 			}
 			try {
 				if (readdirSync(sessionDir).length === 0) rmdirSync(sessionDir);
-			} catch {}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+			}
 		}
-	} catch {}
-	return removed;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") skipped += 1;
+	}
+	return { removed, skipped };
 }
 
 /**
@@ -407,7 +423,7 @@ function withOffloadMetadata(
  * Apply legacy shaping or one declared canonical disposition. Registry calls
  * this once, after middleware annotations have produced the terminal result.
  */
-export function shapeToolResult(
+function shapeTextToolResultBody(
 	spec: ToolSpec,
 	result: ToolResult,
 	context?: ToolResultShapeContext,
@@ -507,3 +523,107 @@ export function shapeToolResult(
 		modelContext: projection.text,
 	};
 }
+
+/** Keep the harness warning visible even when the chosen projection omits the source body. */
+function shapeTextToolResult(
+	spec: ToolSpec,
+	result: ToolResult,
+	context?: ToolResultShapeContext,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResult {
+	const shaped = shapeTextToolResultBody(spec, result, context, requestedDisposition);
+	const warning = `[middleware:warn] ${INSTRUCTION_SHAPED_WARNING}`;
+	if (!resultText(result).includes(warning)) return shaped;
+	const hardMaxBytes = maxBytesFor(spec, context);
+	const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+	const preserve = (text: string, cap: number, tail: boolean): string => {
+		if (text.startsWith(warning) && byteLength(text) <= cap) return text;
+		const prefix = `${warning}\n\n`;
+		const remainder = text.split(warning).join("").trimStart();
+		const allowance = Math.max(0, cap - byteLength(prefix));
+		if (allowance === 0) return truncateUtf8(warning, cap, "");
+		const body = tail
+			? truncateTail(remainder, { maxBytes: allowance, maxLines: Number.MAX_SAFE_INTEGER }).content
+			: truncateUtf8(remainder, allowance, "");
+		return prefix + body;
+	};
+	const output = preserve(
+		resultText(shaped),
+		Math.min(hardMaxBytes, disposition?.presentation.maxBytes ?? hardMaxBytes),
+		disposition?.presentation.overflow === "tail",
+	);
+	const modelContext =
+		shaped.modelContext === undefined
+			? undefined
+			: preserve(
+					shaped.modelContext,
+					Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes),
+					disposition?.context.mode === "bounded" && disposition.context.excerpt === "tail",
+				);
+	const previous = existingDisposition(shaped.details);
+	const details = { ...shaped.details };
+	if (previous !== null)
+		details.resultDisposition = {
+			...previous,
+			presentation: { ...previous.presentation, content: output },
+			displayedBytes: byteLength(output),
+			contextBytes: byteLength(modelContext ?? output),
+			presentationTruncated: previous.presentationTruncated || byteLength(resultText(shaped)) > byteLength(output),
+			contextTruncated:
+				previous.contextTruncated || byteLength(shaped.modelContext ?? "") > byteLength(modelContext ?? ""),
+		};
+	const size = detailsRecord(shaped.details, "resultSize");
+	if (size !== null) details.resultSize = { ...size, shownBytes: byteLength(output) };
+	return {
+		...shaped,
+		...(shaped.kind === "ok" ? { output } : { message: output }),
+		...(modelContext === undefined ? {} : { modelContext }),
+		details,
+	};
+}
+
+/** Image bytes share the same payload cap as text, including after annotation. */
+export function shapeToolResult(
+	spec: ToolSpec,
+	result: ToolResult,
+	context?: ToolResultShapeContext,
+	requestedDisposition?: ToolResultDisposition,
+): ToolResult {
+	if (result.kind !== "ok" || !result.images?.length)
+		return shapeTextToolResult(spec, result, context, requestedDisposition);
+	const hardMaxBytes = maxBytesFor(spec, context);
+	const disposition = normalizeToolResultDisposition(spec, hardMaxBytes, requestedDisposition);
+	const maxBytes = Math.min(hardMaxBytes, disposition?.context.maxBytes ?? hardMaxBytes);
+	const images: NonNullable<typeof result.images> = [];
+	let imageBytes = 0;
+	for (const image of result.images) {
+		const bytes = byteLength(image.data);
+		if (
+			context?.supportsImages === true &&
+			disposition?.context.mode !== "metadata-only" &&
+			bytes + imageBytes < maxBytes - 512
+		) {
+			images.push(image);
+			imageBytes += bytes;
+		}
+	}
+	const omitted = result.images.length - images.length;
+	const notice =
+		omitted > 0 ? `[${omitted} image(s) omitted: model capability, context policy, or tool result byte cap.]\n` : "";
+	const remaining = Math.max(1, maxBytes - imageBytes);
+	const shaped = shapeTextToolResult(
+		spec,
+		{ ...result, output: notice + result.output, images },
+		{ ...context, toolResultMaxBytes: remaining },
+		requestedDisposition,
+	);
+	if (shaped.kind !== "ok") return shaped;
+	// Legacy truncation notices may extend beyond their text allowance; the image
+	// envelope has a strict combined cap, so bound the final projections too.
+	return {
+		...shaped,
+		images,
+		output: truncateUtf8(shaped.output, remaining, ""),
+		...(shaped.modelContext === undefined ? {} : { modelContext: truncateUtf8(shaped.modelContext, remaining, "") }),
+	};
+}

package/src/tools/task-worktree.ts

@@ -57,9 +57,19 @@ export function isCanonicalWorktreePathInside(parent: string, candidate: string)
 	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 
-export function commitWorktreePath(path: string, identity: string, message: string): boolean {
-	git(path, ["add", "-A"]);
-	if (git(path, ["status", "--porcelain"]).length === 0) return false;
+export function commitWorktreePath(
+	path: string,
+	identity: string,
+	message: string,
+	excludedPaths: ReadonlyArray<string> = [],
+): boolean {
+	// Runtime state can already be staged by a worker. Reset only these exact
+	// index entries, leaving their working files and every authored path intact.
+	if (excludedPaths.length > 0) {
+		git(path, ["reset", "-q", "HEAD", "--", ...excludedPaths.map((entry) => `:(top,literal)${entry}`)]);
+	}
+	git(path, ["add", "-A", "--", ".", ...excludedPaths.map((entry) => `:(top,exclude,literal)${entry}`)]);
+	if (git(path, ["diff", "--cached", "--name-only", "-z"]).length === 0) return false;
 	git(path, [
 		"-c",
 		`user.name=${identity}`,

package/src/tools/tasks.ts

@@ -47,7 +47,8 @@ function waitingTrailer(tasks: ReadonlyArray<UserTask>): string[] {
 		.filter((task) => task.status === "open" || task.status === "handed")
 		.map(
 			(task) =>
-				`operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} — pick up with action="pick" id="${task.id}"`,
+				`operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} — durable status=${task.status}; ` +
+				`not completed; pick only if this is the intended operator task, with action="pick" id="${task.id}" before work`,
 		);
 }
 
@@ -60,9 +61,30 @@ function renderTaskBoardText(board: TaskBoardSnapshot, userTasks: ReadonlyArray<
 		if (task.status === "blocked" && task.reason) line += ` — blocked: ${task.reason}`;
 		if (task.status === "cancelled" && task.reason) line += ` — dropped: ${task.reason}`;
 		lines.push(line);
+		const operatorTask = userTasks.find((item) => item.id === task.userTaskId);
+		if (task.userTaskId) {
+			lines.push(
+				`  operator task ${task.userTaskId}: durable status=${operatorTask?.status ?? "unavailable"}; ` +
+					`session=${operatorTask?.handedSessionId ?? "unlinked"}; board task=${operatorTask?.boardTaskId ?? "unlinked"}`,
+			);
+		}
+		const outputs = operatorTask?.acceptance?.expectedOutputs;
+		if (outputs?.length) lines.push(`  expected outputs: ${outputs.join(", ")}`);
+		for (const item of task.requiredValidationEvidence ?? []) {
+			if (item.status === "required") {
+				lines.push(
+					`  acceptance requirement: ${item.command} (${item.notes}; declaration only; execution status is in verification receipts)`,
+				);
+			} else {
+				lines.push(`  acceptance: ${item.command} (${item.status}; ${item.notes})`);
+			}
+		}
 	}
 	if (counts.open > 0 && counts.active === 0) {
-		lines.push(`next: start a task with action="start" before working it`);
+		lines.push(
+			`next: start only an authorized task with action="start" before working it; ` +
+				`block proposed implementation with a note naming the pending operator decision, or drop it, and wait`,
+		);
 	}
 	lines.push(...waitingTrailer(userTasks));
 	return lines.join("\n");
@@ -141,7 +163,12 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
 			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
-			"Work that did not happen is blocked or dropped, never done.",
+			"For an operator handoff, pick the intended uN before work and use its returned linked tN; CLI hand alone does not pick it. " +
+			"Never pick unrelated inbox tasks. Before claiming operator completion, list and confirm the linked board row is completed " +
+			"and the durable operator status is done with the same session/board link; report those IDs and actual states. " +
+			"Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. " +
+			"For proposal-only work, block deferred implementation with note naming the pending operator decision, or drop it; " +
+			"wait for an explicit operator go-ahead before start or implementation. A skill-install choice does not grant that go-ahead.",
 		parameters: Type.Object({
 			action: StringEnum(TASKS_ACTIONS, { description: "Board action." }),
 			title: Type.Optional(Type.String({ description: "Board title (plan)." })),
@@ -188,7 +215,10 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			if (typedAction === "list") {
 				const board = deps.board.snapshot();
 				if (!board) {
-					const output = ['no task board yet; declare one with action="plan"', ...waitingTrailer(userTasks)].join("\n");
+					const output = [
+						'no task board yet; for an operator handoff, pick the intended uN before work; otherwise declare one with action="plan"',
+						...waitingTrailer(userTasks),
+					].join("\n");
 					return {
 						kind: "ok",
 						output,
@@ -210,7 +240,12 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 				if (userTask.status !== "open" && userTask.status !== "handed") {
 					return { kind: "error", message: `tasks: operator task ${id} is ${userTask.status}; it cannot be picked` };
 				}
-				const result = deps.board.apply({ op: "pick", title: userTask.title, userTaskId: userTask.id });
+				const result = deps.board.apply({
+					op: "pick",
+					title: userTask.title,
+					userTaskId: userTask.id,
+					...(userTask.acceptance ? { verification: userTask.acceptance.verification } : {}),
+				});
 				if (!result.ok) return { kind: "error", message: `tasks: ${result.message}` };
 				const picked = result.board.tasks.find((task) => task.userTaskId === userTask.id && task.status === "pending");
 				if (!picked) return { kind: "error", message: `tasks: durable pickup for ${id} did not produce a board row` };