@vietor/agent-core 0.7.0

package/dist/runtime/todo-store.js

@@ -0,0 +1,15 @@
+import { Emitter } from "../util/emitter.js";
+export class TodoStore {
+    listeners = new Emitter();
+    items = [];
+    get all() {
+        return this.items;
+    }
+    subscribe(listener) {
+        return this.listeners.subscribe(listener);
+    }
+    set(todos) {
+        this.items = todos;
+        this.listeners.notify();
+    }
+}

package/dist/skills/loader.d.ts

@@ -0,0 +1,6 @@
+export interface Skill {
+    name: string;
+    description?: string;
+    prompt: string;
+}
+export declare function tryLoadSkills(path: string): Skill[] | undefined;

package/dist/skills/loader.js

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tryReadFileText } from "../util/file.js";
+function parseSkillFile(skillName, skillFile) {
+    const content = tryReadFileText(skillFile);
+    if (!content)
+        return undefined;
+    const frontMatterRegex = /^---\r?\n([\s\S]*?)\r?\n---/;
+    const match = content.match(frontMatterRegex);
+    let name = null;
+    let description = "";
+    let prompt = content;
+    if (match) {
+        const yamlBody = match[1];
+        prompt = content.replace(match[0], "").trim();
+        const nameMatch = yamlBody.match(/^name:\s*(.+)$/m);
+        if (nameMatch)
+            name = nameMatch[1].trim();
+        const descMatch = yamlBody.match(/^description:\s*(.+)$/m);
+        if (descMatch)
+            description = descMatch[1].trim();
+    }
+    if (!name) {
+        name = skillName;
+    }
+    return { name, description, prompt };
+}
+export function tryLoadSkills(path) {
+    if (!existsSync(path))
+        return undefined;
+    const skills = [];
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillFile = join(path, entry.name, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const skill = parseSkillFile(entry.name, skillFile);
+        if (skill && skill.prompt)
+            skills.push(skill);
+    }
+    return skills.length > 0 ? skills : undefined;
+}

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "./types.js";
+export declare const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking.";
+export declare function createAskUserTool(ask: (question: string, options: string[]) => Promise<string>): Tool;

package/dist/tools/ask-user.js

@@ -0,0 +1,26 @@
+import { toolError } from "./types.js";
+export const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking.";
+const DESCRIPTION = "Ask the user a question and wait for the answer. Provide at least one option. Returns the answer as text.";
+export function createAskUserTool(ask) {
+    return {
+        name: "AskUser",
+        description: DESCRIPTION,
+        parameters: {
+            type: "object",
+            properties: {
+                question: { type: "string", description: "The question to ask the user." },
+                options: { type: "array", items: { type: "string" }, minItems: 1, description: "List of choices; at least one required." },
+            },
+            required: ["question", "options"],
+        },
+        async execute(args, _ctx) {
+            const question = args.question;
+            const options = Array.isArray(args.options) ? args.options : [];
+            if (!options.length) {
+                return toolError("options must contain at least one choice");
+            }
+            return { content: await ask(question, options) };
+        },
+        summaryKeys: ["question"],
+    };
+}

package/dist/tools/file-edit.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const fileEditTool: Tool;

package/dist/tools/file-edit.js

