@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/tools/dispatch-types.ts

@@ -3,7 +3,13 @@ import type { AgentSpec } from "../domains/agents/spec.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
-import type { cleanupCompeteGroup, createCandidateWorktree, mergeWinnerBranch } from "./compete-worktrees.js";
+import type {
+	CandidateWorktree,
+	CompeteGroupOwnership,
+	CompeteMuxWorktrees,
+	cleanupCompeteGroup,
+	mergeWinnerBranch,
+} from "./compete-worktrees.js";
 import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
 import type { DispatchPlanView, ResolvedDispatchPlanArtifact } from "./dispatch-plan.js";
 import type { DispatchRunEventRegistry } from "./dispatch-run-events.js";
@@ -83,9 +89,15 @@ export interface DispatchToolDeps {
 	background?: DispatchBackgroundRegistry;
 	/** Optional compete storage overrides for alternate backends and deterministic fault tests. */
 	competeWorktrees?: {
-		createCandidate?: typeof createCandidateWorktree;
-		cleanupGroup?: typeof cleanupCompeteGroup;
+		createCandidate?: (
+			ownership: CompeteGroupOwnership,
+			index: number,
+			baseline: string,
+		) => CandidateWorktree | Promise<CandidateWorktree>;
+		cleanupGroup?: (...args: Parameters<typeof cleanupCompeteGroup>) => void | Promise<void>;
 		mergeWinner?: typeof mergeWinnerBranch;
+		/** Optional herdr route; every operation retains native Git fallback. */
+		mux?: CompeteMuxWorktrees;
 	};
 	getAgentCatalog?: () => string;
 	getAgentSpecs: () => ReadonlyArray<AgentSpec>;

package/src/tools/dispatch.ts

@@ -80,7 +80,7 @@ const DispatchIntentSchema = Type.Object(
 	{
 		additionalProperties: false,
 		description:
-			"Typed repository-relative path and output intent. Verification checks are declared ids from package scripts or .clio-coder/verifiers.yaml, not shell commands.",
+			"Typed repository-relative path and output intent. Declare it on every dispatch: declared paths select the project rules that apply to them and pin worker context, and omitting it falls back to reading path-like tokens out of your task and briefing text, which can miss an applicable rule. Verification checks are declared ids from package scripts or .clio-coder/verifiers.yaml, not shell commands. In a batch, per-task intent narrows the top-level intent and is refused if it reaches outside it.",
 	},
 );
 

package/src/tools/executables.ts

@@ -1,17 +1,4 @@
-import { statSync } from "node:fs";
-import { delimiter, join } from "node:path";
-
-function findExecutableOnPath(name: string): string | null {
-	const pathEnv = process.env.PATH;
-	if (!pathEnv) return null;
-	for (const dir of pathEnv.split(delimiter)) {
-		if (!dir) continue;
-		const candidate = join(dir, name);
-		const stat = statSync(candidate, { throwIfNoEntry: false });
-		if (stat?.isFile() && (stat.mode & 0o111) !== 0) return candidate;
-	}
-	return null;
-}
+import { findExecutableOnPath, resolveToolBinary } from "../domains/toolchain/resolve.js";
 
 export function resolveFdBinary(): string | null {
 	return findExecutableOnPath("fd") ?? findExecutableOnPath("fdfind");
@@ -20,3 +7,19 @@ export function resolveFdBinary(): string | null {
 export function resolveRgBinary(): string | null {
 	return findExecutableOnPath("rg");
 }
+
+/**
+ * Resolve any executable Clio might run, through the toolchain ladder.
+ *
+ * For a name in the pinned registry the answer is PATH when the copy there
+ * clears the pin's floor, then Clio's vendored copy, then null. For anything
+ * else it is a plain PATH lookup, which is what `resolveFdBinary` and
+ * `resolveRgBinary` above already do for the two search tools Clio never
+ * vendors.
+ *
+ * Callers that need to explain the answer (doctor, `clio-coder tools status`)
+ * want `resolveToolBinary` instead: this returns only the path to run.
+ */
+export function resolveBinary(name: string): string | null {
+	return resolveToolBinary(name).binaryPath;
+}

package/src/tools/observation.ts

@@ -70,9 +70,29 @@ export const OBSERVATION_TURN_BUDGET_ENV = GUARDRAIL_ENV_VARS.observationTurnBud
 const MIN_BUDGET_SLICE_BYTES = 1024;
 const BUDGET_TRACK_LIMIT = 256;
 
+/**
+ * How many exhausted-pool notices one turn gets before the next such call fails
+ * terminally instead of returning a retryable notice.
+ *
+ * Smoke pass 2 (G2) watched a 9B local model re-issue the identical read about
+ * twenty times against the same 208-byte notice, until the unrelated tool-call
+ * budget stopped it. The notice cannot become un-retryable by wording alone: a
+ * `kind:"ok"` result is an invitation to try again.
+ *
+ * Three is the smallest count that still lets a model learn the shape from the
+ * notice itself. The pool is shared by six OBSERVE tools, so a model that reads,
+ * then greps narrower, then lists, has spent three honest attempts at the advice
+ * the notice gives. A fourth consecutive exhausted call is evidence the advice
+ * is not landing, and it fails. Waste is bounded at four calls out of the 60-call
+ * turn budget instead of twenty.
+ */
+const MAX_EXHAUSTED_NOTICES_PER_TURN = 3;
+
 interface TurnBudgetState {
 	usedBytes: number;
 	lastSeenAt: number;
+	/** Consecutive exhausted-pool short-circuits; reset by any call that got a slice. */
+	exhaustedStreak: number;
 }
 
 const turnBudgets = new Map<string, TurnBudgetState>();
@@ -156,7 +176,7 @@ export function reserveObservation(selfCapBytes: number, options?: ToolInvokeOpt
 		};
 	}
 	const limitBytes = observationTurnBudgetLimit();
-	const state = turnBudgets.get(key) ?? { usedBytes: 0, lastSeenAt: Date.now() };
+	const state = turnBudgets.get(key) ?? { usedBytes: 0, lastSeenAt: Date.now(), exhaustedStreak: 0 };
 	state.lastSeenAt = Date.now();
 	turnBudgets.set(key, state);
 	pruneBudgetMap();
@@ -174,6 +194,9 @@ export function reserveObservation(selfCapBytes: number, options?: ToolInvokeOpt
 			settled: false,
 		};
 	}
+	// A call that got a slice is progress, so the exhausted streak starts over.
+	// Only an unbroken run of short-circuits reaches the terminal failure.
+	state.exhaustedStreak = 0;
 	const callCapBytes = Math.min(selfCapBytes, remaining);
 	return {
 		key,
@@ -203,6 +226,7 @@ export function commitObservationReservation(reservation: ObservationReservation
 	const state = turnBudgets.get(reservation.key) ?? {
 		usedBytes: reservation.usedBeforeBytes,
 		lastSeenAt: Date.now(),
+		exhaustedStreak: 0,
 	};
 	state.usedBytes += reservation.callCapBytes;
 	state.lastSeenAt = Date.now();
@@ -237,6 +261,7 @@ function recordSpentBytes(reservation: ObservationReservation, bytes: number): v
 	const state = turnBudgets.get(reservation.key) ?? {
 		usedBytes: reservation.usedBeforeBytes + committedBytes,
 		lastSeenAt: Date.now(),
+		exhaustedStreak: 0,
 	};
 	state.usedBytes = Math.max(0, state.usedBytes + bytes - committedBytes);
 	state.lastSeenAt = Date.now();
@@ -252,10 +277,26 @@ function budgetDetails(reservation: ObservationReservation): ObservationBudgetDe
 	};
 }
 
+/** Count this short-circuit against the turn's run of them. Untracked calls never escalate. */
+function bumpExhaustedStreak(key: string | null): number {
+	if (key === null) return 1;
+	const state = turnBudgets.get(key);
+	if (state === undefined) return 1;
+	state.exhaustedStreak += 1;
+	state.lastSeenAt = Date.now();
+	turnBudgets.set(key, state);
+	return state.exhaustedStreak;
+}
+
 /**
  * Structured result for a call that found the turn pool already spent.
  * `subject` names what the call was about (a path, a pattern); `hint` names
  * the narrowing arguments the tool supports.
+ *
+ * The first few such calls get the notice, which states the numbers and the
+ * narrowing advice. Past MAX_EXHAUSTED_NOTICES_PER_TURN the call fails instead:
+ * nothing this turn can return content, so an `ok` result is an invitation to a
+ * retry loop the pool can never satisfy.
  */
 export function observationBudgetExhausted(input: {
 	tool: string;
@@ -265,9 +306,18 @@ export function observationBudgetExhausted(input: {
 	hint: string;
 }): ToolResult {
 	const { tool, unit, reservation, subject, hint } = input;
-	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${formatSize(
-		reservation.usedBeforeBytes,
-	)} already returned of ${formatSize(reservation.limitBytes)}. ${hint}]`;
+	const streak = bumpExhaustedStreak(reservation.key);
+	const spent = `${formatSize(reservation.usedBeforeBytes)} already returned of ${formatSize(reservation.limitBytes)}`;
+	if (streak > MAX_EXHAUSTED_NOTICES_PER_TURN) {
+		const message =
+			`observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ` +
+			`This is the ${streak}th call to hit it, so no observation tool can return content until the ` +
+			`next turn. Do not retry this call and do not substitute another one. Re-plan with what you ` +
+			`already have: say what you found, name what is still unread, and propose the next step.`;
+		recordSpentBytes(reservation, byteLength(message));
+		return { kind: "error", message };
+	}
+	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}]`;
 	const shownBytes = byteLength(output);
 	recordSpentBytes(reservation, shownBytes);
 	const budget = budgetDetails(reservation);

package/src/tools/panes-surface.ts

@@ -0,0 +1,38 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import { PANES_PRESET_IDS } from "../domains/mux/operations.js";
+import { StringEnum } from "../engine/ai.js";
+import type { ToolSurface } from "./lazy-tool.js";
+
+/**
+ * The model's door to the pane layer.
+ *
+ * There is no argv field, and there never will be. Arbitrary argv is
+ * operator-only through `/panes open`, which is what keeps this tool out of
+ * shell-escape territory (spec 4.8, risk register "tool misuse"). `preset` is a
+ * closed enum, so an argv string cannot arrive spelled as a preset name either.
+ */
+export const panesToolSurface = {
+	name: ToolNames.Panes,
+	description:
+		"Look at, focus, and manage the terminal panes Clio owns beside this session. Use show to bring a dispatched run's live viewer pane to the front when the operator asks to see an agent (\"show me the tester\"). open starts one of the fixed utility presets; there is no way to run an arbitrary command. close removes a pane Clio created. list reports the current inventory and the pane layer's health.",
+	parameters: Type.Object({
+		action: StringEnum(["show", "open", "close", "list"], {
+			description:
+				"show focuses a run's viewer pane; open starts a preset utility pane; close removes a Clio-owned pane; list reports the inventory.",
+		}),
+		target: Type.Optional(
+			Type.String({
+				description:
+					'action=show: an agent id or run id prefix, most recent match wins. action=close: a pane id, a pane label, an agent id, or "all".',
+			}),
+		),
+		preset: Type.Optional(
+			StringEnum([...PANES_PRESET_IDS], {
+				description: "action=open: which fixed utility pane to start.",
+			}),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "sequential",
+} satisfies ToolSurface;

package/src/tools/panes.ts

@@ -0,0 +1,112 @@
+import type { PanesOperations } from "../domains/mux/operations.js";
+import { PANES_PRESET_IDS } from "../domains/mux/operations.js";
+import { panesToolSurface } from "./panes-surface.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+
+/**
+ * The `panes` tool: the model's read-class door to the pane layer.
+ *
+ * It is registered only when the mux answered detection, so its presence in the
+ * prompt is itself the statement that panes exist in this session. Every action
+ * routes through the same `PanesOperations` the `/panes` slash command drives,
+ * so the two surfaces cannot describe the same pane differently.
+ *
+ * The one asymmetry with the operator's surface is deliberate: `open` accepts a
+ * preset and nothing else. A caller that fabricates an `argv` field gets a
+ * refusal rather than a shell.
+ */
+
+export interface PanesToolDeps {
+	panes: PanesOperations;
+}
+
+function describeInventory(deps: PanesToolDeps): ToolResult {
+	const status = deps.panes.status();
+	const header = `panes mode=${status.mode} ${status.available ? "available" : "unavailable"}; notifications=${status.settings.notifications}`;
+	const rows = status.panes.map((pane) => `- ${pane.paneId} ${pane.purpose} ${pane.label}`);
+	return {
+		kind: "ok",
+		output: [header, ...(rows.length > 0 ? rows : ["- no Clio-owned panes"])].join("\n"),
+		details: { action: "list", mode: status.mode, available: status.available, panes: status.panes },
+	};
+}
+
+export function createPanesTool(deps: PanesToolDeps): ToolSpec {
+	return {
+		...panesToolSurface,
+		async run(args): Promise<ToolResult> {
+			const action = typeof args.action === "string" ? args.action : "";
+			// An argv field never reaches the operations layer. Refusing loudly is
+			// better than ignoring it, because a model that believed it opened a
+			// command pane would report work it did not do.
+			if ("argv" in args) {
+				return {
+					kind: "error",
+					message:
+						"panes: argv panes are operator-only; use action=open with a preset, or ask the operator to run /panes open <command>",
+				};
+			}
+			const target = typeof args.target === "string" ? args.target.trim() : "";
+			if (action === "list") return describeInventory(deps);
+			if (action === "show") {
+				if (target.length === 0) return { kind: "error", message: "panes: action=show requires target" };
+				const result = await deps.panes.show(target);
+				if (result.status === "watching") {
+					return {
+						kind: "ok",
+						output: `the watch pane is now rendering ${result.agentId} (run ${result.runId}).`,
+						details: { action: "show", runId: result.runId, agentId: result.agentId },
+					};
+				}
+				if (result.status === "not-found") {
+					const known = result.candidates.length > 0 ? ` Live runs: ${result.candidates.join(", ")}.` : "";
+					return { kind: "error", message: `panes: no live run matches '${result.target}'.${known}` };
+				}
+				return { kind: "error", message: `panes: ${result.reason}` };
+			}
+			if (action === "open") {
+				const preset = typeof args.preset === "string" ? args.preset : "";
+				if (!(PANES_PRESET_IDS as ReadonlyArray<string>).includes(preset)) {
+					return {
+						kind: "error",
+						message: `panes: action=open requires preset, one of ${PANES_PRESET_IDS.join(", ")}`,
+					};
+				}
+				const result = await deps.panes.open({ preset });
+				if (result.status === "opened") {
+					return {
+						kind: "ok",
+						output:
+							result.paneId === null
+								? `completed the ${result.label} chooser.`
+								: `opened the ${result.label} pane (${result.paneId}).`,
+						details: { action: "open", preset, paneId: result.paneId },
+					};
+				}
+				if (result.status === "missing-binary") {
+					return {
+						kind: "error",
+						message: `panes: ${result.detail}`,
+					};
+				}
+				return { kind: "error", message: `panes: ${result.reason}` };
+			}
+			if (action === "close") {
+				if (target.length === 0) return { kind: "error", message: "panes: action=close requires target" };
+				const result = await deps.panes.close(target);
+				if (result.status === "closed") {
+					return {
+						kind: "ok",
+						output: `closed ${result.closed} pane(s)${result.labels.length > 0 ? `: ${result.labels.join(", ")}` : ""}.`,
+						details: { action: "close", closed: result.closed },
+					};
+				}
+				if (result.status === "not-found") {
+					return { kind: "error", message: `panes: no Clio-owned pane matches '${result.target}'` };
+				}
+				return { kind: "error", message: `panes: ${result.reason}` };
+			}
+			return { kind: "error", message: `panes: action must be show, open, close, or list; got '${action}'` };
+		},
+	};
+}

package/src/tools/policy.ts

@@ -49,6 +49,10 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	// review the board depends on. Sequential so two posts in one batch do not
 	// interleave against the local post cap.
 	[ToolNames.Ledger]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	// panes projects Clio's own runs onto a pane host and opens preset utility
+	// panes. It mutates no workspace, so it stays read class; sequential because
+	// two pane operations in one batch would race the same pane registry.
+	[ToolNames.Panes]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" },
@@ -75,6 +79,8 @@ const OBSERVE_ENVELOPE_SELF_CAPS: ReadonlyArray<[BuiltinToolName, () => number]>
 const SESSION_BOUND_TOOLS = new Set<ToolName>([]);
 const DISPATCH_BOUND_TOOLS = new Set<ToolName>([ToolNames.Dispatch, ToolNames.Monitor, ToolNames.Steer]);
 const INTERACTIVE_BOUND_TOOLS = new Set<ToolName>([ToolNames.AskUser]);
+/** Registered only when a pane host answered detection and the mux is live. */
+const PANES_BOUND_TOOLS = new Set<ToolName>([ToolNames.Panes]);
 /** The RETRIEVE plane, omitted wholesale by a hermetic run (tools/network-policy.ts). */
 const NETWORK_BOUND_TOOLS = new Set<ToolName>([ToolNames.WebFetch]);
 
@@ -82,8 +88,9 @@ export interface BuiltinToolPolicyOptions {
 	includeSessionTools?: boolean;
 	includeDispatchTools?: boolean;
 	includeInteractiveTools?: boolean;
+	includePanesTools?: boolean;
 	/**
-	 * Unlike the other three, this defaults to true: every registry registers
+	 * Unlike the other four, this defaults to true: every registry registers
 	 * the network plane unless a run explicitly asked to be hermetic, so an
 	 * unset option must keep demanding it.
 	 */
@@ -132,12 +139,14 @@ function validateBuiltinToolPolicy(specs: ReadonlyArray<ToolSpec>, options: Buil
 	const includeSessionTools = options.includeSessionTools ?? false;
 	const includeDispatchTools = options.includeDispatchTools ?? false;
 	const includeInteractiveTools = options.includeInteractiveTools ?? false;
+	const includePanesTools = options.includePanesTools ?? false;
 	const includeNetworkTools = options.includeNetworkTools ?? true;
 	const required = new Set<ToolName>(Object.values(ToolNames));
 	for (const tool of [...required]) {
 		if (!includeSessionTools && SESSION_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeDispatchTools && DISPATCH_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeInteractiveTools && INTERACTIVE_BOUND_TOOLS.has(tool)) required.delete(tool);
+		if (!includePanesTools && PANES_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeNetworkTools && NETWORK_BOUND_TOOLS.has(tool)) required.delete(tool);
 	}
 	for (const tool of required) {

package/src/tools/presentation.ts

@@ -67,6 +67,7 @@ export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>>
 	[ToolNames.Steer]: FOLDED,
 	[ToolNames.Tasks]: FOLDED,
 	[ToolNames.Ledger]: FOLDED,
+	[ToolNames.Panes]: FOLDED,
 	[ToolNames.WebFetch]: FOLDED,
 	[ToolNames.AskUser]: FOLDED,
 	[ToolNames.Artifact]: FOLDED,

package/dist/chunk-D73KXYPF.js

@@ -1,37 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  durableAssistantTextFromEvent
-} from "./chunk-TEO2TLVN.js";
-import {
-  responseModelIdObservationFromRecord
-} from "./chunk-LXPJXFM5.js";
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/tools/dispatch-event-text.ts
-init_esm_shims();
-function assistantTextFromEvent(event) {
-  return durableAssistantTextFromEvent(event).trim();
-}
-function receiptResponseModelIdObservationLabel(receipt) {
-  const responses = receipt.upstreamResponses ?? [];
-  if (responses.length === 0) return null;
-  const labels = responses.map((response) => {
-    const observation = responseModelIdObservationFromRecord(
-      response,
-      "legacy-difference-only"
-    );
-    if (observation.state === "reported") return `reported:${observation.reportedModelId}`;
-    if (observation.state === "not-reported") return "not-reported";
-    if (observation.state === "not-observed") return "not-observed";
-    return `legacy-difference-only:${observation.differingModelId ?? "none"}`;
-  });
-  return `response_model_id_observation=${labels.join(",")}`;
-}
-
-export {
-  assistantTextFromEvent,
-  receiptResponseModelIdObservationLabel
-};
-//# sourceMappingURL=chunk-D73KXYPF.js.map