@oharness/engine 0.1.0

package/dist/tools/builtin/memory.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+/**
+ * Read and write the agent's durable notes.
+ *
+ * Split into two tools rather than one with a `mode` argument: writing a note
+ * is a decision the model should make deliberately, and a single tool whose
+ * behaviour flips on a string is one the model gets wrong under pressure.
+ */
+export function createMemoryTools(memory) {
+    const read = defineTool({
+        name: "memory",
+        readOnly: true,
+        description: "Read notes recorded in earlier sessions. Call with an id from the memory index " +
+            "in the system prompt to read one in full, or with a query to search. The index " +
+            "shows summaries only — read the note before relying on it.",
+        parameters: z.object({
+            id: z.string().optional().describe("Note id to read in full"),
+            query: z.string().optional().describe("Text to search summaries, bodies and tags for"),
+        }),
+        renderTitle: (input) => `Memory(${input.id ?? input.query ?? "all"})`,
+        async execute(input) {
+            const entries = await memory.load();
+            if (entries.length === 0) {
+                return toolText("No notes have been recorded yet.");
+            }
+            if (input.id) {
+                const entry = entries.find((candidate) => candidate.id === input.id);
+                if (!entry) {
+                    return toolError(`No note with id "${input.id}". Known ids: ${entries.map((e) => e.id).join(", ")}`);
+                }
+                return toolText(render(entry));
+            }
+            const matches = input.query ? await memory.search(input.query) : entries;
+            if (matches.length === 0) {
+                return toolText(`No note matches "${input.query}".`);
+            }
+            return toolText(matches.slice(0, 10).map(render).join("\n\n---\n\n"), {
+                matched: matches.length,
+            });
+        },
+    });
+    const write = defineTool({
+        name: "remember",
+        description: "Record something worth carrying into future sessions — a correction, a convention " +
+            "this project follows, an approach that worked. Do not record what the code or git " +
+            "history already says, or anything that only matters to the current task. Writing " +
+            "the same summary again updates the existing note rather than adding a duplicate.",
+        parameters: z.object({
+            summary: z
+                .string()
+                .min(4)
+                .describe("One line naming the lesson; this is what appears in the index"),
+            body: z
+                .string()
+                .min(4)
+                .describe("The note itself: what was learned, why it matters, how to apply it"),
+            tags: z.array(z.string()).optional().describe("Tags to help find it later"),
+        }),
+        renderTitle: (input) => `Remember(${input.summary.slice(0, 40)})`,
+        async execute(input) {
+            const entry = await memory.remember(input);
+            return toolText(`Recorded as \`${entry.id}\`.`, { id: entry.id, file: entry.file });
+        },
+    });
+    return [read, write];
+}
+function render(entry) {
+    const when = entry.createdAt
+        ? new Date(entry.createdAt).toISOString().slice(0, 10)
+        : "unknown date";
+    const tags = entry.tags.length > 0 ? ` · ${entry.tags.join(", ")}` : "";
+    return `### ${entry.id} (${when}${tags})\n${entry.summary}\n\n${entry.body}`;
+}
+//# sourceMappingURL=memory.js.map

package/dist/tools/builtin/memory.js.map

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

package/dist/tools/builtin/recall.d.ts

@@ -0,0 +1,13 @@
+import type { ArchivedMessage } from "../../agent/store.ts";
+/** Where the agent loop parks a reader for the current session's archive. */
+export declare const ARCHIVE_READER = "session:archiveReader";
+export type ArchiveReader = () => Promise<ArchivedMessage[]>;
+/**
+ * Reach back into conversation history that compaction summarized away.
+ *
+ * A summary is lossy by construction — the model writing it cannot know which
+ * detail will matter twenty turns later. Archiving the originals is only half
+ * the fix; the agent also needs a way to ask for them, or it will confidently
+ * re-derive things it could have looked up.
+ */
+export declare const recallTool: import("../types.ts").Tool;

