@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/tools/builtin-tool-catalog.ts

@@ -0,0 +1,265 @@
+import { type ToolName, ToolNames } from "../core/tool-names.js";
+import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { readMaxBytes } from "./read.js";
+import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
+
+function withSourceInfo<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
+	return { ...spec, sourceInfo };
+}
+
+function withMetadata<T extends ToolSpec>(spec: T, metadata: ToolMetadata): T {
+	return { ...spec, metadata };
+}
+
+// Registry-backstop caps derive from the OBSERVE self-caps in
+// src/tools/observation.ts: policy cap = self cap + slack, so a tool's own
+// envelope notice (with its exact continuation call) survives shaping instead
+// of being cut again and replaced by a generic hint. The 16KB summary
+// policies are the explicit overrides for tools whose output is inherently
+// aggregate (shell, verification runs, git, dispatch receipts, web pages).
+const policyCap = (selfCapBytes: number): number => selfCapBytes + OBSERVATION_POLICY_SLACK_BYTES;
+
+const observePolicy = (selfCapBytes: number, followUpHint: string) =>
+	({ kind: "bounded", maxBytes: policyCap(selfCapBytes), followUpHint }) satisfies ToolMetadata["resultSizePolicy"];
+
+const summaryPolicy = (followUpHint: string) =>
+	({ kind: "summary", maxBytes: 16_384, followUpHint }) satisfies ToolMetadata["resultSizePolicy"];
+
+const exactMutationPolicy = {
+	kind: "exact",
+	maxBytes: 8_192,
+	followUpHint: "Inspect the changed file or git diff for exact follow-up context.",
+} satisfies ToolMetadata["resultSizePolicy"];
+
+// Per-tool metadata, organized by plane. OBSERVE tools share the observation
+// envelope, the turn budget pool, and derived policy caps; every other plane
+// declares its posture explicitly.
+const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
+	// OBSERVE: read-class, parallel, envelope + shared turn budget.
+	[ToolNames.Read]: {
+		objective: "Read exact UTF-8 file content with line and byte bounds.",
+		uiLabel: "Read",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			readMaxBytes(),
+			"Use offset/limit or a narrower locate/search tool call to inspect omitted content.",
+		),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Grep]: {
+		objective: "Search file contents and return line-referenced matches.",
+		uiLabel: "Grep",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			OBSERVE_SELF_CAPS.grepContent,
+			"Refine the pattern, path, glob, context, or limit, or use mode=files, to inspect omitted matches.",
+		),
+		costLatency: "local_medium",
+	},
+	[ToolNames.Find]: {
+		objective: "Find paths by glob pattern with optional mtime ordering.",
+		uiLabel: "Find",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			OBSERVE_SELF_CAPS.find,
+			"Refine the pattern, path, or limit to inspect omitted paths.",
+		),
+		costLatency: "local_medium",
+	},
+	[ToolNames.Ls]: {
+		objective: "List directory entries.",
+		uiLabel: "List",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(OBSERVE_SELF_CAPS.ls, "Raise limit or list a narrower directory."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.CodeNav]: {
+		objective: "Navigate the codewiki index by symbol, path, entry points, outline, imports, or importers.",
+		uiLabel: "Nav",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(OBSERVE_SELF_CAPS.codeNav, "Raise limit or use a narrower mode/query."),
+		costLatency: "local_fast",
+		promptHint:
+			"Use code_nav for indexed code navigation (modes: symbol, path, entries, outline, deps, dependents, wiki).",
+	},
+	[ToolNames.Context]: {
+		objective: "Return workspace, bundled-docs, or skill context.",
+		uiLabel: "Context",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			Math.max(OBSERVE_SELF_CAPS.contextDocs, OBSERVE_SELF_CAPS.contextSkills, OBSERVE_SELF_CAPS.contextWorkspace),
+			"Use a narrower query or scope to inspect omitted content.",
+		),
+		costLatency: "local_fast",
+		promptHint:
+			'Call context with scope="skills" to list installed and marketplace skills; when one matches the task, or the operator names a skill or asks how one works, suggest the operator run /skill <name> (a marketplace skill is offered for install) and never load it uninvited. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else.',
+	},
+	[ToolNames.CredentialPresent]: {
+		objective: "Check whether a credential key is present without returning its value.",
+		uiLabel: "Credential",
+		retrySafety: "idempotent",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "Use the boolean result only; never ask to print the credential value.",
+		},
+		costLatency: "local_fast",
+	},
+	// MUTATE: write-class, sequential, file-mutation queue.
+	[ToolNames.Write]: {
+		objective: "Write a complete UTF-8 file.",
+		uiLabel: "Write",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+	[ToolNames.Edit]: {
+		objective: "Apply exact text replacements to one file.",
+		uiLabel: "Edit",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+	// EXECUTE: the safe-exec spine (bash offloads its own overflow).
+	[ToolNames.Bash]: {
+		objective: "Execute an explicit shell command when narrower tools are insufficient.",
+		uiLabel: "Shell",
+		retrySafety: "unknown",
+		resultSizePolicy: summaryPolicy(
+			"Use a narrower command or a dedicated verification/read/search tool to inspect omitted output.",
+		),
+		costLatency: "local_slow",
+	},
+	[ToolNames.Git]: {
+		objective: "Read-only git inspection: status, diff, or log.",
+		uiLabel: "Git",
+		retrySafety: "idempotent",
+		resultSizePolicy: summaryPolicy("Limit the diff/log to one path or fewer commits."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Verify]: {
+		objective: "Run declared verification checks (scripts or frontend artifacts).",
+		uiLabel: "Verify",
+		retrySafety: "retry_safe",
+		resultSizePolicy: summaryPolicy(
+			"Rerun the check with narrower args or inspect the named failing file/test directly.",
+		),
+		costLatency: "local_slow",
+	},
+	// ORCHESTRATE: agent-class, receipts as evidence.
+	[ToolNames.Tasks]: {
+		objective: "Declare and track the session task board with evidence-carrying completions.",
+		uiLabel: "Tasks",
+		// A repeated plan/start/done lands on the same board state; a repeated
+		// add duplicates a task, so the surface as a whole is not retry safe.
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 8_192,
+			followUpHint: 'Call tasks with action="list" to re-read the board.',
+		},
+		costLatency: "local_fast",
+		promptHint:
+			'When a request contains three or more distinct steps, declare the board before your first edit: tasks action="plan" with a title and the task list. ' +
+			'Mark one task active with "start" before working it, close it with "done" plus an evidence note ' +
+			'(what proves it works), and use "block" with a reason instead of silently stalling.',
+	},
+	[ToolNames.Ledger]: {
+		objective: "Coordinate with the peer workers of this dispatch through typed claims, findings, and reviews.",
+		uiLabel: "Ledger",
+		// A repeated post lands a second entry and spends another of the run's
+		// twenty posts, so the surface as a whole is not retry safe.
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 16_384,
+			followUpHint: 'Call ledger with action="read" and a since sequence to re-read only what is new.',
+		},
+		costLatency: "local_fast",
+	},
+	[ToolNames.Dispatch]: {
+		objective: "Dispatch bounded tasks to configured Clio workers.",
+		uiLabel: "Dispatch",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: summaryPolicy(
+			"Use the dispatch receipt paths or ask a narrower worker follow-up for omitted output.",
+		),
+		costLatency: "agent",
+		promptHint:
+			"Call dispatch with list:true only when the operator asks about agents, workers, or the fleet; never use it to inventory direct tools.",
+	},
+	[ToolNames.Monitor]: {
+		objective: "Inspect dispatched runs: state, recent events, receipts.",
+		uiLabel: "Monitor",
+		retrySafety: "idempotent",
+		resultSizePolicy: summaryPolicy("Use monitor(mode=receipt) or read the receipt path for full details."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Steer]: {
+		objective: "Guide or cancel a running dispatched worker.",
+		uiLabel: "Steer",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "Use monitor(mode=status) to confirm the run state after steering.",
+		},
+		costLatency: "local_fast",
+	},
+	// RETRIEVE: network-class.
+	[ToolNames.WebFetch]: {
+		objective: "Fetch HTTP(S) text for explicit external research.",
+		uiLabel: "Fetch",
+		retrySafety: "retry_safe",
+		resultSizePolicy: {
+			kind: "bounded",
+			maxBytes: 16_384,
+			followUpHint: "Fetch a narrower URL or lower max_bytes to inspect a specific section.",
+		},
+		costLatency: "network",
+	},
+	// INTERACT: operator dialogue.
+	[ToolNames.AskUser]: {
+		objective: "Ask the operator structured questions.",
+		uiLabel: "Ask",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 20_000,
+			followUpHint: "Proceed with stated assumptions if the operator cancels or no UI is available.",
+		},
+		costLatency: "local_slow",
+		promptHint:
+			'Use ask_user only when blocked on a decision the request does not answer; never ask about anything the operator already stated. One question per round in interview workflows, up to four tightly related questions otherwise, recommended option first. Finish with action="complete" and a compact decisions array before final prose. If cancelled, continue with defaults and do not ask again.',
+	},
+	// ARTIFACT: terminal writers.
+	[ToolNames.Artifact]: {
+		objective: "Write terminal plan/review/report documents that complete the turn.",
+		uiLabel: "Artifact",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+};
+
+/** Canonical, registry-owned prompt hints for an already-admitted tool set. */
+export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): ReadonlyArray<{ tool: string; hint: string }> {
+	const seen = new Set<string>();
+	const hints: Array<{ tool: string; hint: string }> = [];
+	for (const name of [...names].sort()) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		const hint = TOOL_METADATA[name]?.promptHint?.trim();
+		if (hint) hints.push({ tool: name, hint });
+	}
+	return hints;
+}
+
+function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
+	const metadata = TOOL_METADATA[spec.name];
+	return metadata ? withMetadata(spec, metadata) : spec;
+}
+
+export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
+	return withBuiltinMetadata(withSourceInfo(spec, sourceInfo));
+}