@@ -0,0 +1,43 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolveRequiredPath } from "../util/file.js";
+const DESCRIPTION = "Replace old_string with new_string in a file. Read the file first — old_string must match exactly including whitespace/indentation. Must be unique unless replace_all is set. For full rewrites prefer FileWrite.";
+export const fileEditTool = {
+    name: "FileEdit",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+            replace_all: { type: "boolean", description: "replace all occurrences (default false)" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    async execute(args, ctx) {
+        const resolved = resolveRequiredPath(args, ctx.cwd);
+        const oldStr = args.old_string;
+        const newStr = args.new_string;
+        const all = args.replace_all === true;
+        if (!oldStr)
+            throw new Error("old_string is required");
+        const content = await readFile(resolved, "utf-8");
+        if (!content.includes(oldStr))
+            throw new Error(`old_string not found in ${args.path}; re-read the file with FileRead to get the exact current text (watch whitespace/indentation)`);
+        if (all) {
+            await writeFile(resolved, content.split(oldStr).join(newStr), "utf-8");
+            return { content: `Edited ${args.path} (replaced all)` };
+        }
+        const count = content.split(oldStr).length - 1;
+        if (count > 1)
+            throw new Error(`old_string appears ${count} times in ${args.path}, must be unique (or set replace_all)`);
+        await writeFile(resolved, content.replace(oldStr, newStr), "utf-8");
+        return { content: `Edited ${args.path}` };
+    },
+    summarizeResult(result) {
+        if (result.isError)
+            return "Edit failed";
+        return "Edit completed";
+    },
+    summaryKeys: ["path"],
+};

package/dist/tools/file-read.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const fileReadTool: Tool;

package/dist/tools/file-read.js

@@ -0,0 +1,93 @@
+import { open } from "node:fs/promises";
+import { resolveRequiredPath } from "../util/file.js";
+import { DEFAULT_FILE_READ_LIMIT, MAX_FILE_READ_MB, mbToBytes } from "../util/constants.js";
+import { formatCompactNumber, summaryBytes } from "../util/text.js";
+const CHUNK = 64 * 1024;
+const MAX_FILE_READ_BYTES = mbToBytes(MAX_FILE_READ_MB);
+const DESCRIPTION = `Read a file as UTF-8 text, returned with line numbers (cat -n format). Reads up to ${DEFAULT_FILE_READ_LIMIT} lines; use offset and limit to page further. Files over ${MAX_FILE_READ_MB}MB are rejected. Binary files may return garbled output or fail.`;
+async function readPage(handle, offset, limit) {
+    const startLine = offset - 1;
+    let newlines = 0;
+    let windowStart = startLine === 0 ? 0 : -1;
+    const pieces = [];
+    const buf = Buffer.allocUnsafe(CHUNK);
+    for (;;) {
+        const { bytesRead } = await handle.read(buf, 0, CHUNK, null);
+        if (bytesRead === 0)
+            break;
+        for (let from = 0;;) {
+            const i = buf.indexOf(0x0a, from);
+            if (i === -1 || i >= bytesRead)
+                break;
+            if (newlines === startLine - 1)
+                windowStart = i + 1;
+            newlines++;
+            if (newlines === startLine + limit) {
+                if (windowStart >= 0 && windowStart < i)
+                    pieces.push(Buffer.from(buf.subarray(windowStart, i)));
+                return { text: Buffer.concat(pieces).toString("utf-8"), totalLines: -1, eof: false };
+            }
+            from = i + 1;
+        }
+        if (windowStart >= 0) {
+            if (windowStart < bytesRead)
+                pieces.push(Buffer.from(buf.subarray(windowStart, bytesRead)));
+            windowStart = 0;
+        }
+    }
+    const totalLines = newlines + 1;
+    if (startLine >= totalLines)
+        return { text: null, totalLines, eof: true };
+    return { text: Buffer.concat(pieces).toString("utf-8"), totalLines, eof: true };
+}
+export const fileReadTool = {
+    name: "FileRead",
+    readOnly: true,
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            offset: { type: "number", description: "line number to start reading from (1-indexed)" },
+            limit: { type: "number", description: `number of lines to read (default ${DEFAULT_FILE_READ_LIMIT})` },
+        },
+        required: ["path"],
+    },
+    async execute(args, ctx) {
+        const resolved = resolveRequiredPath(args, ctx.cwd);
+        const offset = args.offset === undefined ? 1 : args.offset;
+        const limit = args.limit === undefined ? DEFAULT_FILE_READ_LIMIT : args.limit;
+        if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 1)
+            throw new Error("offset must be a positive integer");
+        if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1)
+            throw new Error("limit must be a positive integer");
+        const handle = await open(resolved, "r");
+        try {
+            const { size } = await handle.stat();
+            if (size > MAX_FILE_READ_BYTES) {
+                throw new Error(`file is ${formatCompactNumber(size)} — larger than the ${formatCompactNumber(MAX_FILE_READ_BYTES)} read limit`);
+            }
+            if (size === 0)
+                return { content: "(empty file)" };
+            const { text, totalLines, eof } = await readPage(handle, offset, limit);
+            if (text === null) {
+                return { content: `(offset ${offset} is past end of file; file has ${totalLines} lines)` };
+            }
+            const lines = text.split("\n");
+            let out = lines
+                .map((line, i) => `${String(offset + i).padStart(6, " ")}\t${line}`)
+                .join("\n");
+            if (!eof) {
+                out += `\n(more lines; use offset=${offset + limit} to continue)`;
+            }
+            return { content: out };
+        }
+        finally {
+            await handle.close();
+        }
+    },
+    summarizeResult(result) {
+        return summaryBytes("Read", result, "Read failed");
+    },
+    summaryKeys: ["path"],
+};

