@cleocode/core 2026.6.12 → 2026.6.14

package/dist/tools/agent-registry.js

@@ -0,0 +1,292 @@
+/**
+ * Agent-facing tool registry (T1739 · epic T11456 · SG-TOOLS).
+ *
+ * EXTENDS the CORE-SDK tool layer (`core/src/tools/*`) with an AGENT-FACING
+ * registry alongside the existing skill-tools engine — the cleocode analogue of
+ * Hermes' `tools/registry.py`. Where {@link ./fs.js}/{@link ./shell.js} are the
+ * raw side-effecting primitives and {@link ./guard.js} is the deny-first
+ * chokepoint, THIS module is what an agent loop (the Pi adapter / ModelRunner)
+ * consults to learn "which tools exist, what is each tool's OpenAI-format schema,
+ * which toolset does it belong to, is it available right now, and how do I run
+ * it". It owns NO side-effects of its own: every registered tool's executable is
+ * bound over an injected {@link GuardedToolSurface}, so all fs/shell work still
+ * funnels through {@link createToolGuard} — there is no raw-primitive bypass.
+ *
+ * ## Responsibilities (the 8 acceptance criteria)
+ *
+ * - **AC1** — the {@link AgentToolRegistry} class lives here.
+ * - **AC2** — {@link AgentToolRegistry.discover} performs a BOUNDED directory
+ *   scan for agent-tool modules (a lightweight source scan for the registration
+ *   marker, then a dynamic import of only the matching modules) — NOT a heavy
+ *   whole-tree AST parse, and NEVER at module import.
+ * - **AC3** — {@link AgentToolRegistry.toOpenAITools} emits the OpenAI-format
+ *   {@link TransportTool}[] the Pi adapter / transport wire layer consume, via
+ *   the single shared {@link zodSchemaToOpenAITool} generator (DRY).
+ * - **AC4** — every tool declares a {@link Toolset} group (`terminal | file |
+ *   web | agent | media`); {@link AgentToolRegistry.byToolset} buckets them.
+ * - **AC5** — every tool declares an {@link AvailabilityCheck} predicate, so a
+ *   tool can be hidden when its preconditions (e.g. network egress, a binary on
+ *   PATH) are not met for the current {@link ToolAvailabilityContext}.
+ * - **AC6** — the registry is effectively IMMUTABLE after {@link
+ *   AgentToolRegistry.init}: registration is rejected once initialised and
+ *   `init()` is single-flight (concurrent callers await one shared promise), so
+ *   there is no shared-mutable-state race.
+ * - **AC7** — auto-discovery is exposed as an EXPLICIT {@link
+ *   AgentToolRegistry.init} called at startup. Module import registers nothing
+ *   and runs no heavy work (lazy {@link getLogger}; no scan at import).
+ *
+ * @task T1739
+ * @epic T11456
+ * @see ./guard.js — the deny-first chokepoint every tool executable routes through
+ * @see ./schema-gen.js — the single OpenAI-format schema generator (AC3)
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getLogger } from '../logger.js';
+import { registerBuiltinAgentTools } from './builtin-agent-tools.js';
+import { zodSchemaToOpenAITool } from './schema-gen.js';
+// Lazy subsystem logger — `getLogger` is safe pre-init and triggers NO heavy
+// work at module import (AC7).
+const log = getLogger('agent-tool-registry');
+/**
+ * The marker an agent-tool module must export for the bounded directory scan
+ * (AC2) to dynamically import it: a function `registerAgentTools(registry)` that
+ * self-registers the module's tools. The scan greps for this identifier in the
+ * source before importing, so non-tool modules are never loaded.
+ */
+export const AGENT_TOOL_REGISTER_FN = 'registerAgentTools';
+/** An {@link AvailabilityCheck} that always reports available. */
+export const ALWAYS_AVAILABLE = () => true;
+/** Convert a registry entry into its taxonomy descriptor (lossless subset). */
+function toPrimitiveDescriptor(t) {
+    return {
+        name: t.name,
+        class: t.class,
+        responsibility: t.description,
+        stateless: t.stateless,
+    };
+}
+/**
+ * The agent-facing tool registry (AC1).
+ *
+ * Lifecycle: construct → {@link register} built-ins/custom tools (or let
+ * {@link init} do it) → {@link init} (idempotent, single-flight) → read-only
+ * queries ({@link list}, {@link byToolset}, {@link available},
+ * {@link toOpenAITools}, {@link getExecutable}). After `init()` the tool set is
+ * frozen; a late {@link register} throws (AC6).
+ *
+ * @example
+ * ```ts
+ * const registry = new AgentToolRegistry();
+ * await registry.init(); // registers built-in atomic primitives (AC7)
+ * const openai = registry.toOpenAITools();          // AC3
+ * const fileTools = registry.byToolset('file');     // AC4
+ * const usable = registry.available({ networkEgressAllowed: false }); // AC5
+ * ```
+ */
+export class AgentToolRegistry {
+    /** name → descriptor. Mutated only before {@link #initialised} flips true. */
+    #tools = new Map();
+    /** Frozen-after-init guard (AC6). */
+    #initialised = false;
+    /** Single-flight init promise so concurrent {@link init} calls coalesce (AC6). */
+    #initPromise = null;
+    /** Whether {@link init} has completed (the tool set is frozen). */
+    get initialised() {
+        return this.#initialised;
+    }
+    /** Number of registered tools. */
+    get size() {
+        return this.#tools.size;
+    }
+    /**
+     * Register a single agent tool. Rejects duplicate names and any registration
+     * after {@link init} has completed (AC6 — the registry is immutable post-init).
+     *
+     * @param tool - The tool to register.
+     * @throws Error when the registry is already initialised, or the name is taken.
+     */
+    register(tool) {
+        if (this.#initialised) {
+            throw new Error(`agent-tool-registry: cannot register "${tool.name}" after init() — the registry is frozen`);
+        }
+        if (this.#tools.has(tool.name)) {
+            throw new Error(`agent-tool-registry: duplicate tool name "${tool.name}"`);
+        }
+        this.#tools.set(tool.name, tool);
+    }
+    /**
+     * Initialise the registry (AC7): register the built-in atomic primitives
+     * (unless `skipBuiltins`), run bounded module discovery over `scanDirs`
+     * (AC2), then FREEZE the tool set. Idempotent and single-flight — concurrent
+     * callers await one shared promise and a second call after completion is a
+     * no-op (AC6).
+     *
+     * @param options - Discovery options ({@link AgentToolDiscoveryOptions}).
+     */
+    async init(options = {}) {
+        if (this.#initialised)
+            return;
+        if (this.#initPromise)
+            return this.#initPromise;
+        this.#initPromise = this.#runInit(options);
+        try {
+            await this.#initPromise;
+        }
+        finally {
+            this.#initPromise = null;
+        }
+    }
+    /** Inner init body — guarded by the single-flight latch in {@link init}. */
+    async #runInit(options) {
+        if (options.skipBuiltins !== true) {
+            registerBuiltinAgentTools(this);
+        }
+        if (options.scanDirs && options.scanDirs.length > 0) {
+            await this.discover(options.scanDirs);
+        }
+        this.#initialised = true;
+        log.debug({ count: this.#tools.size }, 'agent-tool-registry initialised');
+    }
+    /**
+     * Bounded discovery (AC2): for each directory, read its entries (NON-recursive,
+     * bounded), grep each `*.agent-tool.{ts,js}` candidate's SOURCE for the
+     * {@link AGENT_TOOL_REGISTER_FN} export marker, and dynamically import ONLY the
+     * matching modules — then invoke each module's `registerAgentTools(this)`.
+     *
+     * This is a lightweight source scan rather than a whole-tree AST parse: it does
+     * the minimum work to locate self-registering tool modules without loading the
+     * whole package. It is invoked from {@link init} (explicit startup) and never at
+     * module import (AC7). May also be called directly before `init()` for tests.
+     *
+     * @param scanDirs - Absolute directories to scan.
+     * @throws Error when called after the registry is frozen (AC6).
+     */
+    async discover(scanDirs) {
+        if (this.#initialised) {
+            throw new Error('agent-tool-registry: cannot discover() after init() — the registry is frozen');
+        }
+        for (const dir of scanDirs) {
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch (err) {
+                log.warn({ dir, err }, 'agent-tool-registry: scan dir unreadable — skipped');
+                continue;
+            }
+            for (const entry of entries) {
+                if (!/\.agent-tool\.(ts|js)$/.test(entry))
+                    continue;
+                const full = join(dir, entry);
+                // Source-marker scan: only import a module that actually exports the
+                // registration fn. Cheaper + safer than importing every file.
+                let src;
+                try {
+                    src = await readFile(full, 'utf8');
+                }
+                catch (err) {
+                    log.warn({ full, err }, 'agent-tool-registry: candidate unreadable — skipped');
+                    continue;
+                }
+                if (!src.includes(AGENT_TOOL_REGISTER_FN))
+                    continue;
+                const mod = await import(full);
+                const register = mod[AGENT_TOOL_REGISTER_FN];
+                if (typeof register !== 'function') {
+                    log.warn({ full }, 'agent-tool-registry: module has no callable registerAgentTools — skipped');
+                    continue;
+                }
+                register(this);
+            }
+        }
+    }
+    /**
+     * Look up a registered tool by name.
+     *
+     * @param name - The tool name.
+     * @returns The descriptor, or `undefined` when unknown.
+     */
+    get(name) {
+        return this.#tools.get(name);
+    }
+    /**
+     * All registered tools in deterministic (insertion) order. The returned array
+     * is a fresh copy — mutating it never affects the registry (AC6).
+     */
+    list() {
+        return [...this.#tools.values()];
+    }
+    byToolset(toolset) {
+        if (toolset !== undefined) {
+            return this.list().filter((t) => t.toolset === toolset);
+        }
+        const grouped = {
+            terminal: [],
+            file: [],
+            web: [],
+            agent: [],
+            media: [],
+        };
+        for (const t of this.#tools.values()) {
+            grouped[t.toolset].push(t);
+        }
+        return grouped;
+    }
+    /**
+     * The subset of tools available for the given context (AC5). A tool without an
+     * explicit {@link AgentToolDescriptor.available} predicate is treated as
+     * {@link ALWAYS_AVAILABLE}.
+     *
+     * @param ctx - The availability context.
+     * @returns Tools whose predicate returns `true`, in registration order.
+     */
+    available(ctx = {}) {
+        return this.list().filter((t) => (t.available ?? ALWAYS_AVAILABLE)(ctx));
+    }
+    /**
+     * Emit the OpenAI-format {@link TransportTool}[] for the model (AC3) — the
+     * shape the Pi adapter / ModelRunner transport layer consume. Generated via the
+     * single shared {@link zodSchemaToOpenAITool} generator so the registry and the
+     * Pi streamFn never drift.
+     *
+     * @param ctx - When provided, only AVAILABLE tools (AC5) are emitted; otherwise
+     *   every registered tool is emitted.
+     * @returns OpenAI-format tool definitions in deterministic order.
+     */
+    toOpenAITools(ctx) {
+        const tools = ctx ? this.available(ctx) : this.list();
+        return tools.map((t) => zodSchemaToOpenAITool({ name: t.name, description: t.description, parameters: t.parameters }));
+    }
+    /**
+     * The bound executable for a tool (the name→handler dispatch map, AC1).
+     *
+     * @param name - The tool name.
+     * @returns The {@link AgentToolExecutable}, or `undefined` when unknown.
+     */
+    getExecutable(name) {
+        return this.#tools.get(name)?.execute;
+    }
+    /**
+     * The taxonomy descriptors ({@link ToolPrimitiveDescriptor}) for every
+     * registered tool — the lossless subset compatible with the canonical
+     * `ATOMIC_TOOL_PRIMITIVES` registry, for callers that want the class taxonomy
+     * without the agent-facing schema/executable.
+     */
+    primitiveDescriptors() {
+        return this.list().map(toPrimitiveDescriptor);
+    }
+}
+/**
+ * Build and initialise an {@link AgentToolRegistry} in one call (AC7 convenience).
+ * Equivalent to `new AgentToolRegistry()` + `await registry.init(options)`.
+ *
+ * @param options - Discovery options.
+ * @returns A frozen, ready-to-query registry.
+ */
+export async function createAgentToolRegistry(options = {}) {
+    const registry = new AgentToolRegistry();
+    await registry.init(options);
+    return registry;
+}
+//# sourceMappingURL=agent-registry.js.map

package/dist/tools/agent-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.js","sourceRoot":"","sources":["../../src/tools/agent-registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/agent-tool-families.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent-facing tool FAMILIES — terminal, file, search, git (T1741 · epic T11456).
+ *
+ * The six richer tool families layered over the atomic primitives and registered
+ * into the {@link ./agent-registry.js | AgentToolRegistry}, on top of the thin
+ * built-ins in {@link ./builtin-agent-tools.js}:
+ *
+ *   - **AC1** `run_shell` — terminal execution with PTY + non-PTY (spawn) modes
+ *     (PTY via the OPTIONAL, lazily-loaded `node-pty`; transparent spawn fallback).
+ *   - **AC2** `read_file_paged` — file read with `offset`/`limit` pagination.
+ *   - **AC3** `write_file_atomic` — atomic (tmp-then-rename) write.
+ *   - **AC4** `apply_patch` — fuzzy (whitespace-tolerant) text replacement.
+ *   - **AC5** `search_files` — ripgrep-backed search with graceful degradation
+ *     to `grep` when `rg` is absent.
+ *   - **AC6** `git_status` / `git_diff` / `git_log` / `git_commit` — workspace-
+ *     confined git operations.
+ *
+ * Every family performs ALL side effects through the injected
+ * {@link GuardedToolSurface} (deny-first chokepoint) — there is NO raw `fs` /
+ * `child_process` use here. The pure helpers (patch matching, search-output
+ * parsing, git parsing) are exported for direct unit testing with mocked
+ * backends (AC8). Import-time side-effect-free.
+ *
+ * @epic T11456
+ * @task T1741
+ * @see ./guard.js — the deny-first chokepoint every executable routes through
+ */
+import type { ApplyPatchResult, GitLogEntry, GitStatusEntry, ReadFilePagedResult, SearchFilesMatch } from '@cleocode/contracts/tools/agent-tools';
+import type { AgentToolRegistry } from './agent-registry.js';
+/**
+ * Slice a file's text into a paginated window. Pure helper — no I/O — so it is
+ * unit-testable in isolation (AC8).
+ *
+ * @param content - The full file text.
+ * @param offset - 0-based starting line (clamped to `[0, totalLines]`).
+ * @param limit - Max lines to return; `undefined` → to end of file.
+ * @returns The paginated {@link ReadFilePagedResult} body for `path`.
+ */
+export declare function paginateLines(content: string, path: string, offset?: number, limit?: number): ReadFilePagedResult;
+/** Outcome of {@link applyFuzzyPatch} — the new content + how it matched. */
+export interface FuzzyPatchOutcome {
+    /** The patched content (unchanged when `matchKind === 'none'`). */
+    readonly content: string;
+    /** How `oldText` was located. */
+    readonly matchKind: ApplyPatchResult['matchKind'];
+    /** 0-based line where the replacement began (when applied). */
+    readonly startLine?: number;
+}
+/**
+ * Apply a text replacement, falling back to whitespace-tolerant fuzzy matching
+ * when an exact substring match is not found. Pure function of its inputs — no
+ * I/O — so it is unit-testable with no filesystem (AC8).
+ *
+ * Strategy:
+ *  1. **Exact** — a verbatim `indexOf(oldText)` substring replacement (first hit).
+ *  2. **Fuzzy** (when enabled) — compare `oldText` line-trimmed against every
+ *     same-length window of the file's line-trimmed lines; the first window that
+ *     matches is replaced (preserving the file's other lines).
+ *  3. **None** — no match; content returned unchanged.
+ *
+ * @param content - The current file content.
+ * @param oldText - The block to locate.
+ * @param newText - The replacement.
+ * @param fuzzy - Permit fuzzy matching (default `true`).
+ * @returns The {@link FuzzyPatchOutcome}.
+ */
+export declare function applyFuzzyPatch(content: string, oldText: string, newText: string, fuzzy?: boolean): FuzzyPatchOutcome;
+/**
+ * Parse ripgrep `--vimgrep`/`-n` style output (`path:line:col:text` or
+ * `path:line:text`) into structured matches. Pure helper (AC8).
+ *
+ * @param stdout - ripgrep stdout.
+ * @param maxResults - Cap on returned matches.
+ * @returns The parsed matches and whether the cap truncated them.
+ */
+export declare function parseRipgrepOutput(stdout: string, maxResults: number): {
+    matches: SearchFilesMatch[];
+    truncated: boolean;
+};
+/**
+ * Parse `git status --porcelain=v1` output into structured entries. Pure (AC8).
+ *
+ * @param stdout - porcelain-v1 stdout.
+ * @returns The parsed status entries.
+ */
+export declare function parseGitStatus(stdout: string): GitStatusEntry[];
+/**
+ * The `--pretty=format:` argument for {@link parseGitLog} — SHA, author name,
+ * ISO date, subject, unit-separated.
+ */
+export declare const GIT_LOG_FORMAT = "%H\u001F%an\u001F%aI\u001F%s";
+/**
+ * Parse `git log --pretty=format:<GIT_LOG_FORMAT>` output. Pure (AC8).
+ *
+ * @param stdout - The git-log stdout.
+ * @returns The parsed commit entries, newest-first.
+ */
+export declare function parseGitLog(stdout: string): GitLogEntry[];
+/**
+ * Register the agent-facing tool FAMILIES (terminal, file, search, git) into
+ * `registry`. Pure registration — no I/O, no scan; side effects happen later
+ * through the injected {@link GuardedToolSurface}.
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentToolFamilies(registry: AgentToolRegistry): void;
+//# sourceMappingURL=agent-tool-families.d.ts.map

package/dist/tools/agent-tool-families.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool-families.d.ts","sourceRoot":"","sources":["../../src/tools/agent-tool-families.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAG/C,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,qBAAqB,CAAC;AAYhF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,SAAI,EACV,KAAK,CAAC,EAAE,MAAM,GACb,mBAAmB,CAcrB;AAMD,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAClD,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAgBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,UAAO,GACX,iBAAiB,CA8BnB;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAkBrD;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAS/D;AAKD;;;GAGG;AACH,eAAO,MAAM,cAAc,iCAA2E,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAczD;AA2ED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAyQ3E"}