@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/tools/context/index.ts

@@ -1,12 +1,13 @@
 import { type Dirent, readdirSync } from "node:fs";
 import path from "node:path";
-import { Type } from "typebox";
 import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
 import { ToolNames } from "../../core/tool-names.js";
 import {
 	checkSkillDrift,
+	discoverMarketplaceSkills,
 	type LoadSkillsInput,
 	loadSkills,
+	type MarketplaceSkill,
 	modelVisibleSkills,
 	type Skill,
 } from "../../domains/resources/index.js";
@@ -19,9 +20,9 @@ import {
 	reserveObservation,
 } from "../observation.js";
 import type { ToolInvokeOptions, ToolResult, ToolSpec } from "../registry.js";
-import { stringEnum } from "../string-enum.js";
 import { truncateHead } from "../truncate.js";
 import { listDocsCorpus, searchDocs } from "./docs-engine.js";
+import { contextToolSurface } from "./surface.js";
 
 /**
  * The context tool: one OBSERVE entry point for material about the working
@@ -49,6 +50,13 @@ export interface ContextToolDeps {
 	>;
 	/** Absent in worker registries without a session; scope=workspace errors cleanly. */
 	workspace?: ContextWorkspaceDeps;
+	/**
+	 * Whether scope=skills may list marketplace entries beside installed
+	 * skills. Worker registries set false: a worker can neither install a
+	 * skill nor address the operator who could, so installable rows would only
+	 * invite a load the pending-skill policy rejects. Undefined means true.
+	 */
+	skillMarketplace?: boolean;
 }
 
 function cwdFromDeps(deps?: ContextToolDeps): string {
@@ -187,14 +195,69 @@ function renderPendingSkillTask(name: string, options: ToolInvokeOptions | undef
 	return lines;
 }
 
-function renderSkillsList(skills: ReadonlyArray<Skill>): string {
-	if (skills.length === 0) return "No skills are installed.";
+/**
+ * Marketplace rows the listing may show. Absent for every worker registry
+ * (`skillMarketplace: false`), when discovery is switched off for the run
+ * (a `--no-skills` run), and for a recipe-bound policy, whose
+ * context(scope=skills) admits exactly its bound names: none of these can
+ * install anything, so installable rows would only invite a load the policy
+ * rejects. Whatever discovery reports as broken stays out of the listing; the
+ * CLI and the hub carry those diagnostics.
+ */
+function marketplaceRowsFor(
+	deps: ContextToolDeps,
+	installed: ReadonlyArray<Skill>,
+	options: ToolInvokeOptions | undefined,
+): MarketplaceSkill[] {
+	if (deps.skillMarketplace === false) return [];
+	if (deps.getSkillLoaderOptions?.().disableDiscovery === true) return [];
+	const policy = options?.pendingSkillPolicy;
+	if (policy && policyIsRecipeBound(policy)) return [];
+	const installedNames = new Set(installed.map((skill) => skill.name));
+	try {
+		return discoverMarketplaceSkills({ cwd: cwdFromDeps(deps) }).skills.filter(
+			(entry) => !installedNames.has(entry.name),
+		);
+	} catch {
+		return [];
+	}
+}
+
+function renderSkillsList(
+	skills: ReadonlyArray<Skill>,
+	marketplace: ReadonlyArray<MarketplaceSkill>,
+	marketplaceOffered: boolean,
+): string {
+	if (skills.length === 0 && marketplace.length === 0) {
+		// A registry that never offers the marketplace (a worker) must not
+		// claim none is configured; it simply has nothing to list.
+		return marketplaceOffered ? "No skills are installed and no marketplace is configured." : "No skills are installed.";
+	}
 	const lines = [
-		"Available skills. Match the current task against the descriptions below: when one fits, suggest the operator run /skill:<name>; when several compose, suggest the sequence in order. Skill bodies load only after an explicit operator request; never load one without it.",
+		"Available skills. Match the current task against the descriptions below: when one fits, suggest the operator run /skill <name>; when several compose, suggest the sequence in order. Skill bodies load only after an explicit operator request; never load one without it.",
 		"",
 	];
-	for (const skill of skills) {
-		lines.push(`- ${skill.name} (${skill.scope}): ${skill.description}`);
+	if (skills.length > 0) {
+		lines.push("Installed:");
+		for (const skill of skills) {
+			lines.push(`- ${skill.name} (${skill.scope}): ${skill.description}`);
+		}
+	} else {
+		lines.push("Installed: none.");
+	}
+	if (marketplace.length > 0) {
+		// Installable rows are suggested exactly like installed ones: the
+		// operator's /skill <name> prompts to install before it runs, so the
+		// model's move is the same suggest-and-wait. Only the body is out of
+		// reach until then, which is why the description is all that appears.
+		lines.push(
+			"",
+			"Marketplace (not installed; /skill <name> offers to install, or `clio-coder skills install <name>`). Suggest these the same way when one matches; their bodies cannot be loaded until the operator installs them:",
+		);
+		for (const entry of marketplace) {
+			const category = entry.category ? ` [${entry.category}]` : "";
+			lines.push(`- ${entry.name}${category}: ${entry.description}`);
+		}
 	}
 	// Recency anchor with an exact reply shape: literal models act on an output
 	// template where they skip conditional prose in the header.
@@ -237,17 +300,20 @@ function runWorkspaceScope(
 }
 
 function withSkillsPointer(deps: ContextToolDeps, snap: WorkspaceSnapshot): Record<string, unknown> {
-	let count = 0;
+	let installed = 0;
+	let installable = 0;
 	try {
 		const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
-		count = modelVisibleSkills(list.items).length;
+		const visible = modelVisibleSkills(list.items);
+		installed = visible.length;
+		installable = marketplaceRowsFor(deps, visible, undefined).length;
 	} catch {
 		return { ...snap };
 	}
-	if (count === 0) return { ...snap };
+	if (installed === 0 && installable === 0) return { ...snap };
 	return {
 		...snap,
-		skills: `Installed skills: ${count}. If one matches this task, list them with context(scope="skills") and suggest /skill:<name> to the operator; load only on operator request.`,
+		skills: `Skills: ${installed} installed, ${installable} installable from the marketplace. If one matches this task, or the operator names a skill, list them with context(scope="skills") and suggest /skill <name> to the operator; load only on operator request.`,
 	};
 }
 
@@ -303,14 +369,28 @@ function runSkillsScope(
 	if (name.length === 0) {
 		const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
 		const visible = modelVisibleSkills(list.items);
+		const marketplace = marketplaceRowsFor(deps, visible, options);
+		const rendered = renderSkillsList(visible, marketplace, deps.skillMarketplace !== false);
+		// The catalog is bounded but not small: the whole listing must fit the
+		// per-call cap like any observation, and a cut list says so instead of
+		// silently dropping the marketplace tail.
+		const truncation = truncateHead(rendered, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
+		const total = visible.length + marketplace.length;
 		return finalizeObservation({
 			tool: ToolNames.Context,
 			unit: "entries",
-			output: renderSkillsList(visible),
-			shownCount: visible.length,
-			totalCount: visible.length,
-			truncated: false,
-			details: { skills: visible.map((skill) => ({ name: skill.name, scope: skill.scope })) },
+			output: truncation.content,
+			...(truncation.truncated ? { fullOutput: rendered } : {}),
+			shownCount: total,
+			totalCount: total,
+			truncated: truncation.truncated,
+			details: {
+				skills: visible.map((skill) => ({ name: skill.name, scope: skill.scope })),
+				marketplace: marketplace.map((entry) => ({
+					name: entry.name,
+					...(entry.category ? { category: entry.category } : {}),
+				})),
+			},
 			reservation,
 			...(options ? { options } : {}),
 		});
@@ -321,6 +401,16 @@ function runSkillsScope(
 	const visible = modelVisibleSkills(list.items);
 	const skill = visible.find((item) => item.name === name);
 	if (!skill) {
+		// A marketplace entry is a skill that exists and is not installed. Saying
+		// "unknown skill" about it denies the operator a thing the listing just
+		// offered; name the state and the one move that changes it.
+		const installable = marketplaceRowsFor(deps, visible, options).some((entry) => entry.name === name);
+		if (installable) {
+			return {
+				kind: "error",
+				message: `context: skill "${name}" is not installed; it is available in the marketplace. Ask the operator to run /skill ${name}, which offers to install it, and wait. Do not retry this load.`,
+			};
+		}
 		const available = visible.map((item) => item.name).join(", ");
 		const suffix = available.length > 0 ? ` Available skills: ${available}.` : " No skills are currently available.";
 		return { kind: "error", message: `context: unknown skill "${name}".${suffix}` };
@@ -394,18 +484,7 @@ function runSkillsScope(
 
 export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 	return {
-		name: ToolNames.Context,
-		description:
-			"Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists available skills or loads one by name. For repository code and the repo's generated wiki use code_nav (mode=wiki).",
-		parameters: Type.Object({
-			scope: stringEnum(["workspace", "docs", "skills"], "Context source."),
-			query: Type.Optional(Type.String({ description: "scope=docs: question or terms; omit to list the corpus." })),
-			name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
-			limit: Type.Optional(Type.Number({ description: "scope=docs: max sections (default 5, max 12)." })),
-			include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
-		}),
-		baseActionClass: "read",
-		executionMode: "parallel",
+		...contextToolSurface,
 		async run(args, options): Promise<ToolResult> {
 			const scope = typeof args.scope === "string" ? args.scope : "";
 			if (scope !== "workspace" && scope !== "docs" && scope !== "skills") {

package/src/tools/context/surface.ts

@@ -0,0 +1,19 @@
+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 contextToolSurface = {
+	name: ToolNames.Context,
+	description:
+		"Environment context: scope=workspace returns the git/project snapshot, scope=docs searches Clio's bundled documentation (omit query to list the corpus), scope=skills lists installed and marketplace skills or loads an installed one by name. For repository code and the repo's generated wiki use code_nav (mode=wiki).",
+	parameters: Type.Object({
+		scope: StringEnum(["workspace", "docs", "skills"], { description: "Context source." }),
+		query: Type.Optional(Type.String({ description: "scope=docs: question or terms; omit to list the corpus." })),
+		name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
+		limit: Type.Optional(Type.Number({ description: "scope=docs: max sections (default 5, max 12)." })),
+		include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+} satisfies ToolSurface;

package/src/tools/core-bootstrap.ts

@@ -0,0 +1,168 @@
+import type { LoadSkillsInput } from "../domains/resources/index.js";
+import type { SessionContract } from "../domains/session/contract.js";
+import { createTaskBoardStore, type TaskBoardStore } from "../domains/session/task-board.js";
+import type { UserTasksStore } from "../domains/user-tasks/store.js";
+import type { AgentLedgerPort } from "../worker/protocol.js";
+import { createArtifactTool } from "./artifact.js";
+import { type AskUserHandler, createAskUserTool } from "./ask-user.js";
+import { bashTool } from "./bash.js";
+import { builtin } from "./builtin-tool-catalog.js";
+import { codeNavToolSurface } from "./codewiki/code-nav-surface.js";
+import { contextToolSurface } from "./context/surface.js";
+import { credentialPresentTool } from "./credential-present.js";
+import { editTool } from "./edit.js";
+import { findTool } from "./find.js";
+import { grepTool } from "./grep.js";
+import { lazyTool } from "./lazy-tool.js";
+import { createLedgerTool } from "./ledger.js";
+import { lsTool } from "./ls.js";
+import { networkToolsDisabled } from "./network-policy.js";
+import { assertBuiltinToolPolicy } from "./policy.js";
+import { readTool } from "./read.js";
+import type { ToolRegistry } from "./registry.js";
+import { gitTool } from "./safe-exec.js";
+import { createTasksTool } from "./tasks.js";
+import { verifyToolSurface } from "./verify/surface.js";
+import { webFetchToolSurface } from "./web-fetch-surface.js";
+import { writeTool } from "./write.js";
+
+export interface CoreToolBootstrapDeps {
+	session?: SessionContract;
+	askUser?: AskUserHandler;
+	taskBoard?: TaskBoardStore;
+	userTasks?: UserTasksStore;
+	agentLedger?: AgentLedgerPort;
+	getSkillLoaderOptions?: () => Pick<
+		LoadSkillsInput,
+		"trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths"
+	>;
+	skillMarketplace?: boolean;
+}
+
+export interface CoreToolRegistration {
+	includeNetworkTools: boolean;
+	includeSessionTools: boolean;
+	includeInteractiveTools: boolean;
+}
+
+export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstrapDeps = {}): CoreToolRegistration {
+	const includeNetworkTools = !networkToolsDisabled();
+	registry.register({
+		...builtin(readTool, { path: "src/tools/read.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(writeTool, { path: "src/tools/write.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(editTool, { path: "src/tools/edit.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(bashTool, { path: "src/tools/bash.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(grepTool, { path: "src/tools/grep.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(findTool, { path: "src/tools/find.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(lsTool, { path: "src/tools/ls.ts", scope: "core" }),
+	});
+	if (includeNetworkTools) {
+		registry.register({
+			...builtin(
+				lazyTool(webFetchToolSurface, async () => (await import("./web-fetch.js")).webFetchTool),
+				{ path: "src/tools/web-fetch.ts", scope: "core" },
+			),
+		});
+	}
+	registry.register({
+		...builtin(gitTool, { path: "src/tools/safe-exec.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(
+			lazyTool(verifyToolSurface, async () => (await import("./verify/index.js")).verifyTool),
+			{ path: "src/tools/verify/index.ts", scope: "core" },
+		),
+	});
+	registry.register({
+		...builtin(
+			lazyTool(codeNavToolSurface, async () => (await import("./codewiki/code-nav.js")).codeNavTool),
+			{ path: "src/tools/codewiki/code-nav.ts", scope: "core" },
+		),
+	});
+	const skillToolDeps = {
+		getCwd: () => deps.session?.current()?.cwd ?? process.cwd(),
+		...(deps.getSkillLoaderOptions ? { getSkillLoaderOptions: deps.getSkillLoaderOptions } : {}),
+		...(deps.skillMarketplace !== undefined ? { skillMarketplace: deps.skillMarketplace } : {}),
+	};
+	if (deps.askUser) {
+		registry.register({
+			...builtin(createAskUserTool({ askUser: deps.askUser }), {
+				path: "src/tools/ask-user.ts",
+				scope: "core",
+			}),
+		});
+	}
+	registry.register({
+		...builtin(credentialPresentTool, { path: "src/tools/credential-present.ts", scope: "core" }),
+	});
+	const session = deps.session;
+	registry.register({
+		...builtin(
+			lazyTool(contextToolSurface, async () => {
+				const { createContextTool } = await import("./context/index.js");
+				if (!session) return createContextTool(skillToolDeps);
+				const { probeWorkspace } = await import("../domains/session/workspace/index.js");
+				return createContextTool({
+					...skillToolDeps,
+					workspace: {
+						hasSession: () => session.current() !== null,
+						getSnapshot: () => session.current()?.workspace ?? null,
+						probeWorkspace: () => probeWorkspace(session.current()?.cwd ?? process.cwd()),
+						saveSnapshot: (snap) => {
+							const meta = session.current();
+							if (meta) meta.workspace = snap;
+						},
+					},
+				});
+			}),
+			{ path: "src/tools/context/index.ts", scope: "core" },
+		),
+	});
+	registry.register({
+		...builtin(createArtifactTool({ getCwd: skillToolDeps.getCwd }), { path: "src/tools/artifact.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(createLedgerTool(deps.agentLedger ? { agentLedger: deps.agentLedger } : {}), {
+			path: "src/tools/ledger.ts",
+			scope: "core",
+		}),
+	});
+	registry.register({
+		...builtin(
+			createTasksTool({
+				board: deps.taskBoard ?? createTaskBoardStore(),
+				...(deps.userTasks ? { userTasks: deps.userTasks } : {}),
+				getSessionId: () => deps.session?.current()?.id ?? null,
+			}),
+			{
+				path: "src/tools/tasks.ts",
+				scope: "core",
+			},
+		),
+	});
+	return {
+		includeNetworkTools,
+		includeSessionTools: Boolean(session),
+		includeInteractiveTools: Boolean(deps.askUser),
+	};
+}
+
+export function assertRegisteredBuiltinTools(
+	registry: ToolRegistry,
+	registration: CoreToolRegistration,
+	includeDispatchTools: boolean,
+): void {
+	assertBuiltinToolPolicy(registry.listAll(), { ...registration, includeDispatchTools });
+}

package/src/tools/credential-present.ts

@@ -2,9 +2,9 @@ import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
+import { StringEnum } from "../engine/ai.js";
 import { resolveReadPath } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
-import { stringEnum } from "./string-enum.js";
 
 type CredentialPresenceSource = "auto" | "environment" | "file";
 type CredentialPresenceResultSource = "environment" | "file" | "both" | "none";
@@ -91,10 +91,10 @@ export const credentialPresentTool: ToolSpec = {
 	parameters: Type.Object({
 		name: Type.String({ description: "Credential key name, e.g. OPENAI_API_KEY." }),
 		source: Type.Optional(
-			stringEnum(
-				["auto", "environment", "env", "file"],
-				"auto checks the environment and the file when file is supplied; environment/env checks only the process environment; file checks only the file.",
-			),
+			StringEnum(["auto", "environment", "env", "file"], {
+				description:
+					"auto checks the environment and the file when file is supplied; environment/env checks only the process environment; file checks only the file.",
+			}),
 		),
 		file: Type.Optional(Type.String({ description: "Env-style file to check for NAME=, e.g. .env." })),
 	}),