@dreb/coding-agent 1.16.0

package/dist/core/tools/search.js

@@ -0,0 +1,187 @@
+/**
+ * Semantic codebase search tool.
+ *
+ * Uses embeddings + FTS5 to support natural language queries over the codebase.
+ * Feature-gated on `node:sqlite` availability (Node 22+).
+ */
+import { Text } from "@dreb/tui";
+import { Type } from "@sinclair/typebox";
+import { SearchEngine } from "../search/search.js";
+import { shortenPath, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+// ============================================================================
+// Schema
+// ============================================================================
+const searchSchema = Type.Object({
+    query: Type.String({ description: "The search query (natural language, identifier, or path)" }),
+    path: Type.Optional(Type.String({ description: "Restrict search to files under this path (relative to cwd)" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of results to return (default: 20)" })),
+});
+// ============================================================================
+// Rendering
+// ============================================================================
+function formatSearchCall(args, theme) {
+    const query = str(args?.query);
+    const searchPath = str(args?.path);
+    let text = `${theme.fg("toolTitle", theme.bold("search"))} ${theme.fg("accent", `"${query ?? ""}"`)}`;
+    if (searchPath) {
+        text += theme.fg("toolOutput", ` in ${shortenPath(searchPath)}`);
+    }
+    if (args?.limit !== undefined) {
+        text += theme.fg("toolOutput", ` limit ${args.limit}`);
+    }
+    return text;
+}
+function formatSearchResult(result, options, theme) {
+    const output = result.content[0]?.text?.trim() ?? "";
+    if (!output)
+        return "";
+    const lines = output.split("\n");
+    const maxLines = options.expanded ? lines.length : 20;
+    const displayLines = lines.slice(0, maxLines);
+    const remaining = lines.length - maxLines;
+    let text = `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+    if (remaining > 0) {
+        text += `\n${theme.fg("muted", `... (${remaining} more lines)`)}`;
+    }
+    if (result.details?.indexStats) {
+        const { files, chunks } = result.details.indexStats;
+        text += `\n${theme.fg("muted", `[Index: ${files} files, ${chunks} chunks]`)}`;
+    }
+    return text;
+}
+// ============================================================================
+// Tool Definition
+// ============================================================================
+/** Check if the search tool is available (requires node:sqlite). */
+export function isSearchAvailable() {
+    return SearchEngine.isAvailable();
+}
+// Cache search engines per cwd to reuse index across calls within a session
+const engineCache = new Map();
+function getSearchEngine(cwd) {
+    let engine = engineCache.get(cwd);
+    if (!engine) {
+        engine = new SearchEngine(cwd);
+        engineCache.set(cwd, engine);
+    }
+    return engine;
+}
+export function createSearchToolDefinition(cwd) {
+    return {
+        name: "search",
+        label: "search",
+        description: "Search the codebase using natural language queries. Returns ranked code/doc results using semantic similarity and keyword matching. First query builds the index (may take a moment); subsequent queries are fast. Supports identifier queries (e.g. 'AuthMiddleware'), natural language (e.g. 'where is rate limiting handled'), and path queries (e.g. 'src/auth/').",
+        promptSnippet: "Semantic codebase search — natural language queries over code and docs",
+        promptGuidelines: [
+            'Use `search` for broad/conceptual queries ("where is auth handled", "rate limiting logic"). Use `grep` for exact text/regex matches.',
+            "The first search query builds an index (may take 10-60s). Subsequent queries are fast.",
+        ],
+        parameters: searchSchema,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            if (signal?.aborted)
+                throw new Error("Operation aborted");
+            if (!isSearchAvailable()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Semantic search requires Node.js 22+ (for built-in SQLite). Current Node.js version does not support node:sqlite.",
+                        },
+                    ],
+                    details: { resultCount: 0, indexBuilt: false },
+                };
+            }
+            const { query, path: searchPath, limit } = params;
+            if (!query || query.trim().length === 0) {
+                return {
+                    content: [{ type: "text", text: "Search query cannot be empty." }],
+                    details: { resultCount: 0, indexBuilt: false },
+                };
+            }
+            const engine = getSearchEngine(cwd);
+            let indexBuilt = false;
+            const results = await engine.search(query, {
+                limit: limit ?? 20,
+                pathFilter: searchPath,
+                onProgress: (phase, current, total) => {
+                    if (phase === "indexing" || phase === "scanning" || phase === "loading model" || phase === "embedding") {
+                        indexBuilt = true;
+                    }
+                    if (onUpdate) {
+                        onUpdate({
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `${phase}: ${current}/${total}`,
+                                },
+                            ],
+                            details: { resultCount: 0, indexBuilt: true },
+                        });
+                    }
+                },
+            });
+            if (results.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No results found." }],
+                    details: { resultCount: 0, indexBuilt },
+                };
+            }
+            // Format results
+            const lines = [];
+            for (let i = 0; i < results.length; i++) {
+                const r = results[i];
+                const { chunk, scores } = r;
+                // Header line with file path and line range
+                const lineRange = chunk.startLine === chunk.endLine ? `L${chunk.startLine}` : `L${chunk.startLine}-${chunk.endLine}`;
+                const kindLabel = chunk.name ? `${chunk.kind} ${chunk.name}` : chunk.kind;
+                lines.push(`${i + 1}. ${chunk.filePath}:${lineRange} (${kindLabel})`);
+                // Score summary — show top contributing metrics
+                const topScores = Object.entries(scores)
+                    .filter(([, v]) => v > 0.01)
+                    .sort(([, a], [, b]) => b - a)
+                    .map(([k, v]) => `${k}=${v.toFixed(2)}`)
+                    .join(" ");
+                if (topScores) {
+                    lines.push(`   scores: ${topScores}`);
+                }
+                // Content preview (first 3 lines)
+                const contentLines = chunk.content.split("\n");
+                const previewLines = contentLines.slice(0, 3);
+                for (const line of previewLines) {
+                    const trimmed = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+                    lines.push(`   ${trimmed}`);
+                }
+                if (contentLines.length > 3) {
+                    lines.push(`   ... (${contentLines.length - 3} more lines)`);
+                }
+                if (i < results.length - 1)
+                    lines.push("");
+            }
+            // Get index stats from the existing engine (no new connection)
+            const stats = engine.getStats();
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                details: {
+                    resultCount: results.length,
+                    indexBuilt,
+                    indexStats: stats ?? undefined,
+                },
+            };
+        },
+        renderCall(args, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            text.setText(formatSearchCall(args, theme));
+            return text;
+        },
+        renderResult(result, options, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            text.setText(formatSearchResult(result, options, theme));
+            return text;
+        },
+    };
+}
+export function createSearchTool(cwd) {
+    return wrapToolDefinition(createSearchToolDefinition(cwd));
+}
+//# sourceMappingURL=search.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/core/tools/search.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Semantic codebase search tool.\n *\n * Uses embeddings + FTS5 to support natural language queries over the codebase.\n * Feature-gated on `node:sqlite` availability (Node 22+).\n */\n\nimport type { AgentTool } from \"@dreb/agent-core\";\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.js\";\nimport { SearchEngine } from \"../search/search.js\";\nimport { shortenPath, str } from \"./render-utils.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nconst searchSchema = Type.Object({\n\tquery: Type.String({ description: \"The search query (natural language, identifier, or path)\" }),\n\tpath: Type.Optional(Type.String({ description: \"Restrict search to files under this path (relative to cwd)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of results to return (default: 20)\" })),\n});\n\nexport type SearchToolInput = Static<typeof searchSchema>;\n\n// ============================================================================\n// Details\n// ============================================================================\n\nexport interface SearchToolDetails {\n\tresultCount: number;\n\tindexBuilt: boolean;\n\tindexStats?: { files: number; chunks: number };\n}\n\n// ============================================================================\n// Rendering\n// ============================================================================\n\nfunction formatSearchCall(\n\targs: { query?: string; path?: string; limit?: number } | undefined,\n\ttheme: typeof import(\"../../modes/interactive/theme/theme.js\").theme,\n): string {\n\tconst query = str(args?.query);\n\tconst searchPath = str(args?.path);\n\tlet text = `${theme.fg(\"toolTitle\", theme.bold(\"search\"))} ${theme.fg(\"accent\", `\"${query ?? \"\"}\"`)}`;\n\tif (searchPath) {\n\t\ttext += theme.fg(\"toolOutput\", ` in ${shortenPath(searchPath)}`);\n\t}\n\tif (args?.limit !== undefined) {\n\t\ttext += theme.fg(\"toolOutput\", ` limit ${args.limit}`);\n\t}\n\treturn text;\n}\n\nfunction formatSearchResult(\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string }>;\n\t\tdetails?: SearchToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\ttheme: typeof import(\"../../modes/interactive/theme/theme.js\").theme,\n): string {\n\tconst output = result.content[0]?.text?.trim() ?? \"\";\n\tif (!output) return \"\";\n\n\tconst lines = output.split(\"\\n\");\n\tconst maxLines = options.expanded ? lines.length : 20;\n\tconst displayLines = lines.slice(0, maxLines);\n\tconst remaining = lines.length - maxLines;\n\n\tlet text = `\\n${displayLines.map((line) => theme.fg(\"toolOutput\", line)).join(\"\\n\")}`;\n\tif (remaining > 0) {\n\t\ttext += `\\n${theme.fg(\"muted\", `... (${remaining} more lines)`)}`;\n\t}\n\n\tif (result.details?.indexStats) {\n\t\tconst { files, chunks } = result.details.indexStats;\n\t\ttext += `\\n${theme.fg(\"muted\", `[Index: ${files} files, ${chunks} chunks]`)}`;\n\t}\n\n\treturn text;\n}\n\n// ============================================================================\n// Tool Definition\n// ============================================================================\n\n/** Check if the search tool is available (requires node:sqlite). */\nexport function isSearchAvailable(): boolean {\n\treturn SearchEngine.isAvailable();\n}\n\n// Cache search engines per cwd to reuse index across calls within a session\nconst engineCache = new Map<string, SearchEngine>();\n\nfunction getSearchEngine(cwd: string): SearchEngine {\n\tlet engine = engineCache.get(cwd);\n\tif (!engine) {\n\t\tengine = new SearchEngine(cwd);\n\t\tengineCache.set(cwd, engine);\n\t}\n\treturn engine;\n}\n\nexport function createSearchToolDefinition(cwd: string): ToolDefinition<typeof searchSchema, SearchToolDetails> {\n\treturn {\n\t\tname: \"search\",\n\t\tlabel: \"search\",\n\t\tdescription:\n\t\t\t\"Search the codebase using natural language queries. Returns ranked code/doc results using semantic similarity and keyword matching. First query builds the index (may take a moment); subsequent queries are fast. Supports identifier queries (e.g. 'AuthMiddleware'), natural language (e.g. 'where is rate limiting handled'), and path queries (e.g. 'src/auth/').\",\n\t\tpromptSnippet: \"Semantic codebase search — natural language queries over code and docs\",\n\t\tpromptGuidelines: [\n\t\t\t'Use `search` for broad/conceptual queries (\"where is auth handled\", \"rate limiting logic\"). Use `grep` for exact text/regex matches.',\n\t\t\t\"The first search query builds an index (may take 10-60s). Subsequent queries are fast.\",\n\t\t],\n\t\tparameters: searchSchema,\n\n\t\tasync execute(_toolCallId, params, signal, onUpdate, _ctx) {\n\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\n\t\t\tif (!isSearchAvailable()) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\t\ttext: \"Semantic search requires Node.js 22+ (for built-in SQLite). Current Node.js version does not support node:sqlite.\",\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { resultCount: 0, indexBuilt: false },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst { query, path: searchPath, limit } = params;\n\n\t\t\tif (!query || query.trim().length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: \"Search query cannot be empty.\" }],\n\t\t\t\t\tdetails: { resultCount: 0, indexBuilt: false },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst engine = getSearchEngine(cwd);\n\n\t\t\tlet indexBuilt = false;\n\t\t\tconst results = await engine.search(query, {\n\t\t\t\tlimit: limit ?? 20,\n\t\t\t\tpathFilter: searchPath,\n\t\t\t\tonProgress: (phase, current, total) => {\n\t\t\t\t\tif (phase === \"indexing\" || phase === \"scanning\" || phase === \"loading model\" || phase === \"embedding\") {\n\t\t\t\t\t\tindexBuilt = true;\n\t\t\t\t\t}\n\t\t\t\t\tif (onUpdate) {\n\t\t\t\t\t\tonUpdate({\n\t\t\t\t\t\t\tcontent: [\n\t\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\t\t\t\ttext: `${phase}: ${current}/${total}`,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\tdetails: { resultCount: 0, indexBuilt: true } as SearchToolDetails,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t});\n\n\t\t\tif (results.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: \"No results found.\" }],\n\t\t\t\t\tdetails: { resultCount: 0, indexBuilt },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\t// Format results\n\t\t\tconst lines: string[] = [];\n\t\t\tfor (let i = 0; i < results.length; i++) {\n\t\t\t\tconst r = results[i];\n\t\t\t\tconst { chunk, scores } = r;\n\n\t\t\t\t// Header line with file path and line range\n\t\t\t\tconst lineRange =\n\t\t\t\t\tchunk.startLine === chunk.endLine ? `L${chunk.startLine}` : `L${chunk.startLine}-${chunk.endLine}`;\n\t\t\t\tconst kindLabel = chunk.name ? `${chunk.kind} ${chunk.name}` : chunk.kind;\n\n\t\t\t\tlines.push(`${i + 1}. ${chunk.filePath}:${lineRange} (${kindLabel})`);\n\n\t\t\t\t// Score summary — show top contributing metrics\n\t\t\t\tconst topScores = Object.entries(scores)\n\t\t\t\t\t.filter(([, v]) => v > 0.01)\n\t\t\t\t\t.sort(([, a], [, b]) => b - a)\n\t\t\t\t\t.map(([k, v]) => `${k}=${v.toFixed(2)}`)\n\t\t\t\t\t.join(\" \");\n\t\t\t\tif (topScores) {\n\t\t\t\t\tlines.push(`   scores: ${topScores}`);\n\t\t\t\t}\n\n\t\t\t\t// Content preview (first 3 lines)\n\t\t\t\tconst contentLines = chunk.content.split(\"\\n\");\n\t\t\t\tconst previewLines = contentLines.slice(0, 3);\n\t\t\t\tfor (const line of previewLines) {\n\t\t\t\t\tconst trimmed = line.length > 120 ? `${line.slice(0, 117)}...` : line;\n\t\t\t\t\tlines.push(`   ${trimmed}`);\n\t\t\t\t}\n\t\t\t\tif (contentLines.length > 3) {\n\t\t\t\t\tlines.push(`   ... (${contentLines.length - 3} more lines)`);\n\t\t\t\t}\n\n\t\t\t\tif (i < results.length - 1) lines.push(\"\");\n\t\t\t}\n\n\t\t\t// Get index stats from the existing engine (no new connection)\n\t\t\tconst stats = engine.getStats();\n\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: lines.join(\"\\n\") }],\n\t\t\t\tdetails: {\n\t\t\t\t\tresultCount: results.length,\n\t\t\t\t\tindexBuilt,\n\t\t\t\t\tindexStats: stats ?? undefined,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatSearchCall(args, theme));\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatSearchResult(result as any, options, theme));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createSearchTool(cwd: string): AgentTool<typeof searchSchema> {\n\treturn wrapToolDefinition(createSearchToolDefinition(cwd));\n}\n"]}

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

@@ -0,0 +1,26 @@
+import type { AgentTool } from "@dreb/agent-core";
+import { type Static } from "@sinclair/typebox";
+import type { ToolDefinition } from "../extensions/types.js";
+import type { Skill } from "../skills.js";
+declare const skillSchema: import("@sinclair/typebox").TObject<{
+    skill: import("@sinclair/typebox").TString;
+    args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type SkillToolInput = Static<typeof skillSchema>;
+export interface SkillToolDetails {
+    skillName: string;
+    found: boolean;
+    warned: boolean;
+    error?: string;
+}
+export interface SkillToolOptions {
+    /** Returns the current list of loaded skills. Called on each invocation so reloads are reflected. */
+    getSkills: () => Skill[];
+    /** Returns the current session ID for ${DREB_SESSION_ID} substitution. Called on each invocation so session rotations are reflected. */
+    getSessionId: () => string;
+}
+export declare function expandSkillContent(skill: Skill, args: string, sessionId: string): string;
+export declare function createSkillToolDefinition(_cwd: string, options: SkillToolOptions): ToolDefinition<typeof skillSchema, SkillToolDetails>;
+export declare function createSkillTool(cwd: string, options: SkillToolOptions): AgentTool<typeof skillSchema>;
+export {};
+//# sourceMappingURL=skill.d.ts.map

package/dist/core/tools/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/core/tools/skill.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAQ1C,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,WAAW,gBAAgB;IAChC,qGAAqG;IACrG,SAAS,EAAE,MAAM,KAAK,EAAE,CAAC;IACzB,wIAAwI;IACxI,YAAY,EAAE,MAAM,MAAM,CAAC;CAC3B;AAMD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBxF;AAMD,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACvB,cAAc,CAAC,OAAO,WAAW,EAAE,gBAAgB,CAAC,CA8FtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAErG","sourcesContent":["import { readFileSync } from \"node:fs\";\nimport type { AgentTool } from \"@dreb/agent-core\";\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport { stripFrontmatter } from \"../../utils/frontmatter.js\";\nimport { escapeXml } from \"../../utils/xml.js\";\nimport type { ToolDefinition } from \"../extensions/types.js\";\nimport { parseCommandArgs, substituteArgs } from \"../prompt-templates.js\";\nimport type { Skill } from \"../skills.js\";\nimport { getTextOutput } from \"./render-utils.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\n// ---------------------------------------------------------------------------\n// Schema\n// ---------------------------------------------------------------------------\n\nconst skillSchema = Type.Object({\n\tskill: Type.String({ description: 'The skill name to invoke (e.g. \"review-pr\", \"telegram-send\")' }),\n\targs: Type.Optional(Type.String({ description: \"Optional arguments to pass to the skill\" })),\n});\n\nexport type SkillToolInput = Static<typeof skillSchema>;\n\nexport interface SkillToolDetails {\n\tskillName: string;\n\tfound: boolean;\n\twarned: boolean;\n\terror?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface SkillToolOptions {\n\t/** Returns the current list of loaded skills. Called on each invocation so reloads are reflected. */\n\tgetSkills: () => Skill[];\n\t/** Returns the current session ID for ${DREB_SESSION_ID} substitution. Called on each invocation so session rotations are reflected. */\n\tgetSessionId: () => string;\n}\n\n// ---------------------------------------------------------------------------\n// Skill expansion — shared between skill tool and _expandSkillCommand\n// ---------------------------------------------------------------------------\n\nexport function expandSkillContent(skill: Skill, args: string, sessionId: string): string {\n\tconst content = readFileSync(skill.filePath, \"utf-8\");\n\tlet body = stripFrontmatter(content).trim();\n\n\tconst parsedArgs = parseCommandArgs(args);\n\t// $0 is an alias for first argument (per spec). Replace BEFORE substituteArgs\n\t// so that argument values containing \"$0\" aren't re-substituted.\n\t// Negative lookahead avoids matching $00, $01, etc.\n\tbody = body.replace(/\\$0(?![0-9])/g, parsedArgs[0] ?? \"\");\n\tbody = substituteArgs(body, parsedArgs);\n\t// Environment-style placeholders\n\tbody = body.replace(/\\$\\{DREB_SKILL_DIR\\}/g, skill.baseDir);\n\tbody = body.replace(/\\$\\{DREB_SESSION_ID\\}/g, sessionId);\n\n\tconst skillBlock = `<skill name=\"${escapeXml(skill.name)}\" location=\"${escapeXml(skill.filePath)}\">\\nReferences are relative to ${skill.baseDir}.\\n\\n${body}\\n</skill>`;\n\treturn skillBlock;\n}\n\n// ---------------------------------------------------------------------------\n// Tool definition\n// ---------------------------------------------------------------------------\n\nexport function createSkillToolDefinition(\n\t_cwd: string,\n\toptions: SkillToolOptions,\n): ToolDefinition<typeof skillSchema, SkillToolDetails> {\n\tconst { getSkills, getSessionId } = options;\n\n\treturn {\n\t\tname: \"skill\",\n\t\tlabel: \"skill\",\n\t\tdescription:\n\t\t\t\"Invoke a skill by name. Skills provide specialized instructions for specific tasks. \" +\n\t\t\t\"Use this tool when a task matches a skill's description from the available_skills list in the system prompt.\",\n\t\tpromptSnippet: \"Invoke a skill to get specialized instructions for a task\",\n\t\tparameters: skillSchema,\n\n\t\tasync execute(_toolCallId, params: { skill: string; args?: string }) {\n\t\t\tconst skills = getSkills();\n\t\t\tconst skill = skills.find((s) => s.name === params.skill);\n\n\t\t\tif (!skill) {\n\t\t\t\tconst available = skills\n\t\t\t\t\t.filter((s) => !s.disableModelInvocation)\n\t\t\t\t\t.map((s) => `  - ${s.name}: ${s.description}`)\n\t\t\t\t\t.join(\"\\n\");\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `Unknown skill \"${params.skill}\". Available skills:\\n${available || \"  (none loaded)\"}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: params.skill, found: false, warned: false },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (skill.disableModelInvocation) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext:\n\t\t\t\t\t\t\t\t`The skill \"${skill.name}\" has model invocation disabled. ` +\n\t\t\t\t\t\t\t\t`This skill is intended to be invoked explicitly by the user (via /skill:${skill.name}), not by the model. ` +\n\t\t\t\t\t\t\t\t`Please ask the user for clarification before proceeding.`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: true },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tconst expanded = expandSkillContent(skill, params.args ?? \"\", getSessionId());\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\" as const, text: expanded }],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: false },\n\t\t\t\t};\n\t\t\t} catch (err) {\n\t\t\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `Error loading skill \"${skill.name}\": ${message}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: false, error: message },\n\t\t\t\t};\n\t\t\t}\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst skillName = args?.skill ?? \"...\";\n\t\t\tconst argsStr = args?.args ? ` ${theme.fg(\"accent\", args.args)}` : \"\";\n\t\t\ttext.setText(`${theme.fg(\"toolTitle\", theme.bold(\"skill\"))} ${theme.fg(\"accent\", skillName)}${argsStr}`);\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst output = getTextOutput(result, context.showImages).trim();\n\t\t\tif (!output) {\n\t\t\t\ttext.setText(\"\");\n\t\t\t\treturn text;\n\t\t\t}\n\t\t\tconst lines = output.split(\"\\n\");\n\t\t\tconst maxLines = options.expanded ? lines.length : 15;\n\t\t\tconst displayLines = lines.slice(0, maxLines);\n\t\t\tlet display = `\\n${displayLines.map((line) => theme.fg(\"toolOutput\", line)).join(\"\\n\")}`;\n\t\t\tconst remaining = lines.length - maxLines;\n\t\t\tif (remaining > 0) {\n\t\t\t\tdisplay += `\\n${theme.fg(\"muted\", `... (${remaining} more lines)`)}`;\n\t\t\t}\n\t\t\ttext.setText(display);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createSkillTool(cwd: string, options: SkillToolOptions): AgentTool<typeof skillSchema> {\n\treturn wrapToolDefinition(createSkillToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/skill.js

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { Text } from "@dreb/tui";
+import { Type } from "@sinclair/typebox";
+import { stripFrontmatter } from "../../utils/frontmatter.js";
+import { escapeXml } from "../../utils/xml.js";
+import { parseCommandArgs, substituteArgs } from "../prompt-templates.js";
+import { getTextOutput } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const skillSchema = Type.Object({
+    skill: Type.String({ description: 'The skill name to invoke (e.g. "review-pr", "telegram-send")' }),
+    args: Type.Optional(Type.String({ description: "Optional arguments to pass to the skill" })),
+});
+// ---------------------------------------------------------------------------
+// Skill expansion — shared between skill tool and _expandSkillCommand
+// ---------------------------------------------------------------------------
+export function expandSkillContent(skill, args, sessionId) {
+    const content = readFileSync(skill.filePath, "utf-8");
+    let body = stripFrontmatter(content).trim();
+    const parsedArgs = parseCommandArgs(args);
+    // $0 is an alias for first argument (per spec). Replace BEFORE substituteArgs
+    // so that argument values containing "$0" aren't re-substituted.
+    // Negative lookahead avoids matching $00, $01, etc.
+    body = body.replace(/\$0(?![0-9])/g, parsedArgs[0] ?? "");
+    body = substituteArgs(body, parsedArgs);
+    // Environment-style placeholders
+    body = body.replace(/\$\{DREB_SKILL_DIR\}/g, skill.baseDir);
+    body = body.replace(/\$\{DREB_SESSION_ID\}/g, sessionId);
+    const skillBlock = `<skill name="${escapeXml(skill.name)}" location="${escapeXml(skill.filePath)}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+    return skillBlock;
+}
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+export function createSkillToolDefinition(_cwd, options) {
+    const { getSkills, getSessionId } = options;
+    return {
+        name: "skill",
+        label: "skill",
+        description: "Invoke a skill by name. Skills provide specialized instructions for specific tasks. " +
+            "Use this tool when a task matches a skill's description from the available_skills list in the system prompt.",
+        promptSnippet: "Invoke a skill to get specialized instructions for a task",
+        parameters: skillSchema,
+        async execute(_toolCallId, params) {
+            const skills = getSkills();
+            const skill = skills.find((s) => s.name === params.skill);
+            if (!skill) {
+                const available = skills
+                    .filter((s) => !s.disableModelInvocation)
+                    .map((s) => `  - ${s.name}: ${s.description}`)
+                    .join("\n");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown skill "${params.skill}". Available skills:\n${available || "  (none loaded)"}`,
+                        },
+                    ],
+                    details: { skillName: params.skill, found: false, warned: false },
+                };
+            }
+            if (skill.disableModelInvocation) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `The skill "${skill.name}" has model invocation disabled. ` +
+                                `This skill is intended to be invoked explicitly by the user (via /skill:${skill.name}), not by the model. ` +
+                                `Please ask the user for clarification before proceeding.`,
+                        },
+                    ],
+                    details: { skillName: skill.name, found: true, warned: true },
+                };
+            }
+            try {
+                const expanded = expandSkillContent(skill, params.args ?? "", getSessionId());
+                return {
+                    content: [{ type: "text", text: expanded }],
+                    details: { skillName: skill.name, found: true, warned: false },
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error loading skill "${skill.name}": ${message}`,
+                        },
+                    ],
+                    details: { skillName: skill.name, found: true, warned: false, error: message },
+                };
+            }
+        },
+        renderCall(args, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            const skillName = args?.skill ?? "...";
+            const argsStr = args?.args ? ` ${theme.fg("accent", args.args)}` : "";
+            text.setText(`${theme.fg("toolTitle", theme.bold("skill"))} ${theme.fg("accent", skillName)}${argsStr}`);
+            return text;
+        },
+        renderResult(result, options, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            const output = getTextOutput(result, context.showImages).trim();
+            if (!output) {
+                text.setText("");
+                return text;
+            }
+            const lines = output.split("\n");
+            const maxLines = options.expanded ? lines.length : 15;
+            const displayLines = lines.slice(0, maxLines);
+            let display = `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+            const remaining = lines.length - maxLines;
+            if (remaining > 0) {
+                display += `\n${theme.fg("muted", `... (${remaining} more lines)`)}`;
+            }
+            text.setText(display);
+            return text;
+        },
+    };
+}
+export function createSkillTool(cwd, options) {
+    return wrapToolDefinition(createSkillToolDefinition(cwd, options));
+}
+//# sourceMappingURL=skill.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../../src/core/tools/skill.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync } from \"node:fs\";\nimport type { AgentTool } from \"@dreb/agent-core\";\nimport { Text } from \"@dreb/tui\";\nimport { type Static, Type } from \"@sinclair/typebox\";\nimport { stripFrontmatter } from \"../../utils/frontmatter.js\";\nimport { escapeXml } from \"../../utils/xml.js\";\nimport type { ToolDefinition } from \"../extensions/types.js\";\nimport { parseCommandArgs, substituteArgs } from \"../prompt-templates.js\";\nimport type { Skill } from \"../skills.js\";\nimport { getTextOutput } from \"./render-utils.js\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.js\";\n\n// ---------------------------------------------------------------------------\n// Schema\n// ---------------------------------------------------------------------------\n\nconst skillSchema = Type.Object({\n\tskill: Type.String({ description: 'The skill name to invoke (e.g. \"review-pr\", \"telegram-send\")' }),\n\targs: Type.Optional(Type.String({ description: \"Optional arguments to pass to the skill\" })),\n});\n\nexport type SkillToolInput = Static<typeof skillSchema>;\n\nexport interface SkillToolDetails {\n\tskillName: string;\n\tfound: boolean;\n\twarned: boolean;\n\terror?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface SkillToolOptions {\n\t/** Returns the current list of loaded skills. Called on each invocation so reloads are reflected. */\n\tgetSkills: () => Skill[];\n\t/** Returns the current session ID for ${DREB_SESSION_ID} substitution. Called on each invocation so session rotations are reflected. */\n\tgetSessionId: () => string;\n}\n\n// ---------------------------------------------------------------------------\n// Skill expansion — shared between skill tool and _expandSkillCommand\n// ---------------------------------------------------------------------------\n\nexport function expandSkillContent(skill: Skill, args: string, sessionId: string): string {\n\tconst content = readFileSync(skill.filePath, \"utf-8\");\n\tlet body = stripFrontmatter(content).trim();\n\n\tconst parsedArgs = parseCommandArgs(args);\n\t// $0 is an alias for first argument (per spec). Replace BEFORE substituteArgs\n\t// so that argument values containing \"$0\" aren't re-substituted.\n\t// Negative lookahead avoids matching $00, $01, etc.\n\tbody = body.replace(/\\$0(?![0-9])/g, parsedArgs[0] ?? \"\");\n\tbody = substituteArgs(body, parsedArgs);\n\t// Environment-style placeholders\n\tbody = body.replace(/\\$\\{DREB_SKILL_DIR\\}/g, skill.baseDir);\n\tbody = body.replace(/\\$\\{DREB_SESSION_ID\\}/g, sessionId);\n\n\tconst skillBlock = `<skill name=\"${escapeXml(skill.name)}\" location=\"${escapeXml(skill.filePath)}\">\\nReferences are relative to ${skill.baseDir}.\\n\\n${body}\\n</skill>`;\n\treturn skillBlock;\n}\n\n// ---------------------------------------------------------------------------\n// Tool definition\n// ---------------------------------------------------------------------------\n\nexport function createSkillToolDefinition(\n\t_cwd: string,\n\toptions: SkillToolOptions,\n): ToolDefinition<typeof skillSchema, SkillToolDetails> {\n\tconst { getSkills, getSessionId } = options;\n\n\treturn {\n\t\tname: \"skill\",\n\t\tlabel: \"skill\",\n\t\tdescription:\n\t\t\t\"Invoke a skill by name. Skills provide specialized instructions for specific tasks. \" +\n\t\t\t\"Use this tool when a task matches a skill's description from the available_skills list in the system prompt.\",\n\t\tpromptSnippet: \"Invoke a skill to get specialized instructions for a task\",\n\t\tparameters: skillSchema,\n\n\t\tasync execute(_toolCallId, params: { skill: string; args?: string }) {\n\t\t\tconst skills = getSkills();\n\t\t\tconst skill = skills.find((s) => s.name === params.skill);\n\n\t\t\tif (!skill) {\n\t\t\t\tconst available = skills\n\t\t\t\t\t.filter((s) => !s.disableModelInvocation)\n\t\t\t\t\t.map((s) => `  - ${s.name}: ${s.description}`)\n\t\t\t\t\t.join(\"\\n\");\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `Unknown skill \"${params.skill}\". Available skills:\\n${available || \"  (none loaded)\"}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: params.skill, found: false, warned: false },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tif (skill.disableModelInvocation) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext:\n\t\t\t\t\t\t\t\t`The skill \"${skill.name}\" has model invocation disabled. ` +\n\t\t\t\t\t\t\t\t`This skill is intended to be invoked explicitly by the user (via /skill:${skill.name}), not by the model. ` +\n\t\t\t\t\t\t\t\t`Please ask the user for clarification before proceeding.`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: true },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tconst expanded = expandSkillContent(skill, params.args ?? \"\", getSessionId());\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\" as const, text: expanded }],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: false },\n\t\t\t\t};\n\t\t\t} catch (err) {\n\t\t\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `Error loading skill \"${skill.name}\": ${message}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: { skillName: skill.name, found: true, warned: false, error: message },\n\t\t\t\t};\n\t\t\t}\n\t\t},\n\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst skillName = args?.skill ?? \"...\";\n\t\t\tconst argsStr = args?.args ? ` ${theme.fg(\"accent\", args.args)}` : \"\";\n\t\t\ttext.setText(`${theme.fg(\"toolTitle\", theme.bold(\"skill\"))} ${theme.fg(\"accent\", skillName)}${argsStr}`);\n\t\t\treturn text;\n\t\t},\n\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst output = getTextOutput(result, context.showImages).trim();\n\t\t\tif (!output) {\n\t\t\t\ttext.setText(\"\");\n\t\t\t\treturn text;\n\t\t\t}\n\t\t\tconst lines = output.split(\"\\n\");\n\t\t\tconst maxLines = options.expanded ? lines.length : 15;\n\t\t\tconst displayLines = lines.slice(0, maxLines);\n\t\t\tlet display = `\\n${displayLines.map((line) => theme.fg(\"toolOutput\", line)).join(\"\\n\")}`;\n\t\t\tconst remaining = lines.length - maxLines;\n\t\t\tif (remaining > 0) {\n\t\t\t\tdisplay += `\\n${theme.fg(\"muted\", `... (${remaining} more lines)`)}`;\n\t\t\t}\n\t\t\ttext.setText(display);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createSkillTool(cwd: string, options: SkillToolOptions): AgentTool<typeof skillSchema> {\n\treturn wrapToolDefinition(createSkillToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/subagent.d.ts

