@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/dispatch/dedup.ts

@@ -0,0 +1,133 @@
+/**
+ * Dispatch duplicate guard, packaged as a middleware hook registration.
+ *
+ * Replaces the registry's former inline dispatchDuplicateBlock /
+ * rememberSuccessfulDispatch pair. Within one user turn, a dispatch whose
+ * normalized fingerprint already completed successfully is blocked so the
+ * model reuses the existing receipt instead of re-running the fleet step.
+ * Orchestrator-only: workers never register the dispatch tool.
+ */
+
+import { ToolNames } from "../../core/tool-names.js";
+import type { MiddlewareEffect, MiddlewareHookInput, MiddlewareHookRegistration } from "../middleware/index.js";
+
+export const DISPATCH_DEDUP_REGISTRATION_ID = "guard.dispatch-dedup";
+
+/** Bounded turn-id memory, matching the loop guard's policy. */
+const DISPATCH_GUARD_TURN_LIMIT = 32;
+const DISPATCH_DEFAULT_AGENT_ID = "coder";
+
+export function createDispatchDedupRegistration(): MiddlewareHookRegistration {
+	const successfulDispatchesByTurn = new Map<string, Set<string>>();
+
+	const remember = (turnId: string, fingerprint: string): void => {
+		let seen = successfulDispatchesByTurn.get(turnId);
+		if (!seen) {
+			seen = new Set<string>();
+			successfulDispatchesByTurn.set(turnId, seen);
+			while (successfulDispatchesByTurn.size > DISPATCH_GUARD_TURN_LIMIT) {
+				const oldest = successfulDispatchesByTurn.keys().next().value;
+				if (typeof oldest !== "string") break;
+				successfulDispatchesByTurn.delete(oldest);
+			}
+		}
+		seen.add(fingerprint);
+	};
+
+	return {
+		id: DISPATCH_DEDUP_REGISTRATION_ID,
+		description: "blocks re-running a dispatch that already completed successfully in this user turn",
+		hooks: ["before_tool", "after_tool"],
+		toolNames: [ToolNames.Dispatch],
+		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			if (input.turnId === undefined) return [];
+			const fingerprint = dispatchFingerprint(input.toolArgs);
+			if (fingerprint === null) return [];
+			if (input.hook === "before_tool") {
+				const seen = successfulDispatchesByTurn.get(input.turnId);
+				if (!seen?.has(fingerprint)) return [];
+				const summary = formatDispatchDuplicateSummary(input.toolArgs);
+				return [
+					{
+						kind: "block_tool",
+						reason:
+							`dispatch duplicate blocked: ${summary} already completed successfully in this user turn. ` +
+							`Use the existing dispatch receipt/output to answer instead of repeating the same fleet dispatch.`,
+						severity: "hard-block",
+					},
+				];
+			}
+			if (input.metadata?.resultKind !== "ok") return [];
+			if (input.toolResultDetails?.exitCode !== 0) return [];
+			remember(input.turnId, fingerprint);
+			return [];
+		},
+	};
+}
+
+function dispatchFingerprint(args: MiddlewareHookInput["toolArgs"]): string | null {
+	const record = asRecord(args);
+	if (record === null) return null;
+	const task = stringValue(record.task);
+	if (task === null) return null;
+	const normalized = {
+		agentId:
+			stringValue(record.agent_id) ??
+			stringValue(record.agentId) ??
+			stringValue(record.agent) ??
+			DISPATCH_DEFAULT_AGENT_ID,
+		task,
+		target: stringValue(record.target) ?? "",
+		model: stringValue(record.model) ?? "",
+		profile:
+			stringValue(record.agent_profile) ?? stringValue(record.worker_profile) ?? stringValue(record.workerProfile) ?? "",
+		runtime:
+			stringValue(record.agent_runtime) ?? stringValue(record.worker_runtime) ?? stringValue(record.workerRuntime) ?? "",
+		toolProfile: stringValue(record.tool_profile) ?? stringValue(record.toolProfile) ?? "",
+		thinkingLevel: stringValue(record.thinking_level) ?? stringValue(record.thinkingLevel) ?? "",
+		cwd: stringValue(record.cwd) ?? "",
+		memorySection: stringValue(record.memory_section) ?? stringValue(record.memorySection) ?? "",
+		requiredCapabilities: stringArrayValue(record.required_capabilities ?? record.requiredCapabilities).sort(),
+	};
+	return stableJson(normalized);
+}
+
+function formatDispatchDuplicateSummary(args: MiddlewareHookInput["toolArgs"]): string {
+	const record = asRecord(args);
+	if (record === null) return "that dispatch";
+	const agentId =
+		stringValue(record.agent_id) ?? stringValue(record.agentId) ?? stringValue(record.agent) ?? DISPATCH_DEFAULT_AGENT_ID;
+	const task = stringValue(record.task) ?? "";
+	const taskSummary = task.length > 80 ? `${task.slice(0, 77)}...` : task;
+	return `agent=${agentId} task=${JSON.stringify(taskSummary)}`;
+}
+
+function stringValue(value: unknown): string | null {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function stringArrayValue(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.filter((item): item is string => typeof item === "string")
+		.map((item) => item.trim())
+		.filter(Boolean);
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		return `{${Object.keys(record)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}

package/src/domains/dispatch/event-pump.ts

@@ -0,0 +1,251 @@
+/**
+ * Domain-owned eager event ingestion for dispatched runs.
+ *
+ * Correctness-critical event folding (token metering, tool stats, finish
+ * contract, assistant output capture) used to run as a side effect of an
+ * external consumer iterating the returned event stream. A fast worker could
+ * finish before anyone iterated, sealing a zero-token receipt. The pump
+ * inverts that: the dispatch domain starts consuming the source stream the
+ * moment a run is registered, folds every event itself, and hands external
+ * consumers a bounded replay tee. Receipts never depend on whether a UI or
+ * tool happened to subscribe.
+ *
+ * The tee is bounded (drop-oldest) so an absent or abandoned consumer cannot
+ * grow memory: the source channel (worker-spawn) already buffers unboundedly,
+ * and duplicating that here would double the hazard. Dropped events only
+ * degrade live display; every receipt-bearing fact was already folded.
+ */
+
+import { truncateUtf8 } from "../../tools/truncate-utf8.js";
+import type { RunReceiptOutput } from "./types.js";
+
+/** Bounded replay capacity for the external consumer tee. */
+export const EVENT_TEE_LIMIT = 1024;
+
+export interface DispatchEventPump {
+	/** Single-consumer bounded replay of the source stream, oldest first. */
+	events: AsyncIterableIterator<unknown>;
+	/** Settles when every source event has been folded (source exhausted). */
+	done: Promise<void>;
+	/** Events dropped from the tee because no consumer kept pace. */
+	droppedEvents(): number;
+}
+
+export interface StartDispatchEventPumpOptions {
+	/** Synthetic events delivered to the consumer before source events (e.g. route warnings). Not folded. */
+	prelude?: ReadonlyArray<unknown>;
+	limit?: number;
+	/** Invoked for fold or source-iteration failures; ingestion continues where possible. */
+	onError?: (error: unknown) => void;
+	/** Domain-owned live projection invoked once for every consumer-visible event. */
+	onEvent?: (event: unknown) => void;
+}
+
+/**
+ * Start consuming `source` immediately, folding every event through `fold`
+ * and buffering it for one external consumer. A fold failure is reported and
+ * skipped so one malformed event cannot starve the meters behind it; a source
+ * failure ends the pump. The consumer's early `return()` abandons the tee
+ * without stopping ingestion.
+ */
+export function startDispatchEventPump(
+	source: AsyncIterable<unknown>,
+	fold: (event: unknown) => void,
+	options: StartDispatchEventPumpOptions = {},
+): DispatchEventPump {
+	const limit = options.limit ?? EVENT_TEE_LIMIT;
+	const pending: unknown[] = [...(options.prelude ?? [])];
+	const waiters: Array<(result: IteratorResult<unknown>) => void> = [];
+	let finished = false;
+	let abandoned = false;
+	let dropped = 0;
+
+	const push = (value: unknown): void => {
+		if (abandoned) return;
+		const waiter = waiters.shift();
+		if (waiter) {
+			waiter({ value, done: false });
+			return;
+		}
+		pending.push(value);
+		while (pending.length > limit) {
+			pending.shift();
+			dropped += 1;
+		}
+	};
+
+	const end = (): void => {
+		finished = true;
+		while (waiters.length > 0) {
+			waiters.shift()?.({ value: undefined, done: true });
+		}
+	};
+	const notify = (event: unknown): void => {
+		try {
+			options.onEvent?.(event);
+		} catch (error) {
+			options.onError?.(error);
+		}
+	};
+
+	const done = (async (): Promise<void> => {
+		try {
+			for (const event of options.prelude ?? []) notify(event);
+			for await (const event of source) {
+				try {
+					fold(event);
+				} catch (error) {
+					options.onError?.(error);
+				}
+				notify(event);
+				push(event);
+			}
+		} catch (error) {
+			options.onError?.(error);
+		} finally {
+			end();
+		}
+	})();
+
+	const events: AsyncIterableIterator<unknown> = {
+		next(): Promise<IteratorResult<unknown>> {
+			if (pending.length > 0) {
+				return Promise.resolve({ value: pending.shift(), done: false });
+			}
+			if (finished || abandoned) return Promise.resolve({ value: undefined, done: true });
+			return new Promise<IteratorResult<unknown>>((resolve) => {
+				waiters.push(resolve);
+			});
+		},
+		return(): Promise<IteratorResult<unknown>> {
+			abandoned = true;
+			pending.length = 0;
+			while (waiters.length > 0) {
+				waiters.shift()?.({ value: undefined, done: true });
+			}
+			return Promise.resolve({ value: undefined, done: true });
+		},
+		[Symbol.asyncIterator](): AsyncIterableIterator<unknown> {
+			return this;
+		},
+	};
+
+	return { events, done, droppedEvents: () => dropped };
+}
+
+/**
+ * Byte bound on the assistant output text sealed into a receipt. Large enough
+ * for a substantive final answer, small enough that receipts stay cheap to
+ * read and render; overflow is recorded explicitly via `truncated`/`bytes`.
+ */
+export const WORKER_OUTPUT_MAX_BYTES = 8192;
+const WORKER_OUTPUT_TRUNCATION_MARKER = "\n[worker output truncated]";
+
+export interface WorkerOutputCapture {
+	observe(event: unknown): void;
+	snapshot(): RunReceiptOutput | undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assistantTextFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => {
+			if (typeof block === "string") return block;
+			if (!isRecord(block)) return "";
+			return typeof block.text === "string" ? block.text : "";
+		})
+		.join("");
+}
+
+function isDurableAssistantMessage(message: Record<string, unknown>): boolean {
+	const stopReason = message.stopReason;
+	if (stopReason === "toolUse" || stopReason === "error" || stopReason === "aborted" || stopReason === "cancelled") {
+		return false;
+	}
+	if (!Array.isArray(message.content)) return true;
+	return !message.content.some((block) => isRecord(block) && block.type === "toolCall");
+}
+
+/**
+ * Extract text only from a completed, durable assistant answer. Tool-use
+ * preambles are intermediate even when an event projection has stripped the
+ * structured call block. Known failure messages are outcome detail, not a
+ * successful worker answer. All other terminal spellings (including ACP's
+ * `end_turn`) remain provider-compatible.
+ */
+export function durableAssistantTextFromEvent(event: unknown): string {
+	if (!isRecord(event) || event.type !== "message_end" || !isRecord(event.message)) return "";
+	if (event.message.role !== "assistant" || !isDurableAssistantMessage(event.message)) return "";
+	return assistantTextFromContent(event.message.content);
+}
+
+function boundedOutput(state: RunReceiptOutput["state"], text: string): RunReceiptOutput {
+	const bytes = Buffer.byteLength(text, "utf8");
+	const bounded = truncateUtf8(text, WORKER_OUTPUT_MAX_BYTES, WORKER_OUTPUT_TRUNCATION_MARKER);
+	return { state, text: bounded, bytes, truncated: bounded !== text };
+}
+
+/**
+ * Fold assistant output out of a run's event stream so the receipt can carry
+ * a durable, bounded copy. A completed assistant `message_end` becomes the
+ * final answer only when it ended as normal text (`stop`/`length`, with no
+ * structured tool call). Tool-use preambles are intermediate and never enter
+ * durable output. Streaming `text_delta` fragments accumulate as the in-flight
+ * partial and are discarded when their message completes. A run that ends
+ * with unflushed deltas (abort, stall, kill mid-message) therefore snapshots
+ * as `partial`, never as final. Accumulation is bounded in memory by the same
+ * byte cap the receipt uses; overflow only marks truncation.
+ */
+export function createWorkerOutputCapture(): WorkerOutputCapture {
+	let finalText: string | null = null;
+	let partialText = "";
+	let partialBytes = 0;
+	let partialStored = 0;
+
+	return {
+		observe(event: unknown): void {
+			if (!isRecord(event)) return;
+			if (event.type === "message_end") {
+				// Any message boundary flushes the in-flight stream: its deltas
+				// belong to the message that just completed.
+				const message = isRecord(event.message) ? event.message : null;
+				partialText = "";
+				partialBytes = 0;
+				partialStored = 0;
+				if (message === null || message.role !== "assistant") return;
+				if (!isDurableAssistantMessage(message)) return;
+				const text = assistantTextFromContent(message.content).trim();
+				if (text.length > 0) finalText = text;
+				return;
+			}
+			if (event.type !== "message_update") return;
+			const assistantEvent = isRecord(event.assistantMessageEvent) ? event.assistantMessageEvent : null;
+			if (assistantEvent === null || assistantEvent.type !== "text_delta") return;
+			const delta = assistantEvent.delta;
+			if (typeof delta !== "string" || delta.length === 0) return;
+			partialBytes += Buffer.byteLength(delta, "utf8");
+			if (partialStored < WORKER_OUTPUT_MAX_BYTES) {
+				partialText += delta;
+				partialStored += Buffer.byteLength(delta, "utf8");
+			}
+		},
+		snapshot(): RunReceiptOutput | undefined {
+			if (partialBytes > 0 && partialText.trim().length > 0) {
+				const bounded = truncateUtf8(partialText.trim(), WORKER_OUTPUT_MAX_BYTES, WORKER_OUTPUT_TRUNCATION_MARKER);
+				return {
+					state: "partial",
+					text: bounded,
+					bytes: partialBytes,
+					truncated: bounded !== partialText.trim() || partialBytes > partialStored,
+				};
+			}
+			if (finalText !== null) return boundedOutput("final", finalText);
+			return undefined;
+		},
+	};
+}

package/src/domains/dispatch/execution-handoff.ts

@@ -0,0 +1,29 @@
+export const EXECUTION_HANDOFF_MAX_ITEMS = 16;
+export const EXECUTION_HANDOFF_MAX_TEXT_BYTES = 12_000;
+
+export interface ExecutionHandoff {
+	stepId: string;
+	assignmentId: string;
+	terminalRunId: string;
+	receiptDigest: string;
+	output: string;
+}
+
+function truncateUtf8(value: string, limit: number): string {
+	const bytes = Buffer.from(value, "utf8");
+	return bytes.length <= limit ? value : bytes.subarray(0, limit).toString("utf8");
+}
+
+export function projectExecutionHandoffs(
+	dependencyIds: ReadonlyArray<string>,
+	outputs: ReadonlyMap<string, ExecutionHandoff>,
+): ExecutionHandoff[] {
+	if (dependencyIds.length > EXECUTION_HANDOFF_MAX_ITEMS)
+		throw new Error(`execution handoff: at most ${EXECUTION_HANDOFF_MAX_ITEMS} predecessors are allowed`);
+	const perItem = Math.floor(EXECUTION_HANDOFF_MAX_TEXT_BYTES / Math.max(1, dependencyIds.length));
+	return dependencyIds.map((id) => {
+		const source = outputs.get(id);
+		if (!source) throw new Error(`execution handoff: missing successful predecessor '${id}'`);
+		return { ...source, output: truncateUtf8(source.output, perItem) };
+	});
+}