package/dist/tools/file-write.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const fileWriteTool: Tool;

package/dist/tools/file-write.js

@@ -0,0 +1,25 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolveRequiredPath } from "../util/file.js";
+const DESCRIPTION = "Write content to a file, overwriting if it exists and creating parent directories. For targeted changes prefer FileEdit.";
+export const fileWriteTool = {
+    name: "FileWrite",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: { path: { type: "string" }, content: { type: "string" } },
+        required: ["path", "content"],
+    },
+    async execute(args, ctx) {
+        const resolved = resolveRequiredPath(args, ctx.cwd);
+        await mkdir(dirname(resolved), { recursive: true });
+        await writeFile(resolved, args.content, "utf-8");
+        return { content: `Wrote ${args.path}` };
+    },
+    summarizeResult(result) {
+        if (result.isError)
+            return "Write failed";
+        return "Write completed";
+    },
+    summaryKeys: ["path"],
+};

package/dist/tools/glob.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const globTool: Tool;

package/dist/tools/glob.js

@@ -0,0 +1,31 @@
+import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
+import { NO_MATCHES } from "../util/constants.js";
+import { resolveOptionalPath } from "../util/file.js";
+const DESCRIPTION = "List files under a directory, optionally filtered by a glob pattern (e.g. **/*.ts). Skips node_modules and .git.";
+export const globTool = {
+    name: "Glob",
+    readOnly: true,
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "glob pattern; omit to list all files" },
+            path: { type: "string", description: "root directory, defaults to cwd" },
+        },
+        required: [],
+    },
+    async execute(args, ctx) {
+        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const rgArgs = ["--files"];
+        const pattern = args.pattern;
+        if (pattern)
+            rgArgs.push("-g", pattern);
+        rgArgs.push(".");
+        const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal);
+        return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
+    },
+    summarizeResult(result) {
+        return ripgrepResultSummary("file", result, "Glob failed", "Found 0 files");
+    },
+    summaryKeys: ["pattern", "path"],
+};

package/dist/tools/grep.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const grepTool: Tool;

package/dist/tools/grep.js