package/dist/tools/builtin/recall.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { messageText } from "../../core/types.js";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+/** Where the agent loop parks a reader for the current session's archive. */
+export const ARCHIVE_READER = "session:archiveReader";
+const MAX_CHARS = 12_000;
+const DEFAULT_LIMIT = 10;
+/**
+ * Reach back into conversation history that compaction summarized away.
+ *
+ * A summary is lossy by construction — the model writing it cannot know which
+ * detail will matter twenty turns later. Archiving the originals is only half
+ * the fix; the agent also needs a way to ask for them, or it will confidently
+ * re-derive things it could have looked up.
+ */
+export const recallTool = defineTool({
+    name: "recall",
+    description: "Search the archived earlier conversation that was summarized away by compaction. " +
+        "Use it when the summary mentions something without the detail you need — an exact " +
+        "error message, a file path, a decision and its reasoning. Search by keyword, or fetch " +
+        "a specific range with `fromSeq`/`toSeq`. Returns nothing if this session has not been " +
+        "compacted yet.",
+    readOnly: true,
+    parameters: z.object({
+        query: z
+            .string()
+            .optional()
+            .describe("Case-insensitive text to search for across archived messages"),
+        fromSeq: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Start of a sequence range to fetch verbatim"),
+        toSeq: z.number().int().min(0).optional().describe("End of the range, inclusive"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe(`Maximum messages to return (default ${DEFAULT_LIMIT})`),
+    }),
+    renderTitle: (input) => input.query
+        ? `Recall(${input.query})`
+        : input.fromSeq !== undefined
+            ? `Recall(#${input.fromSeq}–${input.toSeq ?? input.fromSeq})`
+            : "Recall(recent)",
+    async execute(input, ctx) {
+        const reader = ctx.host.state.get(ARCHIVE_READER);
+        if (!reader) {
+            return toolError("no archive is available for this session");
+        }
+        const archive = await reader();
+        if (archive.length === 0) {
+            return toolText("Nothing has been archived — this conversation has not been compacted, so the full history is already in context.");
+        }
+        const limit = input.limit ?? DEFAULT_LIMIT;
+        let matches = archive;
+        if (input.fromSeq !== undefined) {
+            const to = input.toSeq ?? input.fromSeq;
+            matches = archive.filter((entry) => entry.seq >= input.fromSeq && entry.seq <= to);
+        }
+        else if (input.query) {
+            const needle = input.query.toLowerCase();
+            matches = archive.filter((entry) => searchableText(entry.message).includes(needle));
+        }
+        else {
+            // No filter: the most recent archived messages are the likeliest target.
+            matches = archive.slice(-limit);
+        }
+        if (matches.length === 0) {
+            return toolText(`No archived message matches ${input.query ? `"${input.query}"` : "that range"}. ` +
+                `The archive covers sequences ${archive[0].seq}–${archive[archive.length - 1].seq} ` +
+                `(${archive.length} messages).`);
+        }
+        // Keyword hits are most useful newest-first; an explicit range is not.
+        const selected = input.fromSeq !== undefined ? matches.slice(0, limit) : matches.slice(-limit);
+        const rendered = [];
+        let budget = MAX_CHARS;
+        let truncated = 0;
+        for (const entry of selected) {
+            const block = render(entry);
+            if (block.length > budget) {
+                truncated = selected.length - rendered.length;
+                break;
+            }
+            rendered.push(block);
+            budget -= block.length;
+        }
+        const header = `Archived messages ${matches.length === selected.length ? "" : `(${selected.length} of ${matches.length} matches) `}` +
+            `from sequences ${archive[0].seq}–${archive[archive.length - 1].seq}:`;
+        const footer = truncated
+            ? `\n\n… ${truncated} more matching messages omitted for length. Narrow the query or use fromSeq/toSeq.`
+            : matches.length > selected.length
+                ? `\n\n… ${matches.length - selected.length} more matches. Raise \`limit\` or narrow the query.`
+                : "";
+        return toolText(`${header}\n\n${rendered.join("\n\n")}${footer}`, {
+            matched: matches.length,
+            returned: rendered.length,
+        });
+    },
+});
+/** Everything worth matching a keyword against, including tool traffic. */
+function searchableText(message) {
+    const parts = [];
+    for (const block of message.content) {
+        switch (block.type) {
+            case "text":
+                parts.push(block.text);
+                break;
+            case "thinking":
+                parts.push(block.thinking);
+                break;
+            case "tool_call":
+                parts.push(block.name, safeJson(block.input));
+                break;
+            case "tool_result":
+                parts.push(block.toolName);
+                for (const inner of block.content) {
+                    if (inner.type === "text")
+                        parts.push(inner.text);
+                }
+                break;
+            case "image":
+                break;
+        }
+    }
+    return parts.join("\n").toLowerCase();
+}
+function render(entry) {
+    const lines = [`#${entry.seq} ${entry.message.role}:`];
+    const text = messageText(entry.message).trim();
+    if (text)
+        lines.push(text);
+    for (const block of entry.message.content) {
+        if (block.type === "tool_call") {
+            lines.push(`  → called ${block.name}(${truncate(safeJson(block.input), 300)})`);
+        }
+        else if (block.type === "tool_result") {
+            const body = block.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join("\n")
+                .trim();
+            lines.push(`  ← ${block.toolName}${block.isError ? " (error)" : ""}: ${truncate(body, 1_500)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+//# sourceMappingURL=recall.js.map

package/dist/tools/builtin/recall.js.map

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

package/dist/tools/builtin/search.d.ts

@@ -0,0 +1,3 @@
+export declare const globTool: import("../types.ts").Tool;
+export declare const grepTool: import("../types.ts").Tool;
+export declare const searchTools: import("../types.ts").Tool[];

package/dist/tools/builtin/search.js

@@ -0,0 +1,240 @@
+import { spawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { glob } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+import { resolvePath } from "./fs.js";
+const MAX_RESULTS = 200;
+const DEFAULT_IGNORES = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/__pycache__/**",
+    "**/.venv/**",
+    "**/target/**",
+];
+export const globTool = defineTool({
+    name: "glob",
+    description: "Find files by glob pattern (e.g. `src/**/*.ts`). Results are sorted by modification time, newest first. Common build and dependency directories are excluded.",
+    readOnly: true,
+    parameters: z.object({
+        pattern: z.string().describe("Glob pattern, relative to the search root"),
+        path: z.string().optional().describe("Directory to search in; defaults to the working directory"),
+    }),
+    renderTitle: (input) => `Glob(${input.pattern})`,
+    async execute(input, ctx) {
+        let root;
+        try {
+            root = resolvePath(ctx, input.path ?? ".");
+        }
+        catch (err) {
+            return toolError(String(err instanceof Error ? err.message : err));
+        }
+        const matches = [];
+        try {
+            for await (const entry of glob(input.pattern, { cwd: root, exclude: excludeFn })) {
+                matches.push(path.resolve(root, String(entry)));
+                if (matches.length >= MAX_RESULTS * 4)
+                    break;
+            }
+        }
+        catch (err) {
+            return toolError(`glob failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (matches.length === 0)
+            return toolText(`No files match ${input.pattern}`);
+        // Newest first: the file someone is actively working on is usually the
+        // one they mean.
+        const withTimes = await Promise.all(matches.map(async (file) => {
+            try {
+                const info = await stat(file);
+                return { file, mtime: info.mtimeMs, isFile: info.isFile() };
+            }
+            catch {
+                return { file, mtime: 0, isFile: false };
+            }
+        }));
+        const sorted = withTimes
+            .filter((entry) => entry.isFile)
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, MAX_RESULTS)
+            .map((entry) => path.relative(ctx.cwd, entry.file) || entry.file);
+        const truncated = withTimes.length > sorted.length;
+        return toolText(sorted.join("\n") + (truncated ? `\n\n… truncated to ${MAX_RESULTS} results.` : ""), { count: sorted.length, truncated });
+    },
+});
+export const grepTool = defineTool({
+    name: "grep",
+    description: "Search file contents with a regular expression. Uses ripgrep when available. Returns matching lines with file and line number.",
+    readOnly: true,
+    parameters: z.object({
+        pattern: z.string().describe("Regular expression to search for"),
+        path: z.string().optional().describe("File or directory to search; defaults to the working directory"),
+        glob: z.string().optional().describe("Restrict to files matching this glob, e.g. '*.ts'"),
+        caseInsensitive: z.boolean().optional().describe("Case-insensitive match"),
+        filesOnly: z.boolean().optional().describe("List matching file paths instead of matching lines"),
+        contextLines: z.number().int().min(0).max(10).optional().describe("Lines of context around each match"),
+    }),
+    renderTitle: (input) => `Grep(${input.pattern})`,
+    async execute(input, ctx) {
+        let root;
+        try {
+            root = resolvePath(ctx, input.path ?? ".");
+        }
+        catch (err) {
+            return toolError(String(err instanceof Error ? err.message : err));
+        }
+        const viaRipgrep = await runRipgrep(input, root, ctx);
+        if (viaRipgrep !== null)
+            return viaRipgrep;
+        return runJsGrep(input, root, ctx);
+    },
+});
+// ---------------------------------------------------------------------------
+function excludeFn(entry) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    return DEFAULT_IGNORES.some((pattern) => {
+        const dir = pattern.replace("**/", "").replace("/**", "");
+        return name === dir;
+    });
+}
+/** Returns null when ripgrep is unavailable, so the caller can fall back. */
+async function runRipgrep(input, root, ctx) {
+    const args = ["--line-number", "--no-heading", "--color", "never", "--max-count", "50"];
+    if (input.caseInsensitive)
+        args.push("-i");
+    if (input.filesOnly)
+        args.push("--files-with-matches");
+    if (input.contextLines)
+        args.push("-C", String(input.contextLines));
+    if (input.glob)
+        args.push("--glob", input.glob);
+    for (const ignore of DEFAULT_IGNORES)
+        args.push("--glob", `!${ignore}`);
+    args.push("--regexp", input.pattern, root);
+    const result = await execCapture("rg", args, ctx.signal);
+    if (result === null)
+        return null; // rg not installed
+    if (result.code === 1 && result.stdout.trim() === "") {
+        return toolText(`No matches for /${input.pattern}/`);
+    }
+    if (result.code > 1) {
+        return toolError(`grep failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+    return formatMatches(result.stdout, root, ctx, input.pattern);
+}
+async function runJsGrep(input, root, ctx) {
+    let regex;
+    try {
+        regex = new RegExp(input.pattern, input.caseInsensitive ? "i" : "");
+    }
+    catch (err) {
+        return toolError(`invalid regular expression: ${err instanceof Error ? err.message : err}`);
+    }
+    const info = await stat(root).catch(() => null);
+    if (!info)
+        return toolError(`path not found: ${root}`);
+    const files = [];
+    if (info.isFile()) {
+        files.push(root);
+    }
+    else {
+        const pattern = input.glob ?? "**/*";
+        for await (const entry of glob(pattern, { cwd: root, exclude: excludeFn })) {
+            const file = path.resolve(root, String(entry));
+            const entryInfo = await stat(file).catch(() => null);
+            if (entryInfo?.isFile())
+                files.push(file);
+            if (files.length > 5_000)
+                break;
+        }
+    }
+    const lines = [];
+    for (const file of files) {
+        if (ctx.signal.aborted)
+            break;
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch {
+            continue; // binary or unreadable
+        }
+        if (content.includes("\u0000"))
+            continue; // skip binary files
+        const fileLines = content.split("\n");
+        for (let i = 0; i < fileLines.length; i++) {
+            if (!regex.test(fileLines[i]))
+                continue;
+            if (input.filesOnly) {
+                lines.push(file);
+                break;
+            }
+            lines.push(`${file}:${i + 1}:${fileLines[i]}`);
+            if (lines.length >= MAX_RESULTS)
+                break;
+        }
+        if (lines.length >= MAX_RESULTS)
+            break;
+    }
+    if (lines.length === 0)
+        return toolText(`No matches for /${input.pattern}/`);
+    return formatMatches(lines.join("\n"), root, ctx, input.pattern);
+}
+function formatMatches(raw, root, ctx, pattern) {
+    void root;
+    const lines = raw.split("\n").filter((line) => line.trim() !== "");
+    const truncated = lines.length > MAX_RESULTS;
+    const shown = lines.slice(0, MAX_RESULTS).map((line) => relativize(line, ctx.cwd));
+    const footer = truncated
+        ? `\n\n… ${lines.length - MAX_RESULTS} more matches. Narrow the pattern or scope the search.`
+        : "";
+    return toolText(shown.join("\n") + footer, {
+        matches: lines.length,
+        truncated,
+        pattern,
+    });
+}
+function relativize(line, cwd) {
+    return line.startsWith(cwd + path.sep) ? line.slice(cwd.length + 1) : line;
+}
+/** Run a command, returning null when the binary does not exist. */
+function execCapture(command, args, signal) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, { signal });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(err.code === "ENOENT" ? null : { code: 127, stdout, stderr: String(err) });
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ code: code ?? 0, stdout, stderr });
+        });
+    });
+}
+export const searchTools = [globTool, grepTool];
+//# sourceMappingURL=search.js.map

package/dist/tools/builtin/search.js.map

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

package/dist/tools/builtin/skill.d.ts

@@ -0,0 +1,10 @@
+import type { SkillRegistry } from "../../agent/skills.ts";
+import type { Tool } from "../types.ts";
+/**
+ * Load a skill's full instructions on demand.
+ *
+ * Built against a live registry because the description has to name the skills
+ * that actually exist — a generic "load a skill" description gives the model
+ * nothing to match a task against, and it will never call the tool.
+ */
+export declare function createSkillTool(skills: SkillRegistry): Tool;

package/dist/tools/builtin/skill.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { renderSkill } from "../../agent/skills.js";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+/**
+ * Load a skill's full instructions on demand.
+ *
+ * Built against a live registry because the description has to name the skills
+ * that actually exist — a generic "load a skill" description gives the model
+ * nothing to match a task against, and it will never call the tool.
+ */
+export function createSkillTool(skills) {
+    const available = skills.list();
+    const names = available.map((skill) => skill.name);
+    return defineTool({
+        name: "skill",
+        readOnly: true,
+        description: "Load the full instructions for a skill listed in the system prompt. Call this " +
+            "before starting work that matches a skill's description — the description is a " +
+            "summary, not the instructions. " +
+            (names.length > 0
+                ? `Available: ${names.join(", ")}.`
+                : "No skills are currently installed."),
+        parameters: z.object({
+            name: z
+                .string()
+                .describe(names.length > 0
+                ? `Skill to load. One of: ${names.join(", ")}`
+                : "Skill name (none are installed)"),
+        }),
+        renderTitle: (input) => `Skill(${input.name})`,
+        async execute(input) {
+            const skill = skills.get(input.name);
+            if (!skill) {
+                return toolError(names.length === 0
+                    ? "No skills are installed. Add one at .oharness/skills/<name>/SKILL.md"
+                    : `No skill named "${input.name}". Available: ${names.join(", ")}`);
+            }
+            return toolText(await renderSkill(skill), {
+                skill: skill.name,
+                directory: skill.directory,
+            });
+        },
+    });
+}
+//# sourceMappingURL=skill.js.map

package/dist/tools/builtin/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../../src/tools/builtin/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEnD,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,IAAI;QACd,WAAW,EACT,gFAAgF;YAChF,iFAAiF;YACjF,iCAAiC;YACjC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBACf,CAAC,CAAC,cAAc,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACnC,CAAC,CAAC,oCAAoC,CAAC;QAC3C,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;YACnB,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,KAAK,CAAC,MAAM,GAAG,CAAC;gBACd,CAAC,CAAC,0BAA0B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC9C,CAAC,CAAC,iCAAiC,CACtC;SACJ,CAAC;QACF,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,KAAK,CAAC,IAAI,GAAG;QAE9C,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,SAAS,CACd,KAAK,CAAC,MAAM,KAAK,CAAC;oBAChB,CAAC,CAAC,sEAAsE;oBACxE,CAAC,CAAC,mBAAmB,KAAK,CAAC,IAAI,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrE,CAAC;YACJ,CAAC;YAED,OAAO,QAAQ,CAAC,MAAM,WAAW,CAAC,KAAK,CAAC,EAAE;gBACxC,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/builtin/task.d.ts

@@ -0,0 +1,9 @@
+import type { Tool, ToolHost } from "../types.ts";
+/**
+ * Spawns a subagent with its own context window and tool set.
+ *
+ * The description is built at registration time so the model sees the agent
+ * types that actually exist in this configuration, rather than a generic
+ * placeholder it has to guess against.
+ */
+export declare function createTaskTool(host: Pick<ToolHost, "listSubagentTypes">): Tool;