@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/core/termination.ts

@@ -1,7 +1,7 @@
 /**
  * Shutdown coordinator implementing the four-phase sequence from spec §17:
  *   DRAIN     stop accepting new input / dispatch
- *   TERMINATE kill active workers (wired in Phase 7)
+ *   TERMINATE kill active workers
  *   PERSIST   atomic writes of domain state
  *   EXIT      tear down TUI and process.exit
  *
@@ -29,6 +29,16 @@ interface RegisteredHook {
 	timeoutMs?: number;
 }
 
+function registeredHook(hook: Hook, options?: { timeoutMs: number }): RegisteredHook {
+	if (
+		options &&
+		(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
+	) {
+		throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
+	}
+	return { run: hook, ...options };
+}
+
 /** Wall-clock budget per hook and per domain.stop() call. */
 export const DEFAULT_SHUTDOWN_HOOK_MS = 500;
 
@@ -141,19 +151,13 @@ class TerminationCoordinator {
 	}
 
 	onDrain(hook: Hook, options?: { timeoutMs: number }): void {
-		if (
-			options &&
-			(!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2 ** 31 - 1)
-		) {
-			throw new RangeError("shutdown hook timeout must be a positive 32-bit timer delay");
-		}
-		this.drainHooks.push({ run: hook, ...options });
+		this.drainHooks.push(registeredHook(hook, options));
 	}