package/src/tools/codewiki/code-nav-surface.ts

@@ -0,0 +1,29 @@
+import { Type } from "typebox";
+import { ToolNames } from "../../core/tool-names.js";
+import { StringEnum } from "../../engine/ai.js";
+import type { ToolSurface } from "../lazy-tool.js";
+
+export const CODE_NAV_DEFAULT_LIMIT = 50;
+export const CODE_NAV_DEFAULT_ENTRY_LIMIT = 25;
+export const CODE_NAV_MAX_LIMIT = 200;
+
+export const codeNavToolSurface = {
+	name: ToolNames.CodeNav,
+	description:
+		"Navigate the indexed codewiki: mode=symbol finds files by symbol, path finds files by glob/regex/substring, entries lists likely entry points, outline lists file symbols, deps lists imports, and dependents lists importers. mode=wiki without query lists generated Markdown wiki pages; with query it resolves a page id/title and returns its summary plus a path to open with read. For Clio's bundled product docs use context scope=docs.",
+	parameters: Type.Object({
+		mode: StringEnum(["symbol", "path", "entries", "outline", "deps", "dependents", "wiki"], {
+			description: "Lookup mode.",
+		}),
+		query: Type.Optional(
+			Type.String({ description: "Symbol name, indexed path/pattern/substring, or wiki page id/title." }),
+		),
+		limit: Type.Optional(
+			Type.Number({
+				description: `Max results (default ${CODE_NAV_DEFAULT_LIMIT}, entries ${CODE_NAV_DEFAULT_ENTRY_LIMIT}, max ${CODE_NAV_MAX_LIMIT}).`,
+			}),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+} satisfies ToolSurface;

package/src/tools/codewiki/code-nav.ts

@@ -1,8 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, normalize } from "node:path";
-import { Type } from "typebox";
 import { ToolNames } from "../../core/tool-names.js";
-import type { Codewiki, CodewikiFile, CodewikiSymbol } from "../../domains/context/codewiki/indexer.js";
+import type { Codewiki, CodewikiFile, CodewikiSymbol } from "../../domains/context/codewiki/schema.js";
 import { listWikiPages } from "../../domains/context/wiki/layout.js";
 import { readWikiMeta } from "../../domains/context/wiki/meta.js";
 import { wikiCompletenessFromMeta, wikiStaleness } from "../../domains/context/wiki/staleness.js";
@@ -14,13 +13,15 @@ import {
 	reserveObservation,
 } from "../observation.js";
 import type { ToolResult, ToolSpec } from "../registry.js";
-import { stringEnum } from "../string-enum.js";
+import {
+	codeNavToolSurface,
+	CODE_NAV_DEFAULT_ENTRY_LIMIT as DEFAULT_ENTRY_LIMIT,
+	CODE_NAV_DEFAULT_LIMIT as DEFAULT_LIMIT,
+	CODE_NAV_MAX_LIMIT as MAX_LIMIT,
+} from "./code-nav-surface.js";
 import { loadCodewikiForTool, renderJson } from "./shared.js";
 
 const REGEX_SYNTAX_HINTS = /\.\*|\.\+|\^|\$|\\[dDwWsSbB]|\(\?:|\(\?=|\(\?!/;
-const DEFAULT_LIMIT = 50;
-const DEFAULT_ENTRY_LIMIT = 25;
-const MAX_LIMIT = 200;
 
 interface NavIndex {
 	filesById: Map<string, CodewikiFile>;
@@ -485,22 +486,7 @@ function parseLimit(value: unknown, fallback: number): number {
 }
 
 export const codeNavTool: ToolSpec = {
-	name: ToolNames.CodeNav,
-	description:
-		"Navigate the indexed codewiki: mode=symbol finds files by symbol, path finds files by glob/regex/substring, entries lists likely entry points, outline lists file symbols, deps lists imports, and dependents lists importers. mode=wiki without query lists generated Markdown wiki pages; with query it resolves a page id/title and returns its summary plus a path to open with read. For Clio's bundled product docs use context scope=docs.",
-	parameters: Type.Object({
-		mode: stringEnum(["symbol", "path", "entries", "outline", "deps", "dependents", "wiki"], "Lookup mode."),
-		query: Type.Optional(
-			Type.String({ description: "Symbol name, indexed path/pattern/substring, or wiki page id/title." }),
-		),
-		limit: Type.Optional(
-			Type.Number({
-				description: `Max results (default ${DEFAULT_LIMIT}, entries ${DEFAULT_ENTRY_LIMIT}, max ${MAX_LIMIT}).`,
-			}),
-		),
-	}),
-	baseActionClass: "read",
-	executionMode: "parallel",
+	...codeNavToolSurface,
 	async run(args, options): Promise<ToolResult> {
 		const mode = typeof args.mode === "string" ? args.mode : "";
 		const loaded = await loadCodewikiForTool();

package/src/tools/codewiki/shared.ts

@@ -1,20 +1,14 @@
 import { statSync } from "node:fs";
-import {
-	buildCodewiki,
-	type Codewiki,
-	codewikiNeedsBackfill,
-	codewikiPath,
-	readCodewiki,
-	syncCodewiki,
-	writeCodewiki,
-} from "../../domains/context/codewiki/indexer.js";
-import { computeFingerprint, isStale } from "../../domains/context/fingerprint.js";
+import { codewikiPath, readCodewiki } from "../../domains/context/codewiki/artifact.js";
+import { coordinateCodewikiWrite } from "../../domains/context/codewiki/coordinator.js";
+import type { Codewiki } from "../../domains/context/codewiki/schema.js";
 import { readClioState, writeClioState } from "../../domains/context/state.js";
-import { detectProjectType } from "../../domains/session/workspace/project-type.js";
 
 const CODEWIKI_ARTIFACT_CACHE_LIMIT = 4;
 
 interface CodewikiArtifactIdentity {
+	dev: bigint;
+	ino: bigint;
 	mtimeNs: bigint;
 	size: bigint;
 }
@@ -30,14 +24,14 @@ function codewikiArtifactIdentity(cwd: string): CodewikiArtifactIdentity | null
 	try {
 		const stats = statSync(codewikiPath(cwd), { bigint: true });
 		if (!stats.isFile()) return null;
-		return { mtimeNs: stats.mtimeNs, size: stats.size };
+		return { dev: stats.dev, ino: stats.ino, mtimeNs: stats.mtimeNs, size: stats.size };
 	} catch {
 		return null;
 	}
 }
 
 function sameArtifactIdentity(a: CodewikiArtifactIdentity, b: CodewikiArtifactIdentity): boolean {
-	return a.mtimeNs === b.mtimeNs && a.size === b.size;
+	return a.dev === b.dev && a.ino === b.ino && a.mtimeNs === b.mtimeNs && a.size === b.size;
 }
 
 function rememberCodewikiArtifact(cwd: string, identity: CodewikiArtifactIdentity, codewiki: Codewiki): void {
@@ -75,35 +69,44 @@ function readCodewikiForTool(cwd: string): Codewiki | null {
 export async function loadCodewikiForTool(
 	cwd: string = process.cwd(),
 ): Promise<{ ok: true; codewiki: Codewiki } | { ok: false; message: string }> {
-	const codewiki = readCodewikiForTool(cwd);
-	const state = readClioState(cwd);
-	if (codewiki && !codewikiNeedsBackfill(codewiki)) {
-		const fingerprint = computeFingerprint(cwd, codewiki);
-		if (state && !isStale(state.fingerprint, fingerprint)) return { ok: true, codewiki };
-	}
 	try {
 		const generatedAt = new Date().toISOString();
-		const projectType = detectProjectType(cwd);
-		const rebuilt = codewiki
-			? await syncCodewiki(cwd, codewiki)
-			: await buildCodewiki({ cwd, language: projectType, generatedAt });
+		const coordinated = await coordinateCodewikiWrite(
+			cwd,
+			(current, workspace) => {
+				const language = readClioState(workspace)?.projectType ?? current?.language;
+				return {
+					kind: "ensure",
+					cwd,
+					...(language ? { language } : {}),
+					current,
+					previous: readClioState(workspace)?.fingerprint ?? null,
+				};
+			},
+			{
+				readCurrent: (workspace) => readCodewikiForTool(workspace) ?? undefined,
+				afterCommit: ({ codewiki: committed, fingerprint, changed }, workspace) => {
+					const prev = readClioState(workspace);
+					if (!changed && prev) return;
+					writeClioState(workspace, {
+						version: 1,
+						projectType: prev?.projectType ?? committed.language,
+						fingerprint,
+						codewikiVersion: committed.version,
+						...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
+						...(prev?.contextSourceHash ? { contextSourceHash: prev.contextSourceHash } : {}),
+						...(prev?.lastBootstrap ? { lastBootstrap: prev.lastBootstrap } : {}),
+						...(prev?.lastInitAt ? { lastInitAt: prev.lastInitAt } : {}),
+						lastSessionAt: prev?.lastSessionAt ?? generatedAt,
+						lastIndexedAt: generatedAt,
+					});
+				},
+			},
+		);
+		if (!coordinated) throw new Error("codewiki coordinator did not admit the demand build");
 		// Not cached here: a post-write stat could pair a concurrent writer's identity
 		// with this object. The next call re-reads once and caches from a clean stat.
-		writeCodewiki(cwd, rebuilt);
-		const prev = state;
-		writeClioState(cwd, {
-			version: 1,
-			projectType: prev?.projectType ?? projectType,
-			fingerprint: computeFingerprint(cwd, rebuilt),
-			codewikiVersion: rebuilt.version,
-			...(prev?.contextSources ? { contextSources: prev.contextSources } : {}),
-			...(prev?.contextSourceHash ? { contextSourceHash: prev.contextSourceHash } : {}),
-			...(prev?.lastBootstrap ? { lastBootstrap: prev.lastBootstrap } : {}),
-			...(prev?.lastInitAt ? { lastInitAt: prev.lastInitAt } : {}),
-			lastSessionAt: prev?.lastSessionAt ?? generatedAt,
-			lastIndexedAt: generatedAt,
-		});
-		return { ok: true, codewiki: rebuilt };
+		return { ok: true, codewiki: coordinated.codewiki };
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		return { ok: false, message: `codewiki unavailable. run /context refresh to rebuild it. ${msg}` };

package/src/tools/context/docs-engine.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { resolvePackageRoot } from "../../core/package-root.js";
 
 // Deterministic, dependency-free retrieval over Clio's bundled human docs,
@@ -323,7 +323,18 @@ function buildDocumentFrequency(sections: ReadonlyArray<IndexedSection>): Map<st
 function loadDocsIndex(): { ok: true; index: DocsIndex } | { ok: false; message: string } {
 	let root: string;
 	try {
-		root = resolvePackageRoot();
+		// resolvePackageRoot() caches its answer for the life of the process, so
+		// once any caller has resolved it, a later CLIO_CODER_PACKAGE_ROOT change
+		// (a test fixture, most commonly) has no effect on that cached value.
+		// Reading the override directly here, rather than trusting the shared
+		// cache, keeps this module's notion of "docs root" live even when it
+		// isn't the first thing in the process to have resolved a package root.
+		const override = process.env.CLIO_CODER_PACKAGE_ROOT?.trim();
+		if (override) {
+			root = resolve(override);
+		} else {
+			root = resolvePackageRoot();
+		}
 	} catch (err) {
 		return { ok: false, message: err instanceof Error ? err.message : String(err) };
 	}
@@ -536,7 +547,7 @@ function resultPayload(index: DocsIndex, plan: QueryPlan, scored: ReadonlyArray<
 		results,
 		followUp:
 			results.length > 0
-				? "Cited files are Clio's bundled docs, not workspace paths; never read or search for them as files. For more depth, run another context scope=docs query with more specific terms."
+				? "Cited files are Clio's bundled docs: read them from the installed documentation path named in your prompt, never by searching the workspace for them. For more depth, run another context scope=docs query with more specific terms."
 				: "Try Clio vocabulary such as target, autonomy, dispatch, evidence, middleware, context, validation, install, or model catalog.",
 	};
 }