@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/worker-receipts.ts

@@ -13,7 +13,8 @@
  * to take down a render.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { clioStateDir } from "../core/xdg.js";
 import { receiptFilePath } from "./view/artifacts.js";
 import type { WorkerReceiptFacts, WorkerResultContract } from "./worker-stream.js";
@@ -83,8 +84,8 @@ export function workerReceiptFacts(receipt: Record<string, unknown>): WorkerRece
 	};
 }
 
-/** Read and project `<state>/receipts/<runId>.json`; null when it is absent or unreadable. */
-export function readWorkerReceiptFacts(runId: string, stateDir = clioStateDir()): WorkerReceiptFacts | null {
+/** Read and project `<state>/receipts/<runId>.json` alone; null when it is absent or unreadable. */
+function readReceiptFileFacts(runId: string, stateDir: string): WorkerReceiptFacts | null {
 	try {
 		const parsed: unknown = JSON.parse(readFileSync(receiptFilePath(stateDir, runId), "utf8"));
 		return isRecord(parsed) ? workerReceiptFacts(parsed) : null;
@@ -92,3 +93,51 @@ export function readWorkerReceiptFacts(runId: string, stateDir = clioStateDir())
 		return null;
 	}
 }
+
+/** Read and project `<state>/receipts/<runId>.json`; null when it is absent or unreadable. */
+export function readWorkerReceiptFacts(runId: string, stateDir = clioStateDir()): WorkerReceiptFacts | null {
+	return readReceiptFileFacts(runId, stateDir);
+}
+
+/**
+ * The subset of a `runs.json` row replay needs once a receipt has failed to
+ * read: whether the run is still open, and, if the ledger closed it early
+ * (`closeAbandonedRows`), the closing row's own explanation.
+ */
+function findRunRow(runId: string, stateDir: string): Record<string, unknown> | null {
+	const path = join(stateDir, "runs.json");
+	if (!existsSync(path)) return null;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!Array.isArray(parsed)) return null;
+		for (const entry of parsed) {
+			if (isRecord(entry) && entry.id === runId) return entry;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Replay-only receipt reader: falls back to the run's own `runs.json` row
+ * when no receipt was sealed for it, so a resumed transcript can tell a run
+ * still going in another process, one the ledger closed as dead/stalled
+ * before it could seal a receipt, and one whose evidence is genuinely gone
+ * apart from each other. Never used by the live subscription: there, a
+ * missing receipt at settle time is a flush race the terminal event's own
+ * payload already covers (`worker-stream.ts`'s `settle`), not an open run.
+ */
+export function readWorkerReceiptFactsForReplay(runId: string, stateDir = clioStateDir()): WorkerReceiptFacts | null {
+	const sealed = readReceiptFileFacts(runId, stateDir);
+	if (sealed !== null) return sealed;
+	const row = findRunRow(runId, stateDir);
+	if (row === null) return null;
+	if (row.endedAt === null || row.endedAt === undefined) return { outcome: "running", stillRunning: true };
+	const outcome = optionalString(row.outcome) ?? optionalString(row.status) ?? "unknown";
+	const abandonedDetail = optionalString(row.outcomeDetail);
+	return {
+		outcome,
+		...(abandonedDetail !== undefined ? { abandonedDetail } : {}),
+	};
+}

package/src/interactive/worker-stream.ts

@@ -64,8 +64,12 @@ export interface WorkerReceiptSummary {
 	contract?: WorkerResultContract;
 	/** From an abort marker rather than a sealed terminal event; a later DispatchCompleted/DispatchFailed replaces it. */
 	provisional?: boolean;
-	/** The run is over, but no receipt could be read for it. */
+	/** The run is over, but no receipt could be read for it, and the ledger row could not explain why either. */
 	receiptUnavailable?: boolean;
+	/** Replay only: the ledger row for this run has no `endedAt` yet, so the run is still going in another process. */
+	stillRunning?: boolean;
+	/** Replay only: no receipt exists because the ledger closed this row early (`closeAbandonedRows`); the row's own explanation, verbatim. */
+	abandonedDetail?: string;
 }
 
 /** A receipt's projection: the summary plus the answer it sealed. */

package/src/tools/agent-tools.ts

@@ -25,9 +25,9 @@ import type { ResolvedRuntimeTarget } from "../domains/providers/index.js";
 import type { SafetyDecision } from "../domains/safety/contract.js";
 import { formatModelRejection } from "../domains/safety/rejection-feedback.js";
 import { validateEngineToolArguments } from "../engine/ai.js";
-import type { AgentTool, AgentToolResult } from "../engine/types.js";
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "../engine/types.js";
 import { applyToolProfile, type ToolProfileName } from "./profiles.js";
-import type { ToolInvokeOptions, ToolRegistry, ToolSpec } from "./registry.js";
+import type { ToolInvokeOptions, ToolRegistry, ToolResult, ToolSpec } from "./registry.js";
 
 /**
  * Lightweight per-call observability hook. Default no-op so unused
@@ -96,6 +96,18 @@ export interface InvokeWorkerToolOptions {
 type WorkerAgentToolResult = AgentToolResult<{ kind: "ok" } | { kind: "error" }>;
 type WorkerToolOkDetails = { kind: "ok" } & Record<string, unknown>;
 
+function projectToolResult(result: ToolResult): WorkerAgentToolResult {
+	const details = { ...(result.details ?? {}), kind: result.kind } as { kind: "ok" } | { kind: "error" };
+	if (result.kind === "error") {
+		return { content: [{ type: "text", text: result.message }], details };
+	}
+	return {
+		content: [{ type: "text", text: result.output }],
+		details,
+		...(result.terminate === true ? { terminate: true } : {}),
+	};
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -264,9 +276,17 @@ function toAgentTool(
 		description: spec.description,
 		parameters: spec.parameters,
 		label: spec.metadata?.uiLabel ?? spec.name,
-		async execute(toolCallId: string, params: unknown, signal?: AbortSignal): Promise<WorkerAgentToolResult> {
+		async execute(
+			toolCallId: string,
+			params: unknown,
+			signal?: AbortSignal,
+			onUpdate?: AgentToolUpdateCallback,
+		): Promise<WorkerAgentToolResult> {
 			const options = invokeOptions?.() ?? {};
 			if (toolCallId.length > 0) options.toolCallId = toolCallId;
+			if (onUpdate !== undefined) {
+				options.onUpdate = (partialResult) => onUpdate(projectToolResult(partialResult));
+			}
 			const callInput: RunValidatedToolCallInput = {
 				spec,
 				args: params as Record<string, unknown>,

package/src/tools/artifact.ts

@@ -3,10 +3,10 @@ import path from "node:path";
 import { Type } from "typebox";
 import { artifactDefaultPath, CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
 import { ToolNames } from "../core/tool-names.js";
+import { StringEnum } from "../engine/ai.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
-import { stringEnum } from "./string-enum.js";
 
 /**
  * The artifact tool: terminal document writers. kind=plan|review|report writes
@@ -85,7 +85,7 @@ export function createArtifactTool(deps: ArtifactToolDeps = {}): ToolSpec {
 		name: ToolNames.Artifact,
 		description: `Write a named artifact: kind=plan|review|report writes a terminal Markdown document and completes the turn. Without an explicit path it lands in ${CLIO_ARTIFACT_DIR}/ (PLAN.md, REVIEW.md, REPORT.md); pass path only when the user asked for a file at a specific place.`,
 		parameters: Type.Object({
-			kind: stringEnum(ARTIFACT_KINDS, "Artifact kind."),
+			kind: StringEnum(ARTIFACT_KINDS, { description: "Artifact kind." }),
 			content: Type.String({ description: "Full Markdown body." }),
 			title: Type.Optional(Type.String({ description: "Document title." })),
 			path: Type.Optional(Type.String({ description: "Override the default artifact path." })),

package/src/tools/ask-user.ts

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import { clioStateDir } from "../core/xdg.js";
 import { type AutonomyExposure, DEFAULT_AUTONOMY_EXPOSURE } from "../domains/safety/autonomy.js";
+import { StringEnum } from "../engine/ai.js";
 import type {
 	AskUserToolPolicy,
 	AskUserTranscriptAnswer,
@@ -14,7 +15,6 @@ import type {
 	ToolResult,
 	ToolSpec,
 } from "./registry.js";
-import { stringEnum } from "./string-enum.js";
 
 export const ASK_USER_OTHER_LABEL = "Other (type your answer)";
 
@@ -75,16 +75,15 @@ export interface AskUserToolDeps {
 
 export const askUserParameters = Type.Object({
 	action: Type.Optional(
-		stringEnum(
-			["ask", "complete"],
-			"ask presents a round of questions; complete (exactly once) records decisions before final prose.",
-		),
+		StringEnum(["ask", "complete"], {
+			description: "ask presents a round of questions; complete (exactly once) records decisions before final prose.",
+		}),
 	),
 	mode: Type.Optional(
-		stringEnum(
-			["round", "single_question"],
-			"Caps how many questions this call may carry. single_question accepts exactly 1 and rejects the call otherwise (interviews); round accepts 1 to 4 tightly related confirmations. Default is round.",
-		),
+		StringEnum(["round", "single_question"], {
+			description:
+				"Caps how many questions this call may carry. single_question accepts exactly 1 and rejects the call otherwise (interviews); round accepts 1 to 4 tightly related confirmations. Default is round.",
+		}),
 	),
 	questions: Type.Optional(
 		Type.Array(
@@ -118,10 +117,10 @@ export const askUserParameters = Type.Object({
 	),
 	summary: Type.Optional(Type.String({ description: "Short closeout summary for action=complete." })),
 	exposure: Type.Optional(
-		stringEnum(
-			["local", "outward"],
-			"Blast radius of this gate. local (default) stays inside the workspace. outward means answering it publishes or sends something the operator cannot take back (filing an issue or PR, posting a comment, pushing, releasing); at autonomy auto-edit an outward gate parks for the operator instead of being answered automatically.",
-		),
+		StringEnum(["local", "outward"], {
+			description:
+				"Blast radius of this gate. local (default) stays inside the workspace. outward means answering it publishes or sends something the operator cannot take back (filing an issue or PR, posting a comment, pushing, releasing); at autonomy auto-edit an outward gate parks for the operator instead of being answered automatically.",
+		}),
 	),
 });
 
@@ -558,6 +557,17 @@ export async function finalizeAskUserInterview(
 	await persistAskUserTranscript(policy, options);
 }
 
+/** Settle a turn-owned interview, then hand its immutable policy to one durable producer. */
+export async function finalizeAskUserInterviewForHost(
+	policy: AskUserToolPolicy,
+	reason: string,
+	options?: ToolInvokeOptions,
+	onFinalized?: (policy: AskUserToolPolicy) => void,
+): Promise<void> {
+	await finalizeAskUserInterview(policy, reason, options);
+	onFinalized?.(policy);
+}
+
 async function defaultAskUserHandler(): Promise<AskUserResult> {
 	return cancelledAskUserResult();
 }

package/src/tools/bash.ts

@@ -21,6 +21,28 @@ interface ShapedBashOutput {
 	details?: ToolResultDetails;
 }
 
+/** Bound a cumulative live snapshot without writing an offload file per tick. */
+function shapeBashProgress(rawOutput: string): ToolResult {
+	const truncation = truncateTail(rawOutput, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: BASH_DISPLAY_MAX_BYTES - BASH_TAIL_NOTE_RESERVE,
+	});
+	const bytes = Buffer.byteLength(rawOutput, "utf8");
+	return {
+		kind: "ok",
+		output: truncation.content,
+		details: {
+			resultSize: {
+				bytes,
+				shownBytes: truncation.outputBytes,
+				maxBytes: BASH_DISPLAY_MAX_BYTES,
+				truncated: truncation.truncated,
+				policy: "tail",
+			},
+		},
+	};
+}
+
 // Tail-truncate the combined output for display, spilling the full output to a
 // scratch file first when it overflows the display cap. Setting
 // `details.resultSize.offloadPath` tells the registry result-shaper to leave
@@ -132,11 +154,17 @@ export const bashTool: ToolSpec = {
 		}
 		const timeout = typeof args.timeout_ms === "number" && args.timeout_ms > 0 ? args.timeout_ms : 300_000;
 		try {
-			const result = await runBashCommand(args.command, {
+			const runOptions: Parameters<typeof runBashCommand>[1] = {
 				cwd,
 				timeoutMs: timeout,
 				...(options?.signal === undefined ? {} : { signal: options.signal }),
-			});
+			};
+			if (options?.onUpdate !== undefined) {
+				runOptions.onUpdate = (progress) => {
+					options.onUpdate?.(shapeBashProgress(combineBashOutput(progress)));
+				};
+			}
+			const result = await runBashCommand(args.command, runOptions);
 			const { error, aborted, timedOut, outputCapped } = result;
 			if (aborted) {
 				return { kind: "error", message: "bash: command aborted" };