-	onTerminate(hook: Hook): void {
-		this.terminateHooks.push({ run: hook });
+	onTerminate(hook: Hook, options?: { timeoutMs: number }): void {
+		this.terminateHooks.push(registeredHook(hook, options));
 	}
-	onPersist(hook: Hook): void {
-		this.persistHooks.push({ run: hook });
+	onPersist(hook: Hook, options?: { timeoutMs: number }): void {
+		this.persistHooks.push(registeredHook(hook, options));
 	}
 
 	async shutdown(code = 0): Promise<void> {

package/src/core/tool-names.ts

@@ -2,15 +2,19 @@
  * Canonical tool names. Everything that dispatches a tool call references these constants
  * so mode matrices, safety classifiers, and audit filters never diverge on spelling.
  *
- * The surface is organized in seven planes; each plane is one policy unit
+ * The surface is organized in eight planes; each plane is one policy unit
  * (action class, size posture, details schema, concurrency rule):
- *   OBSERVE      evidence, read, grep, find, ls, code_nav, context, credential_present
+ *   OBSERVE      evidence, read, grep, find, ls, code_nav, context, credential_present, clio_docs, clio_library, data
  *   MUTATE       write, edit
- *   EXECUTE      bash, git, verify
+ *   EXECUTE      bash, git, verify, run_script
  *   ORCHESTRATE  dispatch, monitor, steer, tasks, ledger, panes, limitation, decide
- *   RETRIEVE     web_fetch
+ *   RETRIEVE     web_read, web_fetch
  *   INTERACT     ask_user
  *   ARTIFACT     artifact
+ *   GATEWAY      gateway
+ *
+ * Placement (which names carry an attached schema and which are reached
+ * through the gateway) is a separate axis, declared in src/tools/surface.ts.
  */
 
 export const ToolNames = {
@@ -23,6 +27,9 @@ export const ToolNames = {
 	CodeNav: "code_nav",
 	Context: "context",
 	CredentialPresent: "credential_present",
+	ClioDocs: "clio_docs",
+	ClioLibrary: "clio_library",
+	Data: "data",
 	// MUTATE
 	Write: "write",
 	Edit: "edit",
@@ -30,6 +37,7 @@ export const ToolNames = {
 	Bash: "bash",
 	Git: "git",
 	Verify: "verify",
+	RunScript: "run_script",
 	// ORCHESTRATE
 	Dispatch: "dispatch",
 	Monitor: "monitor",
@@ -40,19 +48,16 @@ export const ToolNames = {
 	Limitation: "limitation",
 	Decide: "decide",
 	// RETRIEVE
+	WebRead: "web_read",
 	WebFetch: "web_fetch",
 	// INTERACT
 	AskUser: "ask_user",
 	// ARTIFACT
 	Artifact: "artifact",
-	// DESIGN-RESERVED, not implemented: gateway, the MCP/DB proxy. One fixed
-	// schema; external capabilities are surfaced through find/describe/call
-	// RESULTS, never as per-capability schemas in the prompt prefix. Contract
-	// sketch: gateway(op: "find" | "describe" | "call", capability?, args?)
-	// -> JSON capability listings / schemas / call results, network action
-	// class, sequential. Reserving the name here keeps classifiers and
-	// profiles from ever assigning "gateway" to a dynamic tool.
-	// Gateway: "gateway",
+	// GATEWAY: one fixed schema; secondary capabilities are surfaced through
+	// find/describe/call RESULTS, never as per-capability schemas in the
+	// prompt prefix.
+	Gateway: "gateway",
 } as const;
 
 export type BuiltinToolName = (typeof ToolNames)[keyof typeof ToolNames];
@@ -72,3 +77,19 @@ export function isBuiltinToolName(name: ToolName): name is BuiltinToolName {
 export function isHarnessExtensionToolName(name: string): name is DynamicToolName {
 	return name.length <= 64 && /^extension_[a-z0-9][a-z0-9_-]*__[a-z][a-z0-9_]*$/.test(name);
 }
+
+/**
+ * Reserved MCP capability namespace: `mcp_<serverId>__<tool>`. The server id
+ * follows the mcp.yaml id charset; the tool segment keeps the server's own
+ * spelling (letters, digits, `_`, `-`, `.`). Syntax conveys origin, never trust
+ * or availability: the gateway launches only trusted servers.
+ */
+export function isMcpToolName(name: string): name is DynamicToolName {
+	return name.length <= 96 && /^mcp_[a-z0-9][a-z0-9_-]*__[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name);
+}
+
+/** Compose the registry name of one MCP server tool; null when the tool's name cannot be carried. */
+export function mcpToolName(serverId: string, tool: string): DynamicToolName | null {
+	const composed = `mcp_${serverId}__${tool}`;
+	return isMcpToolName(composed) ? composed : null;
+}

package/src/domains/agents/contract.ts

@@ -3,7 +3,7 @@ import type { AgentRecipeDiagnostic } from "./registry.js";
 import type { AgentSpec } from "./spec.js";
 
 export interface AgentsContract {
-	/** Monotonic catalog revision; changes after every successful discovery. */
+	/** Monotonic catalog revision; changes after discovery or external-agent settings updates. */
 	revision(): number;
 	/** Raw recipes as loaded from Markdown files. */
 	list(): ReadonlyArray<AgentRecipe>;

package/src/domains/agents/extension.ts

@@ -29,10 +29,22 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 		rediscoveryPending = false;
 	}
 
-	let unsubscribeExtensionsReload: (() => void) | null = null;
+	let unsubscribePluginsReload: (() => void) | null = null;
+	let unsubscribeConfigChange: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			discover();
+			unsubscribeConfigChange =
+				_context.getContract<ConfigContract>("config")?.onChange("nextTurn", ({ diff }) => {
+					if (
+						diff.nextTurn.some(
+							(path) =>
+								path === "integrations.externalAgents.entries" || path.startsWith("integrations.externalAgents.entries."),
+						)
+					) {
+						revision += 1;
+					}
+				}) ?? null;
 			// Recipes are cached at start; plugin agent roots come from the
 			// committed plugin generation, so a changed generation rediscovers.
 			const onResourceReload = (payload: unknown) => {
@@ -69,17 +81,13 @@ export function createAgentsBundle(_context: DomainContext): DomainBundle<Agents
 					);
 				}
 			};
-			const unsubscribe = [
-				_context.bus.on(BusChannels.ExtensionsReloaded, onResourceReload),
-				_context.bus.on(BusChannels.PluginsReloaded, onResourceReload),
-			];
-			unsubscribeExtensionsReload = () => {
-				for (const stop of unsubscribe) stop();
-			};
+			unsubscribePluginsReload = _context.bus.on(BusChannels.PluginsReloaded, onResourceReload);
 		},
 		async stop() {
-			unsubscribeExtensionsReload?.();
-			unsubscribeExtensionsReload = null;
+			unsubscribePluginsReload?.();
+			unsubscribePluginsReload = null;
+			unsubscribeConfigChange?.();
+			unsubscribeConfigChange = null;
 		},
 	};
 

package/src/domains/config/extension.ts

@@ -116,13 +116,14 @@ export function createConfigBundle(
 		update(mutate) {
 			if (!snapshot) throw new Error("config domain not started");
 			const previous = snapshot;
-			const candidate = structuredClone(previous);
-			mutate(candidate);
-			assertAgentNamespace(candidate);
 			// Apply the effective-view delta to the user document under one lock,
 			// then validate it with the project layers before writing. In particular,
 			// a route may name a target supplied only by this workspace.
-			const normalized = updateLayeredSettings(process.cwd(), mutate);
+			const normalized = updateLayeredSettings(process.cwd(), (candidate) => {
+				const next = mutate(candidate) ?? candidate;
+				assertAgentNamespace(next);
+				return next;
+			});
 			snapshot = normalized;
 			setGitCommitAttributionEnabled(normalized.integrations.git.commitAttribution);
 			const diff = diffSettings(previous, normalized);

package/src/domains/context/clio-md.ts

@@ -130,7 +130,7 @@ function normalizeNestedMarkdown(value: string): string {
 	let cursor = 0;
 	for (const match of mask.matchAll(/^(#{1,2})(\s+)/gm)) {
 		if (match.index === undefined) continue;
-		out += body.slice(cursor, match.index) + "###" + (match[2] ?? "");
+		out += `${body.slice(cursor, match.index)}###${match[2] ?? ""}`;
 		cursor = match.index + match[0].length;
 	}
 	return out + body.slice(cursor);

package/src/domains/context/worker/pressure.ts

@@ -1,4 +1,5 @@
 import type { AgentMessage } from "../../../engine/types.js";
+import { effectiveToolCall } from "../../../tools/surface.js";
 import { estimateAgentContextBreakdown, estimateAgentMessageTokens } from "../../session/context-accounting.js";
 import { contextHash, messageToolCalls } from "./snapshot.js";
 
@@ -93,9 +94,12 @@ export function createWorkerContextGuard(archive: (ref: string, message: AgentMe
 				const projected = { ...message, content };
 				replace(index, message, projected);
 			} else if (message.role === "toolResult" && !message.isError) {
-				const name = toolCalls.get(message.toolCallId)?.name;
+				const call = toolCalls.get(message.toolCallId);
+				// A gateway call carries its capability's read semantics: a page
+				// fetched through the gateway is as evictable as a direct fetch.
+				const name = call ? effectiveToolCall(call.name, call.arguments).toolName : undefined;
 				// Only observations with known read semantics. Preserve mutations and opaque tools.
-				if (!name || !["read", "grep", "find", "ls", "code_nav", "web_fetch"].includes(name)) continue;
+				if (!name || !["read", "grep", "find", "ls", "code_nav", "web_read", "web_fetch"].includes(name)) continue;
 				if (JSON.stringify(message.content).length < 1000) continue;
 				const ref = key(message);
 				const file = archive(ref, structuredClone(message));

package/src/domains/context/working-set/path-index.ts

@@ -25,6 +25,7 @@
  */
 
 import { basename, isAbsolute, join, normalize, resolve } from "node:path";
+import { effectiveToolCall } from "../../../tools/surface.js";
 import type { MessageEntry, SessionEntry } from "../../session/entries.js";
 import type { WorkingSetRef } from "./contract.js";
 import { isTurnStart } from "./horizon.js";
@@ -175,8 +176,12 @@ interface ToolCallFacts {
 	argsKey: string;
 }
 
-function callFacts(toolName: string, args: unknown): ToolCallFacts {
-	return { toolName, args, argsKey: args === undefined ? "" : stableStringify(args) };
+function callFacts(recordedTool: string, recordedArgs: unknown): ToolCallFacts {
+	// A gateway call indexes as the capability it reached (git reads the cwd,
+	// artifact writes its path), never as an opaque `gateway` observation.
+	const effective = effectiveToolCall(recordedTool, recordedArgs);
+	const args = effective.viaGateway ? effective.args : recordedArgs;
+	return { toolName: effective.toolName, args, argsKey: args === undefined ? "" : stableStringify(args) };
 }
 
 function stringField(record: Record<string, unknown> | null, ...keys: string[]): string | null {

package/src/domains/dispatch/code-step.ts

@@ -53,6 +53,8 @@ export interface CodeStepRunInput {
 	workspaceRoot: string;
 	/** Absolute directory the command log is written to; omitted means no artifact. */
 	artifactDir?: string;
+	/** Shared stdout/stderr capture ceiling; defaults to CODE_STEP_CAPTURE_MAX_BYTES. */
+	maxOutputBytes?: number;
 	/** Full process environment the allowlist is drawn from. Defaults to the orchestrator's. */
 	env?: NodeJS.ProcessEnv;
 	/**
@@ -221,6 +223,9 @@ interface SpawnOutcome {
 
 async function spawnCommand(input: CodeStepRunInput, cwd: string, argv: ReadonlyArray<string>): Promise<SpawnOutcome> {
 	const command = input.command;
+	const captureMaxBytes = input.maxOutputBytes ?? CODE_STEP_CAPTURE_MAX_BYTES;
+	if (!Number.isSafeInteger(captureMaxBytes) || captureMaxBytes <= 0)
+		throw new Error("code step: maxOutputBytes must be a positive safe integer");
 	const [executable, ...args] = argv;
 	if (executable === undefined) throw new Error(`code step: command '${command.id}' has no executable`);
 	return await new Promise<SpawnOutcome>((resolvePromise) => {
@@ -247,8 +252,8 @@ async function spawnCommand(input: CodeStepRunInput, cwd: string, argv: Readonly
 		});
 		const collect = (chunk: Buffer, stdout: boolean): void => {
 			outputBytes += chunk.length;
-			if (captured >= CODE_STEP_CAPTURE_MAX_BYTES) return;
-			const room = CODE_STEP_CAPTURE_MAX_BYTES - captured;
+			if (captured >= captureMaxBytes) return;
+			const room = captureMaxBytes - captured;
 			const slice = chunk.length <= room ? chunk : chunk.subarray(0, room);
 			chunks.push(slice);
 			if (stdout) stdoutChunks.push(slice);

package/src/domains/dispatch/contract.ts

@@ -348,6 +348,13 @@ export interface DispatchContract {
 	 */
 	abort(runId: string, reason?: AbortReason): void;
 
+	/**
+	 * Wait for one member's attempts, queued retries and retry admissions to
+	 * settle. Does not cancel work; fleet owners call synchronous abort first
+	 * when stopping. Other members and the global drain lifecycle are untouched.
+	 */
+	drainMember?(runId: string): Promise<void>;
+
 	/**
 	 * Queue operator guidance on a running HTTP or SDK worker. A logical
 	 * assignment id addresses its current attempt. The text is sent as a JSON

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

@@ -51,7 +51,7 @@ export type GateTopologyRole = "builder" | "reviewer" | "candidate" | "judge" |
 
 /**
  * Facts the role is derived from. `capabilityClass` and `resultContractKind`
- * both come from the strict Slice 2 recipe schema, so a role can never be read
+ * both come from the strict recipe schema, so a role can never be read
  * off free-form prose or a display-only field.
  */
 export interface ExecutionRoleInput {
@@ -79,7 +79,7 @@ export interface ExecutionRoleInput {
  *   3. Outside a gate, the recipe's own typed contract decides. A declared
  *      `verifier-report` is the only contract that makes a direct run a
  *      verifier; a Debugger's `debugger-report` deliberately does not, because
- *      Slice 2 forbids it from masquerading as a gate verdict.
+ *      the result schema distinguishes diagnosis from a gate verdict.
  *   4. A read-only recipe with no verifier contract is reconnaissance.
  */
 export function deriveExecutionRole(input: ExecutionRoleInput): ExecutionRole {
@@ -151,7 +151,7 @@ export function withAttemptRole(requestRole: ExecutionRole, attempt: number): Ex
  * Defaulting a reviewer or judge to the builder agent makes the gate a
  * self-review: the same recipe, the same prompt surface, and usually the same
  * model family grading its own output. That verdict is correlated by
- * construction and Slice 1 already refuses to treat it as a quality label, so
+ * construction and cannot count as an independent quality label, so
  * the default has to be an agent whose entire contract is independent typed
  * validation.
  */