@pugi/cli 0.1.0-alpha.10

package/dist/core/engine/tool-bridge.js

@@ -0,0 +1,313 @@
+import { editTool, globTool, grepTool, readTool, writeTool, } from '../../tools/file-tools.js';
+import { bashToolSync } from '../../tools/bash.js';
+/**
+ * Tool-bridge: turns the abstract tool registry into:
+ *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
+ *   2. A single executor callback that dispatches each tool_call to the
+ *      concrete `file-tools.ts` handler under workspace permissions.
+ *
+ * The bridge enforces two CLI-side invariants that the runtime cannot:
+ *   - Plan-mode refusal. When `kind === 'plan'`, the executor refuses
+ *     write/edit/bash by throwing `PLAN_MODE_REFUSED:<tool>` (sentinel
+ *     recognised by `runEngineLoop` to terminate with status
+ *     `tool_refused`). The schema also omits the mutating tools so the
+ *     model is unlikely to attempt them in the first place.
+ *   - Argument validation. Each call's `arguments` string is JSON-parsed
+ *     and shape-checked here; bad JSON or missing fields are surfaced
+ *     to the model as a tool error string so it can correct itself.
+ *
+ * The bridge does NOT touch session.ts directly — `file-tools.ts`
+ * already records every call. The engine adapter wires a hook layer on
+ * top that surfaces tool events into the engine's status stream.
+ */
+/**
+ * Read-only subset surfaced to plan-mode. Mutating tools (write, edit,
+ * bash) are intentionally absent so the model rarely tries them.
+ */
+const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+/**
+ * Tools we actually wire today. The registry has more entries
+ * (task_*, skill, question) — those route through the runtime layer, not
+ * the local filesystem, so they ship in a follow-up PR. M1 cornerstone is
+ * the six core tools.
+ */
+const WIRED_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'glob', 'bash']);
+export function buildToolsSchema(kind) {
+    const planMode = kind === 'plan';
+    const toolDefs = [
+        {
+            name: 'read',
+            description: 'Read the contents of a workspace file. Required before edit on a file. Returns the full UTF-8 text. Workspace-scoped: paths must be relative to the workspace root.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string', description: 'Workspace-relative file path.' },
+                },
+            },
+        },
+        {
+            name: 'grep',
+            description: 'Substring-match every workspace file. Returns up to 200 matches with {path, line, text}. Use this to locate code by symbol/keyword.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['query'],
+                properties: {
+                    query: { type: 'string', description: 'Substring to search for.' },
+                },
+            },
+        },
+        {
+            name: 'glob',
+            description: 'List files matching a glob pattern (workspace-scoped, node_modules / dist / .git / .pugi excluded). Up to 500 paths.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['pattern'],
+                properties: {
+                    pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts".' },
+                },
+            },
+        },
+    ];
+    if (!planMode) {
+        toolDefs.push({
+            name: 'write',
+            description: 'Create or overwrite a workspace file. Use for new files only — prefer edit for existing files. Workspace-scoped.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string', description: 'Workspace-relative file path.' },
+                    content: { type: 'string', description: 'Full new file contents (UTF-8).' },
+                },
+            },
+        }, {
+            name: 'edit',
+            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. Fails if the file changed since you read it or if oldString is missing/duplicate.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'oldString', 'newString'],
+                properties: {
+                    path: { type: 'string' },
+                    oldString: { type: 'string' },
+                    newString: { type: 'string' },
+                },
+            },
+        }, {
+            name: 'bash',
+            description: 'Run a shell command inside the workspace root via /bin/sh -c. Inherits a sanitized env (PUGI_API_KEY/PUGI_LOGIN_TOKEN stripped). 30s timeout. Output capped at 64KB. Returns {exitCode, stdout, stderr, truncated}.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: { type: 'string', description: 'Single shell command to execute.' },
+                },
+            },
+        });
+    }
+    return toolDefs;
+}
+function parseArgs(raw) {
+    if (!raw || raw.trim() === '')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('tool arguments must be a JSON object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`invalid JSON in tool arguments: ${error.message}`);
+    }
+}
+function requireString(obj, key) {
+    const v = obj[key];
+    if (typeof v !== 'string') {
+        throw new Error(`tool argument "${key}" must be a string`);
+    }
+    return v;
+}
+export function buildExecutor(input) {
+    const { kind, ctx, hooks, sessionId } = input;
+    const planMode = kind === 'plan';
+    return async ({ name, arguments: argsRaw }) => {
+        if (!WIRED_TOOLS.has(name)) {
+            throw new Error(`unknown tool: ${name}`);
+        }
+        if (planMode && !READ_ONLY_TOOLS.has(name)) {
+            // Sentinel recognised by `runEngineLoop` — terminates the loop
+            // with status `tool_refused`. The CLI surfaces this as a blocked
+            // outcome, not a failure, because plan mode is doing its job.
+            throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+        }
+        // Fire PreToolUse hooks. The match grammar takes the tool name and
+        // (when extractable) the target path. Each new tool dispatch starts a
+        // fresh dedup batch so a hook fires once per dispatch, not once per
+        // session.
+        if (hooks && sessionId) {
+            hooks.resetBatch();
+            const path = extractToolPath(name, argsRaw);
+            const preCtx = {
+                sessionId,
+                event: 'PreToolUse',
+                tool: name,
+                path,
+                payload: { tool: name, arguments: argsRaw },
+            };
+            // List the matching hooks BEFORE firing so we can correlate
+            // hook[i] with result[i] when checking onFailure: 'block'. The
+            // ordering of listMatching and fire is stable: fire iterates the
+            // same listMatching output internally.
+            const matchingPreHooks = hooks.listMatching(preCtx);
+            const preResults = await hooks.fire(preCtx);
+            for (let i = 0; i < matchingPreHooks.length; i += 1) {
+                const hook = matchingPreHooks[i];
+                const result = preResults[i];
+                if (hook && result && hook.onFailure === 'block' && !result.ok) {
+                    throw new Error(`HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
+                }
+            }
+        }
+        const args = parseArgs(argsRaw);
+        const dispatch = async () => {
+            return dispatchTool(name, args, ctx);
+        };
+        try {
+            const result = await dispatch();
+            if (hooks && sessionId) {
+                const path = extractToolPath(name, argsRaw);
+                await hooks.fire({
+                    sessionId,
+                    event: 'PostToolUse',
+                    tool: name,
+                    path,
+                    payload: { tool: name, arguments: argsRaw, ok: true, result: result.slice(0, 1024) },
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            if (hooks && sessionId) {
+                const path = extractToolPath(name, argsRaw);
+                await hooks.fire({
+                    sessionId,
+                    event: 'PostToolUseFailure',
+                    tool: name,
+                    path,
+                    payload: {
+                        tool: name,
+                        arguments: argsRaw,
+                        ok: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Best-effort extraction of the file path a tool targets. Returns
+ * undefined when the tool does not take a path or the path cannot be
+ * parsed cleanly — match rules with a `pathGlob` will then skip this
+ * dispatch, which is the safe default.
+ */
+function extractToolPath(name, argsRaw) {
+    if (name !== 'read' && name !== 'write' && name !== 'edit')
+        return undefined;
+    try {
+        const parsed = JSON.parse(argsRaw);
+        const path = parsed.path;
+        return typeof path === 'string' ? path : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function dispatchTool(name, args, ctx) {
+    switch (name) {
+        case 'read': {
+            const { path } = { path: requireString(args, 'path') };
+            const content = readTool(ctx, path);
+            // Cap the content surfaced back to the model so a 10MB file
+            // does not blow the context window. The model sees the head
+            // and a truncation marker; if it needs more it can grep.
+            const CAP = 32 * 1024;
+            if (content.length > CAP) {
+                return `${content.slice(0, CAP)}\n(...truncated at ${CAP} bytes; use grep or glob to narrow the read)`;
+            }
+            return content;
+        }
+        case 'write': {
+            const wargs = {
+                path: requireString(args, 'path'),
+                content: requireString(args, 'content'),
+            };
+            writeTool(ctx, wargs.path, wargs.content);
+            return `wrote ${wargs.path} (${wargs.content.length} bytes)`;
+        }
+        case 'edit': {
+            const eargs = {
+                path: requireString(args, 'path'),
+                oldString: requireString(args, 'oldString'),
+                newString: requireString(args, 'newString'),
+            };
+            editTool(ctx, eargs.path, eargs.oldString, eargs.newString);
+            return `edited ${eargs.path}`;
+        }
+        case 'grep': {
+            const gargs = { query: requireString(args, 'query') };
+            const matches = grepTool(ctx, gargs.query);
+            if (matches.length === 0)
+                return `no matches for ${gargs.query}`;
+            const head = matches.slice(0, 50);
+            const rendered = head.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n');
+            const more = matches.length > head.length ? `\n(... ${matches.length - head.length} more)` : '';
+            return `${matches.length} match(es):\n${rendered}${more}`;
+        }
+        case 'glob': {
+            const gargs = { pattern: requireString(args, 'pattern') };
+            const results = globTool(ctx, gargs.pattern);
+            if (results.length === 0)
+                return `no paths match ${gargs.pattern}`;
+            return `${results.length} path(s):\n${results.slice(0, 100).join('\n')}${results.length > 100 ? `\n(... ${results.length - 100} more)` : ''}`;
+        }
+        case 'bash': {
+            const bargs = { command: requireString(args, 'command') };
+            // The class-aware bash tool (sprint α5.2) replaces the legacy
+            // file-tools entry point. We use the sync variant here because
+            // dispatchTool's signature is sync; the async tool is reserved
+            // for the REPL path (sprint α5.7) where promises are first class.
+            const result = bashToolSync({ cmd: bargs.command }, {
+                root: ctx.root,
+                settings: ctx.settings,
+                session: ctx.session,
+                source: 'agent',
+            });
+            const parts = [
+                `exit=${result.exitCode}`,
+                result.stdout ? `stdout:\n${result.stdout}` : '',
+                result.stderr ? `stderr:\n${result.stderr}` : '',
+            ];
+            if (result.artifactRef)
+                parts.push(`artifactRef=${result.artifactRef}`);
+            if (result.truncated)
+                parts.push('truncated=true');
+            if (result.timedOut)
+                parts.push('timedOut=true');
+            const body = parts.filter(Boolean).join('\n');
+            return body || '(no output)';
+        }
+        default:
+            // Exhaustive; unreachable because of the WIRED_TOOLS guard above.
+            throw new Error(`unhandled tool: ${name}`);
+    }
+}
+//# sourceMappingURL=tool-bridge.js.map

package/dist/core/file-cache.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+export class FileReadCache {
+    records = new Map();
+    set(record) {
+        this.records.set(record.resolvedPath, record);
+    }
+    get(root, path) {
+        return this.records.get(resolve(root, path));
+    }
+}
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function createReadRecord(root, path, content, source) {
+    const resolvedPath = resolve(root, path);
+    const stat = statSync(resolvedPath);
+    return {
+        path,
+        resolvedPath,
+        sha256: hashContent(content),
+        sizeBytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+        readAt: new Date().toISOString(),
+        source,
+    };
+}
+//# sourceMappingURL=file-cache.js.map