@@ -0,0 +1,67 @@
+import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
+import { DEFAULT_GREP_LIMIT, NO_MATCHES } from "../util/constants.js";
+import { resolveOptionalPath } from "../util/file.js";
+const DESCRIPTION = `Search file contents recursively for a regex pattern (RE2 syntax). Skips node_modules and .git. Returns path:line:content, capped at ${DEFAULT_GREP_LIMIT} lines. For large codebases, use output_mode=files_with_matches first, or narrow with glob/type, or raise head_limit.`;
+export const grepTool = {
+    name: "Grep",
+    readOnly: true,
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string" },
+            path: { type: "string", description: "root directory, defaults to cwd" },
+            glob: { type: "string", description: "filter files, e.g. *.ts" },
+            type: { type: "string", description: "file type, e.g. ts, js, py" },
+            output_mode: { type: "string", enum: ["content", "files_with_matches", "count"], description: "defaults to content" },
+            ignore_case: { type: "boolean", description: "case-insensitive" },
+            before: { type: "number", description: "lines before each match" },
+            after: { type: "number", description: "lines after each match" },
+            context: { type: "number", description: "lines before and after each match" },
+            only_matching: { type: "boolean", description: "only the matched parts" },
+            multiline: { type: "boolean", description: "patterns may span newlines" },
+            head_limit: { type: "number", description: `max output lines, default ${DEFAULT_GREP_LIMIT}` },
+        },
+        required: ["pattern"],
+    },
+    async execute(args, ctx) {
+        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const rgArgs = ["--line-number", "--with-filename", "--no-heading"];
+        if (args.ignore_case)
+            rgArgs.push("-i");
+        if (args.only_matching)
+            rgArgs.push("-o");
+        if (args.multiline)
+            rgArgs.push("-U", "--multiline-dotall");
+        const context = args.context;
+        if (context)
+            rgArgs.push("-C", String(context));
+        else {
+            const before = args.before;
+            const after = args.after;
+            if (before)
+                rgArgs.push("-B", String(before));
+            if (after)
+                rgArgs.push("-A", String(after));
+        }
+        if (args.glob)
+            rgArgs.push("-g", args.glob);
+        if (args.type)
+            rgArgs.push("-t", args.type);
+        const output_mode = args.output_mode || "content";
+        const headLimit = args.head_limit || DEFAULT_GREP_LIMIT;
+        if (output_mode === "files_with_matches")
+            rgArgs.push("-l");
+        else if (output_mode === "count")
+            rgArgs.push("-c");
+        else
+            rgArgs.push("-m", String(headLimit));
+        rgArgs.push("--", args.pattern, ".");
+        const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal, headLimit);
+        return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
+    },
+    summarizeResult(result) {
+        return ripgrepResultSummary("match", result, "Grep failed", "Found 0 matches");
+    },
+    summaryKeys: ["pattern", "path", "glob"],
+};

package/dist/tools/registry.d.ts