@@ -0,0 +1,147 @@
+import type { AgentTool } from "@dreb/agent-core";
+import { type Static } from "@sinclair/typebox";
+import type { ToolDefinition } from "../extensions/types.js";
+import type { ModelRegistry } from "../model-registry.js";
+import { type TruncationResult } from "./truncate.js";
+interface AgentTypeConfig {
+    name: string;
+    description: string;
+    tools?: string;
+    /** Single model ID or ordered fallback list. First resolvable model wins. */
+    model?: string | string[];
+    systemPrompt: string;
+}
+export declare function parseAgentFrontmatter(content: string): {
+    ok: true;
+    config: AgentTypeConfig;
+} | {
+    ok: false;
+    error: string;
+};
+export interface SubagentResult {
+    agent: string;
+    task: string;
+    model?: string;
+    exitCode: number;
+    output: string;
+    stderr: string;
+    errorMessage: string | null;
+    /** Path to the persisted session JSONL file, if available */
+    sessionFile?: string;
+}
+/**
+ * Find the most recently modified .jsonl file in a session directory.
+ * Returns the full path, or undefined if no session file was written
+ * (e.g., subagent was killed before the first assistant message).
+ */
+export declare function discoverSessionFile(sessionDir: string, agentName: string): string | undefined;
+/**
+ * Resolve a model fallback list against the registry. Tries each model in order,
+ * returns the first one that resolves successfully. If all fail, returns the
+ * last error. Single strings are treated as a one-element list.
+ */
+export declare function resolveModelWithFallbacks(models: string | string[], parentProvider: string | undefined, registry: ModelRegistry | undefined): {
+    ok: true;
+    modelId: string;
+    provider?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveModelStringSingle(modelStr: string, parentProvider: string | undefined, registry: ModelRegistry | undefined): {
+    ok: true;
+    modelId: string;
+    provider?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface BackgroundAgentInfo {
+    agentId: string;
+    agentType: string;
+    taskSummary: string;
+    startedAt: number;
+    status: "running" | "completed" | "failed";
+}
+/** Get a snapshot of all tracked background agents (running and recently completed). Returns readonly clones. */
+export declare function getBackgroundAgents(): readonly Readonly<BackgroundAgentInfo>[];
+/** Get only currently running background agents. Returns readonly clones. */
+export declare function getRunningBackgroundAgents(): readonly Readonly<BackgroundAgentInfo>[];
+/** Abort all running background agents. */
+export declare function abortBackgroundAgents(): void;
+/** Remove completed/failed entries older than the given age (ms). Default: 5 minutes. */
+export declare function pruneBackgroundAgents(maxAgeMs?: number): void;
+export interface SubagentToolOptions {
+    /** Called when a background subagent starts. Used by TUI to show status indicators. */
+    onBackgroundStart?: (agentId: string, agentType: string, taskSummary: string) => void;
+    /** Called when a background subagent completes with its result. `cancelled` is true if the user aborted it. */
+    onBackgroundComplete?: (agentId: string, result: SubagentResult, cancelled: boolean) => void;
+    /** Parent session's current provider (e.g. "anthropic"). Called at each invocation to get the live value after mid-session model switches. */
+    parentProvider?: () => string | undefined;
+    /** Model registry for validating model names before spawning child processes. */
+    modelRegistry?: ModelRegistry;
+}
+declare const subagentSchema: import("@sinclair/typebox").TObject<{
+    agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    task: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    tasks: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    chain: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type SubagentToolInput = Static<typeof subagentSchema>;
+export interface SubagentToolDetails {
+    truncation?: TruncationResult;
+    mode: "single" | "parallel" | "chain";
+    agentCount: number;
+}
+export declare function createSubagentToolDefinition(cwd: string, options?: SubagentToolOptions): ToolDefinition<typeof subagentSchema, SubagentToolDetails | undefined>;
+export declare function createSubagentTool(cwd: string, options?: SubagentToolOptions): AgentTool<typeof subagentSchema>;
+export declare const subagentToolDefinition: ToolDefinition<import("@sinclair/typebox").TObject<{
+    agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    task: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    tasks: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    chain: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>, SubagentToolDetails | undefined, any>;
+export declare const subagentTool: AgentTool<import("@sinclair/typebox").TObject<{
+    agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    task: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    tasks: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    chain: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        agent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        task: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
+    background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>, any>;
+export {};
+//# sourceMappingURL=subagent.d.ts.map