@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/tools/code-exec-tool.js

@@ -16,6 +16,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { BaseTool } from './base-tool.js';
 import { logger } from '../utils/logger.js';
+import { ToolCallScheduler } from './tool-call-scheduler.js';
 export const CODE_EXEC_RUNTIME_CONTEXT_KEY = 'codeExecRuntime';
 /** Attach a runtime without changing any other tool-execution context data. */
 export function attachCodeExecRuntime(context, runtime) {
@@ -58,6 +59,22 @@ export const CODE_EXEC_LIMITS = Object.freeze({
     scopeTtlMs: 2 * 60 * 60 * 1000,
 });
 const scopedStates = new Map();
+const scopeSchedulers = new Map();
+async function runScoped(scopeId, action, signal) {
+    let entry = scopeSchedulers.get(scopeId);
+    if (!entry) {
+        entry = { scheduler: new ToolCallScheduler(1), users: 0 };
+        scopeSchedulers.set(scopeId, entry);
+    }
+    entry.users++;
+    try {
+        return await entry.scheduler.schedule(false, action, signal);
+    }
+    finally {
+        if (--entry.users === 0)
+            scopeSchedulers.delete(scopeId);
+    }
+}
 /** Backward-compatible direct-use runtime. Production ToolHandler never uses it. */
 let legacySessionId = 'default';
 let legacyExecutor = null;
@@ -167,17 +184,19 @@ function truncate(value, limit) {
     return value.slice(0, Math.max(0, limit - marker.length)) + marker;
 }
 function jsonSafe(value) {
-    const seen = new WeakSet();
+    const ancestors = [];
     try {
-        const encoded = JSON.stringify(value, (_key, current) => {
+        const encoded = JSON.stringify(value, function (_key, current) {
             if (typeof current === 'bigint')
                 return current.toString();
             if (typeof current === 'function' || typeof current === 'symbol')
                 return undefined;
             if (current && typeof current === 'object') {
-                if (seen.has(current))
+                while (ancestors.length && ancestors[ancestors.length - 1] !== this)
+                    ancestors.pop();
+                if (ancestors.includes(current))
                     return '[Circular]';
-                seen.add(current);
+                ancestors.push(current);
             }
             return current;
         });
@@ -195,23 +214,35 @@ function jsonSafe(value) {
         return String(value);
     }
 }
-function serializeToolResult(result) {
+function serializeToolResult(result, format) {
+    if (format !== 'legacy') {
+        const payload = jsonSafe(result);
+        if (payload && typeof payload === 'object' && 'truncated' in payload && 'preview' in payload) {
+            return JSON.stringify({ success: result.success, truncated: true,
+                output: truncate(result.output ?? String(payload.preview), CODE_EXEC_LIMITS.maxToolResultChars - CODE_EXEC_LIMITS.maxErrorChars),
+                ...(result.error ? { error: truncate(result.error, CODE_EXEC_LIMITS.maxErrorChars) } : {}),
+            });
+        }
+        return JSON.stringify(payload);
+    }
     const payload = result.success
         ? (result.output ?? result.data ?? '')
         : { error: truncate(result.error ?? 'Tool execution failed', CODE_EXEC_LIMITS.maxErrorChars) };
     return JSON.stringify(jsonSafe(payload));
 }
-function sanitizeToolName(name) {
+export function sanitizeToolName(name) {
     const replaced = name.replace(/[^a-zA-Z0-9_$]/g, '_');
     if (!replaced)
         return '_tool';
     return /^[a-zA-Z_$]/.test(replaced) ? replaced : `_${replaced}`;
 }
-function buildToolBindings(toolNames) {
+export function buildToolBindings(toolNames) {
     const bindings = [];
     const seenTools = new Set();
     const seenBindings = new Set(['call']);
-    for (const toolName of toolNames) {
+    // Keep discovery reachable even when direct bindings hit their budget.
+    const ordered = toolNames.includes('tool_search') ? ['tool_search', ...toolNames] : toolNames;
+    for (const toolName of ordered) {
         if (bindings.length >= CODE_EXEC_LIMITS.maxAvailableTools)
             break;
         if (typeof toolName !== 'string' ||
@@ -222,9 +253,11 @@ function buildToolBindings(toolNames) {
             continue;
         }
         seenTools.add(toolName);
-        const exposedName = sanitizeToolName(toolName);
-        if (seenBindings.has(exposedName))
-            continue;
+        const baseName = sanitizeToolName(toolName);
+        let exposedName = baseName;
+        let suffix = 2;
+        while (seenBindings.has(exposedName))
+            exposedName = `${baseName}_${suffix++}`;
         seenBindings.add(exposedName);
         bindings.push({ exposedName, toolName });
     }
@@ -305,27 +338,31 @@ async function execute(message) {
   const outputLimit = ${CODE_EXEC_LIMITS.maxOutputChars};
   const storeEntries = JSON.stringify(message.storeEntries || []);
   const toolBindings = JSON.stringify(message.toolBindings || []);
-  const allTools = JSON.stringify((message.toolBindings || []).map((entry) => entry.toolName));
+  const allTools = JSON.stringify(message.toolMetadata || (message.toolBindings || []).map((entry) => ({ name: entry.toolName, description: '' })));
   const bootstrap =
     'const __cbOutput = []; let __cbOutputLength = 0; let __cbTruncated = false; let __cbYielded = false;' +
     'const __cbStore = new Map(' + storeEntries + ');' +
     'const __cbBindings = ' + toolBindings + ';' +
     'const __cbBridge = globalThis.__codeBuddyBridge; delete globalThis.__codeBuddyBridge;' +
+    'const __cbYield = globalThis.__codeBuddyYield; delete globalThis.__codeBuddyYield;' +
     'function __cbFormat(value) { if (typeof value === "string") return value; try { const json = JSON.stringify(value); return json === undefined ? String(value) : json; } catch { return String(value); } }' +
     'function __cbAppend(values, prefix = "") { if (__cbTruncated) return; const line = prefix + values.map(__cbFormat).join(" "); const separator = __cbOutput.length ? "\\n" : ""; const remaining = ' + outputLimit + ' - __cbOutputLength; if (remaining <= 0) { __cbTruncated = true; return; } const next = separator + line; if (next.length > remaining) { __cbOutput.push(next.slice(0, remaining)); __cbOutputLength += remaining; __cbTruncated = true; return; } __cbOutput.push(next); __cbOutputLength += next.length; }' +
     'function text(content) { __cbAppend([content]); }' +
     'function store(key, value) { if (typeof key !== "string" || key.length === 0 || key.length > 256) throw new Error("store key must be 1..256 characters"); const encoded = JSON.stringify(value); if (encoded === undefined) throw new Error("store values must be JSON-compatible"); const cloned = JSON.parse(encoded); const candidate = new Map(__cbStore); candidate.set(key, cloned); if (candidate.size > ${CODE_EXEC_LIMITS.maxStoreEntries}) throw new Error("store entry limit reached"); const total = JSON.stringify(Array.from(candidate.entries())).length; if (total > ${CODE_EXEC_LIMITS.maxStoreBytes}) throw new Error("store byte limit reached"); __cbStore.set(key, cloned); }' +
     'function load(key) { const value = __cbStore.get(key); return value === undefined ? undefined : JSON.parse(JSON.stringify(value)); }' +
-    'function yield_control() { __cbYielded = true; }' +
+    'let __cbEmittedLength = 0; async function yield_control() { __cbYielded = true; const output = __cbOutput.join(""); const delta = output.slice(__cbEmittedLength); __cbEmittedLength = output.length; await __cbYield(delta); }' +
     'const tools = Object.create(null);' +
     'for (const binding of __cbBindings) { tools[binding.exposedName] = async function(args = {}) { const encoded = JSON.stringify(args); if (encoded === undefined || args === null || typeof args !== "object" || Array.isArray(args)) throw new Error("tool arguments must be a JSON object"); return JSON.parse(await __cbBridge(binding.toolName, encoded)); }; }' +
-    'tools.call = async function(name, args = {}) { if (typeof name !== "string") throw new Error("tool name must be a string"); const binding = __cbBindings.find((entry) => entry.toolName === name); if (!binding) throw new Error("tool is not available: " + name); const encoded = JSON.stringify(args); if (encoded === undefined || args === null || typeof args !== "object" || Array.isArray(args)) throw new Error("tool arguments must be a JSON object"); return JSON.parse(await __cbBridge(binding.toolName, encoded)); };' +
+    'tools.call = async function(name, args = {}) { if (typeof name !== "string") throw new Error("tool name must be a string"); const encoded = JSON.stringify(args); if (encoded === undefined || args === null || typeof args !== "object" || Array.isArray(args)) throw new Error("tool arguments must be a JSON object"); return JSON.parse(await __cbBridge(name, encoded)); };' +
     'Object.freeze(tools); Object.freeze(__cbBindings);' +
-    'const ALL_TOOLS = Object.freeze(' + allTools + ');' +
+    'const ALL_TOOLS = Object.freeze(' + allTools + '.map(Object.freeze)); const ALL_TOOL_NAMES = Object.freeze(ALL_TOOLS.map(t => t.name));' +
     'const console = Object.freeze({ log: (...args) => __cbAppend(args), error: (...args) => __cbAppend(args, "[ERROR] "), warn: (...args) => __cbAppend(args, "[WARN] ") });';
 
   const sandbox = Object.create(null);
   sandbox.__codeBuddyBridge = bridgeCall;
+  const yieldOutput = (output) => send({ type: 'output', output });
+  Object.setPrototypeOf(yieldOutput, null);
+  sandbox.__codeBuddyYield = yieldOutput;
   const context = vm.createContext(sandbox, {
     name: 'codebuddy-code-exec',
     codeGeneration: { strings: false, wasm: false },
@@ -370,12 +407,60 @@ function childExecArgs() {
     args.push('-e', SANDBOX_RUNNER_SOURCE);
     return args;
 }
-function terminateChild(child) {
-    try {
-        if (child.connected)
-            child.disconnect();
+/** Upper bound on waiting for the sandbox process to report `close`. */
+export const CHILD_CLOSE_GRACE_MS = 2_000;
+/**
+ * Wait for the OBSERVED `close` of the sandbox process — the event that says
+ * the process ended and its stdio is released. `exit` alone is not enough:
+ * `exitCode` can be set while stdio is still open, and the sandbox runs with
+ * the caller's workspace as its working directory, so the caller must not be
+ * told the workspace is free before the process really let go of it.
+ *
+ * @returns true when `close` was observed (or there is no process to wait for),
+ *          false when the grace elapsed first. The caller decides what an
+ *          unterminated sandbox means; this function never claims success.
+ */
+export function waitForChildClose(child, graceMs = CHILD_CLOSE_GRACE_MS) {
+    // Spawn failed: no process exists, nothing holds the workspace, nothing to wait for.
+    if (child.pid === undefined && child.exitCode === null && child.signalCode === null) {
+        return Promise.resolve(true);
     }
-    catch { /* already disconnected */ }
+    return new Promise((resolve) => {
+        // Named handlers so every listener and the timer are removed on both paths.
+        const onClose = () => settle(true);
+        const onTimeout = () => settle(false);
+        // Deliberately referenced: a killed child can leave nothing else pending,
+        // and an unreferenced timer would let the host exit with this promise
+        // unsettled instead of finishing the run. The wait stays bounded by graceMs.
+        const timer = setTimeout(onTimeout, graceMs);
+        const settle = (closed) => {
+            clearTimeout(timer);
+            child.removeListener('close', onClose);
+            resolve(closed);
+        };
+        child.on('close', onClose);
+    });
+}
+/**
+ * A sandbox process that did not close within the grace is a cleanup failure:
+ * it may still hold the workspace. Never report success in that case, and keep
+ * the original diagnosis when the run had already failed.
+ */
+export function sandboxNotTerminatedResult(result, graceMs = CHILD_CLOSE_GRACE_MS) {
+    const notice = `Sandbox process did not terminate within ${graceMs}ms; its workspace may still be locked`;
+    return {
+        ...result,
+        success: false,
+        output: result.output ? `${result.output}\n${notice}` : notice,
+    };
+}
+function terminateChild(child) {
+    // No explicit disconnect(): measured on Node 24, closing the IPC channel by
+    // hand before the kill suppresses the process 'close' event entirely (only
+    // 'disconnect' and 'exit' arrive), and 'close' is the signal that the process
+    // released its stdio — and with it the working directory. The channel is
+    // closed by the kill anyway ('disconnect' still fires), and no message can be
+    // sent after this point: `settled` is already true.
     try {
         if (!child.killed)
             child.kill('SIGKILL');
@@ -384,11 +469,15 @@ function terminateChild(child) {
 }
 async function runInChild(code, timeoutMs, runtime, state) {
     const toolBindings = buildToolBindings(runtime.availableTools);
-    const allowedTools = new Set(toolBindings.map((binding) => binding.toolName));
+    // Canonical calls use the full scoped catalogue; only JS shortcuts are capped.
+    const allowedTools = new Set(runtime.availableTools.filter(name => typeof name === 'string' && name && !['exec', 'code_exec'].includes(name)));
     return await new Promise((resolve) => {
         let settled = false;
         let stderr = '';
-        let toolQueue = Promise.resolve();
+        const scheduler = new ToolCallScheduler();
+        const controller = new AbortController();
+        let toolCallCount = 0;
+        let emittedChars = 0;
         const child = spawn(process.execPath, childExecArgs(), {
             cwd: runtime.cwd || process.cwd(),
             env: {
@@ -406,10 +495,16 @@ async function runInChild(code, timeoutMs, runtime, state) {
             if (settled)
                 return;
             settled = true;
+            controller.abort();
             clearTimeout(timer);
             runtime.abortSignal?.removeEventListener('abort', onAbort);
             terminateChild(child);
-            resolve(result);
+            // Report completion only once `close` was observed: callers treat the
+            // resolved promise as "the sandbox no longer touches my workspace". A
+            // process that never closes is reported as a failure, never as success.
+            void waitForChildClose(child).then((closed) => {
+                resolve(closed ? result : sandboxNotTerminatedResult(result));
+            });
         };
         const timer = setTimeout(() => {
             finish({
@@ -443,8 +538,22 @@ async function runInChild(code, timeoutMs, runtime, state) {
             const message = raw;
             if (!message || typeof message !== 'object' || settled)
                 return;
+            if (message.type === 'output') {
+                if (typeof message.output === 'string' && emittedChars + message.output.length <= CODE_EXEC_LIMITS.maxOutputChars) {
+                    emittedChars += message.output.length;
+                    try {
+                        runtime.onOutput?.(message.output);
+                    }
+                    catch { /* Observers do not control execution. */ }
+                }
+                return;
+            }
             if (message.type === 'tool_call') {
-                toolQueue = toolQueue.then(async () => {
+                if (++toolCallCount > CODE_EXEC_LIMITS.maxToolCalls || typeof message.argsJson !== 'string' || message.argsJson.length > CODE_EXEC_LIMITS.maxCodeChars) {
+                    finish({ success: false, output: 'code_exec tool-call or argument limit exceeded' });
+                    return;
+                }
+                void scheduler.schedule(runtime.parallelTools?.includes(message.toolName) === true, async () => {
                     if (settled || !child.connected)
                         return;
                     if (!allowedTools.has(message.toolName) ||
@@ -476,13 +585,13 @@ async function runInChild(code, timeoutMs, runtime, state) {
                         return;
                     }
                     try {
-                        const result = await runtime.executor(message.toolName, args);
+                        const result = await runtime.executor(message.toolName, args, controller.signal);
                         if (!settled && child.connected) {
                             child.send({
                                 type: 'tool_result',
                                 id: message.id,
                                 ok: true,
-                                valueJson: serializeToolResult(result),
+                                valueJson: serializeToolResult(result, runtime.resultFormat),
                             });
                         }
                     }
@@ -536,6 +645,10 @@ async function runInChild(code, timeoutMs, runtime, state) {
             code,
             timeoutMs,
             toolBindings,
+            toolMetadata: toolBindings.map(binding => ({
+                name: binding.toolName,
+                description: runtime.toolMetadata?.find(tool => tool.name === binding.toolName)?.description.slice(0, 2000) ?? '',
+            })),
             storeEntries: Array.from(state.values.entries()),
         }, (error) => {
             if (error)
@@ -563,6 +676,10 @@ export class CodeExecTool extends BaseTool {
                 type: 'number',
                 description: `Execution timeout in milliseconds (${CODE_EXEC_LIMITS.minTimeoutMs}..${CODE_EXEC_LIMITS.maxTimeoutMs}, default ${CODE_EXEC_LIMITS.defaultTimeoutMs}).`,
             },
+            typecheck: {
+                type: 'boolean',
+                description: 'Perform isolated TypeScript typechecking before execution. Rejects code on diagnostic errors with zero runtime side effects. Default false.',
+            },
         };
     }
     validate(input) {
@@ -587,6 +704,13 @@ export class CodeExecTool extends BaseTool {
                 errors: [`timeout_ms must be between ${CODE_EXEC_LIMITS.minTimeoutMs} and ${CODE_EXEC_LIMITS.maxTimeoutMs}`],
             };
         }
+        if (args.typecheck !== undefined &&
+            typeof args.typecheck !== 'boolean') {
+            return {
+                valid: false,
+                errors: ['typecheck must be a boolean'],
+            };
+        }
         return { valid: true };
     }
     async execute(input, context) {
@@ -595,9 +719,11 @@ export class CodeExecTool extends BaseTool {
             return this.error(validation.errors?.join('; ') ?? 'Invalid input');
         const code = input.code;
         const timeoutMs = normalizeTimeout(input.timeout_ms);
+        const typecheck = input.typecheck === true;
         const injectedRuntime = runtimeFromContext(context);
-        const runtime = injectedRuntime ?? {
+        const runtime = injectedRuntime ? { ...injectedRuntime } : {
             scopeId: legacyScopeId(),
+            resultFormat: 'legacy',
             sessionId: legacySessionId,
             cwd: context?.cwd ?? process.cwd(),
             availableTools: legacyAvailableTools,
@@ -606,28 +732,46 @@ export class CodeExecTool extends BaseTool {
                 error: `No ToolHandler executor is attached for ${toolName}`,
             })),
         };
-        const state = getScopedState(runtime);
-        const startedAt = Date.now();
-        const childResult = await runInChild(code, timeoutMs, runtime, state);
-        const elapsed = Date.now() - startedAt;
-        if (!childResult.success) {
-            logger.debug('code_exec failed', {
-                scopeId: runtime.scopeId,
-                timedOut: childResult.timedOut === true,
-                elapsed,
+        runtime.abortSignal ??= context?.abortSignal;
+        let codeToRun = code;
+        if (typecheck) {
+            const { runCodeExecPreflight } = await import('./code-exec-preflight.js');
+            const preflightResult = await runCodeExecPreflight(code, runtime, context, {
+                signal: runtime.abortSignal,
             });
-            return this.error(truncate(childResult.output, CODE_EXEC_LIMITS.maxErrorChars));
-        }
-        // Commit state transactionally only after a successful script.
-        if (childResult.storeEntries) {
-            state.values = new Map(childResult.storeEntries);
-            state.lastAccess = Date.now();
+            if (!preflightResult.success) {
+                return this.error(preflightResult.error || 'TypeScript preflight validation failed');
+            }
+            if (preflightResult.transpiledCode) {
+                codeToRun = preflightResult.transpiledCode;
+            }
         }
-        const status = childResult.yielded
-            ? `Script yielded control after ${elapsed}ms`
-            : `Script completed in ${elapsed}ms`;
-        const output = childResult.output ? `${status}\n\n${childResult.output}` : status;
-        return this.success(truncate(output, CODE_EXEC_LIMITS.maxOutputChars));
+        return runScoped(runtime.scopeId, async () => {
+            if (runtime.abortSignal?.aborted)
+                return this.error('Script cancelled');
+            const state = getScopedState(runtime);
+            const startedAt = Date.now();
+            const childResult = await runInChild(codeToRun, timeoutMs, runtime, state);
+            const elapsed = Date.now() - startedAt;
+            if (!childResult.success) {
+                logger.debug('code_exec failed', {
+                    scopeId: runtime.scopeId,
+                    timedOut: childResult.timedOut === true,
+                    elapsed,
+                });
+                return this.error(truncate(childResult.output, CODE_EXEC_LIMITS.maxErrorChars));
+            }
+            // Commit state transactionally only after a successful script.
+            if (childResult.storeEntries) {
+                state.values = new Map(childResult.storeEntries);
+                state.lastAccess = Date.now();
+            }
+            const status = childResult.yielded
+                ? `Script yielded control after ${elapsed}ms`
+                : `Script completed in ${elapsed}ms`;
+            const output = childResult.output ? `${status}\n\n${childResult.output}` : status;
+            return this.success(truncate(output, CODE_EXEC_LIMITS.maxOutputChars));
+        }, runtime.abortSignal).catch(error => this.error(error instanceof Error ? error.message : String(error)));
     }
 }
 /** Factory used by all FormalToolRegistry assembly paths. */

package/dist/tools/comment-watcher.js

@@ -1,9 +1,25 @@
 import { UnifiedVfsRouter } from '../services/vfs/unified-vfs-router.js';
 import * as path from "path";
-import { exec } from "child_process";
-import { promisify } from "util";
+import { execFile } from "child_process";
 import { EventEmitter } from "events";
-const execAsync = promisify(exec);
+const RIPGREP_TIMEOUT_MS = 30_000;
+/**
+ * Run ripgrep without a shell. Resolves with stdout; exit status 1 means
+ * "no match" and resolves empty. Missing binary, timeout or real errors reject
+ * so the caller can fall back to the manual scan.
+ */
+function runRipgrep(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = execFile("rg", args, { cwd, maxBuffer: 10 * 1024 * 1024, timeout: RIPGREP_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
+            if (!error)
+                return resolve(stdout);
+            if (error.code === 1 && !error.killed)
+                return resolve("");
+            reject(error);
+        });
+        child.stdin?.end();
+    });
+}
 const DEFAULT_TRIGGERS = [
     {
         pattern: "AI:",
@@ -110,15 +126,16 @@ export class CommentWatcher extends EventEmitter {
         // Build pattern for ripgrep
         const patterns = this.config.triggers.map((t) => t.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
         const pattern = patterns.join("|");
-        // Build ignore patterns
-        const ignores = this.config.ignoreDirs.map((d) => `--glob '!${d}/**'`).join(" ");
-        // Build file type filters
-        const types = this.config.fileExtensions.map((e) => `--glob '*${e}'`).join(" ");
+        const rgArgs = [
+            "-n", "--no-heading", "--color=never", "--ignore-case",
+            ...this.config.ignoreDirs.flatMap((d) => ["--glob", `!${d}/**`]),
+            ...this.config.fileExtensions.flatMap((e) => ["--glob", `*${e}`]),
+            // Explicit path: without it ripgrep reads the inherited stdin pipe, which
+            // never closes inside the CLI, and the scan hangs forever.
+            "--", pattern, ".",
+        ];
         try {
-            const { stdout } = await execAsync(`rg -n "${pattern}" ${ignores} ${types} || true`, {
-                cwd: this.projectRoot,
-                maxBuffer: 10 * 1024 * 1024,
-            });
+            const stdout = await runRipgrep(rgArgs, this.projectRoot);
             const lines = stdout.trim().split("\n").filter(Boolean);
             for (const line of lines) {
                 // Format: file:line:content
@@ -133,7 +150,7 @@ export class CommentWatcher extends EventEmitter {
                     const triggerMatch = content.match(trigger.regex);
                     if (triggerMatch) {
                         this.detectedComments.push({
-                            file,
+                            file: path.resolve(this.projectRoot, file),
                             line: parseInt(lineNum),
                             column: content.indexOf(triggerMatch[0]),
                             trigger: trigger.pattern,

package/dist/tools/core-code-inspection.d.ts

@@ -0,0 +1,56 @@
+import type { CoreRootResolution } from '../identity/operational-self-model.js';
+export interface CoreCodeRequest {
+    operation: 'list' | 'read' | 'search';
+    path?: string;
+    query?: string;
+    line?: number;
+    offset?: number;
+}
+/** Read only implementation files within the already-attested core, never the user's project. */
+export declare function inspectCoreCode(core: CoreRootResolution, request: CoreCodeRequest): {
+    operation: string;
+    path: string;
+    line: number;
+    totalLines: number;
+    content: string;
+    truncated: boolean;
+    entries?: undefined;
+    offset?: undefined;
+    nextOffset?: undefined;
+    totalEntries?: undefined;
+    query?: undefined;
+    matches?: undefined;
+} | {
+    operation: string;
+    path: string;
+    entries: {
+        name: string;
+        directory: boolean;
+    }[];
+    offset: number;
+    nextOffset: number | null;
+    totalEntries: number;
+    truncated: boolean;
+    line?: undefined;
+    totalLines?: undefined;
+    content?: undefined;
+    query?: undefined;
+    matches?: undefined;
+} | {
+    operation: string;
+    path: string;
+    query: string;
+    matches: {
+        path: string;
+        line: number;
+        text: string;
+    }[];
+    truncated: boolean;
+    line?: undefined;
+    totalLines?: undefined;
+    content?: undefined;
+    entries?: undefined;
+    offset?: undefined;
+    nextOffset?: undefined;
+    totalEntries?: undefined;
+};

package/dist/tools/core-code-inspection.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const TEXT_FILE = /\.(?:[cm]?[jt]sx?|md)$/i;
+const MAX_FILE_BYTES = 512 * 1024;
+/** Read only implementation files within the already-attested core, never the user's project. */
+export function inspectCoreCode(core, request) {
+    if (core.layout === 'unknown')
+        throw new Error('Code Buddy implementation root is not attested.');
+    const root = fs.realpathSync(core.root);
+    const relative = request.path || (core.layout === 'source' ? 'src' : 'dist');
+    if (path.isAbsolute(relative) || relative.includes('\\') || relative.split('/').some(p => p === '..' || p.startsWith('.')) ||
+        !/^(src|dist|packages)(\/|$)/.test(relative)) {
+        throw new Error('Use a relative implementation path under src/, dist/ or packages/.');
+    }
+    const target = path.resolve(root, relative);
+    function confined(file) {
+        const real = fs.realpathSync(file);
+        const rel = path.relative(root, real);
+        return !path.isAbsolute(rel) && /^(src|dist|packages)(\/|$)/.test(rel.split(path.sep).join('/')) &&
+            !rel.split(path.sep).some(part => part.startsWith('.'));
+    }
+    if (!confined(target))
+        throw new Error('Implementation path escapes the core root.');
+    const stat = fs.statSync(target);
+    if (request.operation === 'read') {
+        if (!stat.isFile() || !TEXT_FILE.test(target) || stat.size > MAX_FILE_BYTES)
+            throw new Error('Expected an implementation text file of at most 512 KiB.');
+        const lines = fs.readFileSync(target, 'utf8').split('\n');
+        const start = Math.max(1, request.line ?? 1);
+        return { operation: 'read', path: relative, line: start, totalLines: lines.length,
+            content: lines.slice(start - 1, start + 119).map((text, i) => `${start + i}: ${text.slice(0, 500)}`).join('\n'),
+            truncated: start + 119 < lines.length };
+    }
+    if (!stat.isDirectory())
+        throw new Error('Expected an implementation directory.');
+    if (request.operation === 'list') {
+        const entries = fs.readdirSync(target, { withFileTypes: true }).filter(entry => !entry.name.startsWith('.') && entry.name !== 'node_modules' && !entry.isSymbolicLink() &&
+            (entry.isDirectory() || TEXT_FILE.test(entry.name)));
+        const offset = request.offset ?? 0;
+        if (!Number.isSafeInteger(offset) || offset < 0)
+            throw new Error('List offset must be a non-negative integer.');
+        const nextOffset = offset + 100 < entries.length ? offset + 100 : null;
+        return { operation: 'list', path: relative, entries: entries.slice(offset, offset + 100).map(entry => ({
+                name: entry.name, directory: entry.isDirectory(),
+            })), offset, nextOffset, totalEntries: entries.length, truncated: nextOffset !== null };
+    }
+    if (!request.query?.trim() || request.query.length > 160)
+        throw new Error('Search requires a literal query of 1–160 characters.');
+    const query = request.query.toLowerCase();
+    const matches = [];
+    const pending = [target];
+    let visited = 0;
+    let bytes = 0;
+    while (pending.length && visited < 4000 && matches.length < 30 && bytes < 8 * 1024 * 1024) {
+        const dir = pending.shift();
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (++visited >= 4000 || matches.length >= 30 || bytes >= 8 * 1024 * 1024)
+                break;
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.isSymbolicLink())
+                continue;
+            const file = path.join(dir, entry.name);
+            if (!confined(file))
+                continue;
+            if (entry.isDirectory()) {
+                pending.push(file);
+                continue;
+            }
+            if (!entry.isFile() || !TEXT_FILE.test(entry.name))
+                continue;
+            const size = fs.statSync(file).size;
+            if (size > MAX_FILE_BYTES)
+                continue;
+            bytes += size;
+            const lines = fs.readFileSync(file, 'utf8').split('\n');
+            for (let i = 0; i < lines.length && matches.length < 30; i++) {
+                if (lines[i].toLowerCase().includes(query))
+                    matches.push({
+                        path: path.relative(root, file).split(path.sep).join('/'), line: i + 1, text: lines[i].slice(0, 500),
+                    });
+            }
+        }
+    }
+    return { operation: 'search', path: relative, query: request.query, matches,
+        truncated: pending.length > 0 || visited >= 4000 || matches.length >= 30 || bytes >= 8 * 1024 * 1024 };
+}
+//# sourceMappingURL=core-code-inspection.js.map

package/dist/tools/create-skill-tool.d.ts

@@ -10,7 +10,7 @@
  * commands it uses repeatedly and codify them as reusable skills.
  *
  * Skill file location:
- *   .codebuddy/skills/workspace/<slug>/SKILL.md
+ *   .codebuddy/skills/<authored-slug>/SKILL.md
  *
  * The tool generates valid SKILL.md frontmatter and validates that
  * the slug does not already exist before writing.
@@ -36,8 +36,7 @@ export interface CreateSkillInput {
     overwrite?: boolean;
 }
 export declare class CreateSkillTool {
-    private get workspaceDir();
-    execute(input: CreateSkillInput): Promise<ToolResult>;
+    execute(input: CreateSkillInput, cwd?: string): Promise<ToolResult>;
     getSchema(): {
         name: string;
         description: string;