@@ -0,0 +1,30 @@
+import type { Tool, ToolContext, ToolSchema, Todo } from "./types.js";
+import { type SubAgentToolDeps } from "./sub-agent.js";
+import type { Skill } from "../skills/loader.js";
+import type { TextResult } from "./types.js";
+export declare class ToolRegistry {
+    private tools;
+    private schemasCache;
+    register(tool: Tool): this;
+    registerAll(tools: Tool[]): this;
+    get(name: string): Tool | undefined;
+    filter(predicate: (t: Tool) => boolean): Tool[];
+    schemas(): ToolSchema[];
+    unregister(name: string): void;
+    execute(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<TextResult>;
+    summarizeResult(name: string, result: TextResult, durationMs?: number): string;
+    summarizeArgs(name: string, args: Record<string, unknown>): string;
+}
+export interface BuiltinToolsOptions {
+    readOnly?: boolean;
+    askUser?: boolean;
+    todoWrite?: boolean;
+    subAgent?: boolean;
+}
+export interface BuiltinToolsDeps {
+    ask: (question: string, options: string[]) => Promise<string>;
+    setTodos: (todos: Todo[]) => void;
+    resolveSkill?: (name: string) => Skill | undefined;
+    subAgent: SubAgentToolDeps;
+}
+export declare function registerBuiltinTools(tools: ToolRegistry, opts: BuiltinToolsOptions | false | undefined, deps: BuiltinToolsDeps): void;

package/dist/tools/registry.js

@@ -0,0 +1,107 @@
+import { toolError } from "./types.js";
+import { shellTool } from "./shell.js";
+import { fileReadTool } from "./file-read.js";
+import { fileWriteTool } from "./file-write.js";
+import { fileEditTool } from "./file-edit.js";
+import { globTool } from "./glob.js";
+import { grepTool } from "./grep.js";
+import { webFetchTool } from "./web-fetch.js";
+import { createAskUserTool } from "./ask-user.js";
+import { createSkillTool } from "./skill.js";
+import { createTodoWriteTool } from "./todo-write.js";
+import { createSubAgentTool } from "./sub-agent.js";
+import { MAX_ARGS_SUMMARY_LENGTH } from "../util/constants.js";
+import { defaultResultSummary, formatDuration, summarizeText, toErrorMessage } from "../util/text.js";
+export class ToolRegistry {
+    tools = new Map();
+    schemasCache = null;
+    register(tool) {
+        this.tools.set(tool.name, tool);
+        this.schemasCache = null;
+        return this;
+    }
+    registerAll(tools) {
+        for (const t of tools)
+            this.tools.set(t.name, t);
+        this.schemasCache = null;
+        return this;
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    filter(predicate) {
+        return [...this.tools.values()].filter(predicate);
+    }
+    schemas() {
+        if (!this.schemasCache) {
+            this.schemasCache = [...this.tools.values()].map((t) => ({
+                type: "function",
+                function: {
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                },
+            }));
+        }
+        return this.schemasCache;
+    }
+    unregister(name) {
+        if (this.tools.delete(name)) {
+            this.schemasCache = null;
+        }
+    }
+    async execute(name, args, ctx) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            return toolError(`unknown tool ${name}`);
+        try {
+            return await tool.execute(args, ctx);
+        }
+        catch (e) {
+            return toolError(toErrorMessage(e));
+        }
+    }
+    summarizeResult(name, result, durationMs) {
+        const tool = this.tools.get(name);
+        const resultSummary = tool?.summarizeResult
+            ? tool.summarizeResult(result)
+            : defaultResultSummary(result);
+        return durationMs !== undefined
+            ? `[${formatDuration(durationMs / 1000)}] ${resultSummary}`
+            : resultSummary;
+    }
+    summarizeArgs(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            return "";
+        if (tool.summarizeArgs)
+            return tool.summarizeArgs(args);
+        if (!tool.summaryKeys)
+            return "";
+        const parts = [];
+        for (const k of tool.summaryKeys) {
+            const v = args[k];
+            if (typeof v === "string" && v) {
+                parts.push(v);
+            }
+        }
+        return summarizeText(parts.join(" "), MAX_ARGS_SUMMARY_LENGTH, true);
+    }
+}
+const BUILTIN_TOOLS = [fileReadTool, globTool, grepTool, webFetchTool, shellTool, fileWriteTool, fileEditTool];
+export function registerBuiltinTools(tools, opts, deps) {
+    if (opts === false)
+        return;
+    const builtins = opts?.readOnly ? BUILTIN_TOOLS.filter((t) => t.readOnly) : BUILTIN_TOOLS;
+    for (const tool of builtins) {
+        tools.register(tool);
+    }
+    if (opts?.askUser)
+        tools.register(createAskUserTool(deps.ask));
+    if (opts?.todoWrite)
+        tools.register(createTodoWriteTool(deps.setTodos));
+    if (deps.resolveSkill)
+        tools.register(createSkillTool(deps.resolveSkill));
+    if (opts?.subAgent)
+        tools.register(createSubAgentTool(deps.subAgent));
+}

package/dist/tools/shell.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "./types.js";
+export declare const shellTool: Tool;

package/dist/tools/shell.js

@@ -0,0 +1,57 @@
+import { runProcess } from "../util/subprocess.js";
+import { CALL_TIMEOUT_MS, NO_OUTPUT } from "../util/constants.js";
+import { toolError } from "./types.js";
+import { summaryBytes } from "../util/text.js";
+const isWindows = process.platform === "win32";
+const shell = isWindows ? "powershell.exe" : (process.env.SHELL || "/bin/bash");
+const shellArgs = isWindows ? ["-NoProfile", "-NonInteractive", "-Command"] : ["-c"];
+const commandPrefix = isWindows
+    ? "[Console]::OutputEncoding=[Text.Encoding]::UTF8; $OutputEncoding=[Text.Encoding]::UTF8; "
+    : "";
+const PRIVILEGED_RE = /(^|[;&|()`\n])\s*(?:(?:env|command|xargs)\s+)?(sudo|su|doas|pkexec)\b/;
+const DESCRIPTION_POWERSHELL = `
+Windows PowerShell 5.1 (powershell.exe — NOT pwsh/bash).
+
+WARNING — four common mistakes:
+• QUOTE unquoted args starting with a single - that contain a dot — splits them at the last dot (or use --%).
+  Example: -DoutputFile=dep.txt → "-DoutputFile=dep" + ".txt" → fails; use "-DoutputFile=dep.txt"
+  Safe unquoted: --key=value, plain paths, dotless values.
+• Use ; not &&/|| to chain commands
+• Use \` (backtick) to escape, not \\
+• Use $env:NAME, not $NAME
+
+QUOTING: '...' literal. "..." expands $var, $env:NAME, $(...).
+SYNTAX: Conditional: if ($?) { }. No heredocs (<<) or background (&).
+LIMITATIONS: No stdin. Long-running killed at timeout.
+`;
+const DESCRIPTION_BASH = `
+Execute a bash command.
+
+QUOTING: Always double-quote: "$FILE" not $FILE.
+LIMITATIONS: Blocked: direct sudo/su/doas/pkexec (best-effort; indirect invocation may bypass). No stdin. Long-running killed at timeout.
+`;
+export const shellTool = {
+    name: "Shell",
+    description: isWindows ? DESCRIPTION_POWERSHELL : DESCRIPTION_BASH,
+    parameters: {
+        type: "object",
+        properties: { command: { type: "string" } },
+        required: ["command"],
+    },
+    async execute(args, ctx) {
+        const command = args.command;
+        if (!isWindows && PRIVILEGED_RE.test(command)) {
+            return toolError("privileged commands (sudo/su/doas/pkexec) are not allowed");
+        }
+        const r = await runProcess(shell, [...shellArgs, commandPrefix + command], { cwd: ctx.cwd, timeout: CALL_TIMEOUT_MS }, ctx.signal);
+        if (r.status === 0 && !r.error) {
+            return { content: r.stdout || NO_OUTPUT };
+        }
+        const parts = [r.stdout, r.stderr, r.error?.message].filter(Boolean);
+        return toolError(parts.join("\n") || NO_OUTPUT);
+    },
+    summarizeResult(result) {
+        return summaryBytes("Command executed", result, "Command failed");
+    },
+    summaryKeys: ["command"],
+};

package/dist/tools/skill.d.ts

@@ -0,0 +1,3 @@
+import type { Skill } from "../skills/loader.js";
+import type { Tool } from "./types.js";
+export declare function createSkillTool(resolve: (name: string) => Skill | undefined): Tool;

package/dist/tools/skill.js

@@ -0,0 +1,30 @@
+import { SKILL_TOOL_NAME } from "../util/constants.js";
+import { toolError } from "./types.js";
+const DESCRIPTION = "Invoke a skill by name. Skills are packaged instructions that extend capabilities. Available skills and their descriptions are listed in the system prompt. When invoked, the skill's instructions are loaded into context — follow them.";
+export function createSkillTool(resolve) {
+    return {
+        name: SKILL_TOOL_NAME,
+        description: DESCRIPTION,
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The name of the skill to invoke" },
+            },
+            required: ["name"],
+        },
+        summaryKeys: ["name"],
+        async execute(args, _ctx) {
+            const name = (args.name || "").trim();
+            if (!name) {
+                return toolError("skill name is required");
+            }
+            if (!resolve(name)) {
+                return toolError(`skill "${name}" not found`);
+            }
+            return { content: `Skill "${name}" loaded. Follow its instructions above.` };
+        },
+        summarizeResult(_result) {
+            return "Successfully loaded skill";
+        }
+    };
+}

package/dist/tools/sub-agent.d.ts

@@ -0,0 +1,7 @@
+import type { SubAgentRunResult } from "../runtime/sub-agent-runner.js";
+import type { Tool } from "./types.js";
+export declare const SUB_AGENT_GUIDANCE = "- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files \u2014 delegate and keep the conclusion, not the file dumps. type: \"explore\" \u2014 read-only search agent for broad fan-out searches (state the search breadth in the task); type: \"plan\" \u2014 software architect producing implementation plans. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself \u2014 wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps \u2014 verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.";
+export interface SubAgentToolDeps {
+    runSubAgent: (systemPrompt: string, task: string, signal?: AbortSignal) => Promise<SubAgentRunResult>;
+}
+export declare function createSubAgentTool(deps: SubAgentToolDeps): Tool;