@namzu/sdk 27.0.0 → 28.0.0

package/dist/tools/builtins/index.d.ts

@@ -3,7 +3,13 @@ export { WriteFileTool } from './write-file.js';
 export { EditTool } from './edit.js';
 export { BashTool } from './bash.js';
 export { GlobTool } from './glob.js';
+export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './lsp.js';
 export { GrepTool } from './grep.js';
+export { JobTool } from './job.js';
+export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './skill.js';
+export { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchTool, WebSearchTool, } from './web.js';
+export { WEB_GUIDANCE_CONTRIBUTION_ID, webGuidanceContribution } from './web-guidance.js';
+export { RUN_CODE_TOOL_NAME, buildRunCodeTool } from './run-code.js';
 export { LsTool } from './ls.js';
 export { SearchToolsTool } from './search-tools.js';
 export { VerifyOutputsTool } from './verify-outputs.js';

package/dist/tools/builtins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAoB/D,wBAAgB,eAAe,IAAI,cAAc,EAAE,CAElD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC1E,OAAO,EACN,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AACzF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAqB/D,wBAAgB,eAAe,IAAI,cAAc,EAAE,CAkBlD"}

package/dist/tools/builtins/index.js

@@ -3,7 +3,13 @@ export { WriteFileTool } from './write-file.js';
 export { EditTool } from './edit.js';
 export { BashTool } from './bash.js';
 export { GlobTool } from './glob.js';
+export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './lsp.js';
 export { GrepTool } from './grep.js';
+export { JobTool } from './job.js';
+export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './skill.js';
+export { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME, WebFetchTool, WebSearchTool, } from './web.js';
+export { WEB_GUIDANCE_CONTRIBUTION_ID, webGuidanceContribution } from './web-guidance.js';
+export { RUN_CODE_TOOL_NAME, buildRunCodeTool } from './run-code.js';
 export { LsTool } from './ls.js';
 export { SearchToolsTool } from './search-tools.js';
 export { VerifyOutputsTool } from './verify-outputs.js';
@@ -13,6 +19,7 @@ import { BashTool } from './bash.js';
 import { EditTool } from './edit.js';
 import { GlobTool } from './glob.js';
 import { GrepTool } from './grep.js';
+import { JobTool } from './job.js';
 import { ReadFileTool } from './read-file.js';
 import { VerifyOutputsTool } from './verify-outputs.js';
 import { WriteFileTool } from './write-file.js';
@@ -28,6 +35,22 @@ import { WriteFileTool } from './write-file.js';
 // `Append` tool is gone.
 // Hosts that genuinely want LS/search can still register them explicitly.
 export function getBuiltinTools() {
-    return [BashTool, EditTool, GlobTool, GrepTool, ReadFileTool, VerifyOutputsTool, WriteFileTool];
+    // `job` ships alongside `bash` rather than being opt-in, because the two
+    // are one capability. `bash run_in_background` returns an id, and an id
+    // with no tool that reads it is the exact shape of the suggestion that
+    // was removed from bash's schema for being unbacked.
+    //
+    // It costs nothing where the host provides no registry: the tool refuses
+    // and says so, which is a truthful answer rather than a missing one.
+    return [
+        BashTool,
+        EditTool,
+        GlobTool,
+        GrepTool,
+        JobTool,
+        ReadFileTool,
+        VerifyOutputsTool,
+        WriteFileTool,
+    ];
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/builtins/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,wEAAwE;AACxE,sEAAsE;AACtE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,qEAAqE;AACrE,sEAAsE;AACtE,yBAAyB;AACzB,0EAA0E;AAE1E,MAAM,UAAU,eAAe;IAC9B,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAA;AAChG,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC1E,OAAO,EACN,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AACzF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,wEAAwE;AACxE,sEAAsE;AACtE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,qEAAqE;AACrE,sEAAsE;AACtE,yBAAyB;AACzB,0EAA0E;AAE1E,MAAM,UAAU,eAAe;IAC9B,yEAAyE;IACzE,wEAAwE;IACxE,uEAAuE;IACvE,qDAAqD;IACrD,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,OAAO;QACN,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,OAAO;QACP,YAAY;QACZ,iBAAiB;QACjB,aAAa;KACb,CAAA;AACF,CAAC"}

package/dist/tools/builtins/job.d.ts

@@ -0,0 +1,6 @@
+export declare const JobTool: import("../../public-types.js").ToolDefinition<{
+    action: "read" | "list" | "kill";
+    id?: string | undefined;
+    from_offset?: number | undefined;
+}>;
+//# sourceMappingURL=job.d.ts.map

package/dist/tools/builtins/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/job.ts"],"names":[],"mappings":"AA0CA,eAAO,MAAM,OAAO;;;;EA0FlB,CAAA"}

package/dist/tools/builtins/job.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { defineTool } from '../defineTool.js';
+/**
+ * Read, list and stop the work `bash run_in_background` started.
+ *
+ * The half that was missing. The previous schema told the model to "start it
+ * in the background and poll" and there was nothing to poll with: no job id,
+ * no way to read output, no cleanup. That sentence was removed rather than
+ * honoured, because a suggestion with no mechanism behind it is worse than
+ * silence — the model follows it and gets a lie back.
+ *
+ * One tool with an `action` rather than three, because these are three views
+ * of one object and a model choosing between `read_job` / `list_jobs` /
+ * `kill_job` has three chances to pick the wrong name for the same idea.
+ */
+const inputSchema = z.object({
+    action: z
+        .enum(['read', 'list', 'kill'])
+        .describe('read: output since `from_offset`. list: every background job this run started, with status. kill: stop a job and everything it forked.'),
+    id: z
+        .string()
+        .optional()
+        .describe('The job id, as returned by bash with run_in_background. Required for read and kill.'),
+    from_offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Byte offset to read from; pass back the `next_offset` of your previous read to get only what is new. Omit to read from the start of what is retained.'),
+});
+export const JobTool = defineTool({
+    name: 'job',
+    description: 'Reads, lists and stops background jobs started by bash with run_in_background. Poll a job with action "read", passing the previous call\'s next_offset to see only new output.',
+    inputSchema,
+    category: 'shell',
+    permissions: ['shell_execute'],
+    // `read` and `list` observe; `kill` stops work. The tool as a whole is not
+    // read-only, and claiming otherwise would let a read-only permission
+    // preset hand the model a way to terminate a running process.
+    readOnly: false,
+    destructive: (input) => input.action === 'kill',
+    concurrencySafe: true,
+    async execute(input, context) {
+        if (!context.backgroundJobs) {
+            return {
+                success: false,
+                output: '',
+                error: 'This host provides no background job registry, so there are no background jobs to report on.',
+            };
+        }
+        const jobs = context.backgroundJobs;
+        if (input.action === 'list') {
+            const all = jobs.list();
+            if (all.length === 0)
+                return { success: true, output: 'No background jobs.' };
+            return {
+                success: true,
+                output: all.map((job) => `${job.id}  ${job.status.padEnd(8)}  ${job.command}`).join('\n'),
+                data: { jobs: all },
+            };
+        }
+        if (!input.id) {
+            return {
+                success: false,
+                output: '',
+                error: `action "${input.action}" needs an id. Use action "list" to see the jobs this run has started.`,
+            };
+        }
+        try {
+            if (input.action === 'kill') {
+                const killed = await jobs.kill(input.id);
+                return {
+                    success: true,
+                    output: `Job ${killed.id} is ${killed.status}.`,
+                    data: { jobId: killed.id, status: killed.status },
+                };
+            }
+            const read = jobs.read(input.id, {
+                ...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
+            });
+            // The dropped count is stated, never absorbed. A job whose middle
+            // vanished quietly reads as a complete result that happens to be
+            // short, and the model concludes the build passed.
+            const notice = read.droppedBytes > 0
+                ? `[${read.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
+                : '';
+            const status = read.status === 'running'
+                ? 'still running'
+                : `${read.status}${read.exitCode === undefined ? '' : ` with code ${read.exitCode}`}`;
+            return {
+                success: true,
+                output: `${notice}${read.chunk || '(no new output)'}\n\n[job ${input.id} is ${status}; next_offset ${read.nextOffset}]`,
+                data: {
+                    jobId: input.id,
+                    status: read.status,
+                    nextOffset: read.nextOffset,
+                    droppedBytes: read.droppedBytes,
+                    ...(read.exitCode === undefined ? {} : { exitCode: read.exitCode }),
+                },
+            };
+        }
+        catch (err) {
+            // An id from another run reads as unknown here, because the
+            // owner-bound view refuses it. That is the intended answer: a run
+            // should not be able to confirm another run's job exists.
+            return {
+                success: false,
+                output: '',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    },
+});
+//# sourceMappingURL=job.js.map

package/dist/tools/builtins/job.js.map

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

package/dist/tools/builtins/lsp.d.ts

@@ -0,0 +1,21 @@
+import type { CodeNavigationProvider } from '../../types/code-navigation/index.js';
+export declare const LSP_TOOL_NAME = "lsp";
+export declare const LspTool: import("../../types/tool/index.js").ToolDefinition<{
+    path: string;
+    operation: "hover" | "definition" | "references";
+    line: number;
+    character: number;
+} | {
+    query: string;
+    operation: "symbols";
+    path?: string | undefined;
+}>;
+/**
+ * The tool, only when there is something for it to call.
+ *
+ * A function rather than a constant because the decision is per run: the
+ * same process can serve one session with a language server and one
+ * without, and a module-level constant would have to pick.
+ */
+export declare function getCodeNavigationTools(provider: CodeNavigationProvider | undefined): (typeof LspTool)[];
+//# sourceMappingURL=lsp.d.ts.map

package/dist/tools/builtins/lsp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/lsp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAA;AA8DlF,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,eAAO,MAAM,OAAO;;;;;;;;;EA4HlB,CAAA;AAYF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,sBAAsB,GAAG,SAAS,GAC1C,CAAC,OAAO,OAAO,CAAC,EAAE,CAEpB"}

package/dist/tools/builtins/lsp.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { defineTool } from '../defineTool.js';
+import { resolveWithinReal } from '../paths.js';
+/**
+ * Symbol navigation, for the questions `grep` answers wrongly.
+ *
+ * An agent asked to find every call site of a function had `grep`: every
+ * textual occurrence, including the comment that mentions it, the string
+ * literal that names it, and the unrelated same-named symbol in another
+ * scope — and MISSING the call sites that arrive through a re-export or a
+ * destructure, which is the half a rename has to get right.
+ *
+ * **Not in `getBuiltinTools()`, and not registered when no provider is
+ * configured.** A tool that is always present and always answers
+ * "unavailable" costs a decision on every turn to say nothing, and it
+ * teaches a model that this capability exists when it does not. `bash`'s
+ * companion `job` tool ships unconditionally for the opposite reason — it
+ * has a real answer either way — and the difference is worth stating
+ * because the two look alike from the outside.
+ */
+/**
+ * Position is required for `definition`/`hover`/`references` and MUST NOT be
+ * for `symbols`.
+ *
+ * A union rather than four optional fields with a comment. `symbols` exists
+ * precisely because an agent starting from a name has no line and no
+ * character — forcing it to supply them means inventing two numbers, and a
+ * model that invents them gets an answer about whatever happens to sit at
+ * 0:0. Making position unconditionally optional has the mirror failure: a
+ * `definition` call with no position silently resolves the top of the file.
+ */
+const positioned = z.object({
+    operation: z
+        .enum(['definition', 'references', 'hover'])
+        .describe('`definition` finds where the symbol under the position is declared, `references` finds everywhere it is used, `hover` gives its type and documentation.'),
+    path: z.string().describe('File containing the symbol, relative to the working directory.'),
+    line: z.number().int().min(0).describe('Zero-based line of the symbol.'),
+    character: z.number().int().min(0).describe('Zero-based column of the symbol.'),
+});
+const byName = z.object({
+    operation: z
+        .literal('symbols')
+        .describe('Find a declaration by NAME, with no position. Start here: the other operations need a line and character, and this is how you get them.'),
+    query: z.string().min(1).describe('The symbol name, or part of it.'),
+    path: z
+        .string()
+        .optional()
+        .describe('Optional file to scope the search to. Absent searches every configured language.'),
+});
+const inputSchema = z.discriminatedUnion('operation', [positioned, byName]);
+export const LSP_TOOL_NAME = 'lsp';
+export const LspTool = defineTool({
+    name: LSP_TOOL_NAME,
+    description: 'Resolves a symbol through a language server: where it is declared, and everywhere it is used. Use it instead of grep when the answer has to be right — grep finds the identifier in comments and strings and misses call sites that come through a re-export.',
+    inputSchema,
+    category: 'filesystem',
+    permissions: ['file_read'],
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+    async execute(input, context) {
+        const provider = context.codeNavigation;
+        if (!provider) {
+            // Reachable only if a host registered this tool without a provider.
+            // The registration path does not, so this is the refusal for a host
+            // that wired it up by hand — and it names the missing piece rather
+            // than reading as "no results".
+            return {
+                success: false,
+                output: '',
+                error: 'This run has no code navigation provider, so there is nothing to resolve against. A host supplies one on the tool context; `grep` is the fallback, and it answers a different question.',
+            };
+        }
+        // Contained BEFORE the path reaches the server, with the same
+        // containment `read` and `grep` use. A language server indexes a
+        // workspace and will happily answer about `../../etc/passwd` if asked;
+        // the boundary is this tool's job, not the server's.
+        let absolute;
+        if (input.path !== undefined) {
+            try {
+                absolute = await resolveWithinReal(context.workingDirectory, input.path);
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    output: '',
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        }
+        if (input.operation === 'symbols') {
+            const result = await provider.symbols(input.query, absolute);
+            switch (result.kind) {
+                case 'symbols': {
+                    if (result.symbols.length === 0) {
+                        return {
+                            success: true,
+                            output: `No symbol matching "${input.query}" was found.`,
+                            data: { operation: 'symbols', count: 0, symbols: [] },
+                        };
+                    }
+                    return {
+                        success: true,
+                        output: result.symbols
+                            .map((s) => `${s.name} — ${s.path}:${s.line}:${s.character}`)
+                            .join('\n'),
+                        data: { operation: 'symbols', count: result.symbols.length, symbols: result.symbols },
+                    };
+                }
+                case 'unsupported':
+                    return { success: false, output: '', error: unsupportedMessage(result.reason) };
+                case 'failed':
+                    return { success: false, output: '', error: failedMessage(result.error) };
+            }
+        }
+        if (input.operation === 'hover') {
+            const result = await provider.hover(absolute, input.line, input.character);
+            switch (result.kind) {
+                case 'hover':
+                    return {
+                        success: true,
+                        // An EMPTY hover is a real answer — whitespace, a comment, a
+                        // token with no type — and it has to read differently from a
+                        // server that broke.
+                        output: result.contents ||
+                            `Nothing to show at ${input.path}:${input.line}:${input.character}.`,
+                        data: { operation: 'hover', contents: result.contents },
+                    };
+                case 'unsupported':
+                    return { success: false, output: '', error: unsupportedMessage(result.reason) };
+                case 'failed':
+                    return { success: false, output: '', error: failedMessage(result.error) };
+            }
+        }
+        const result = input.operation === 'definition'
+            ? await provider.definition(absolute, input.line, input.character)
+            : await provider.references(absolute, input.line, input.character);
+        switch (result.kind) {
+            case 'locations': {
+                if (result.locations.length === 0) {
+                    // A real answer: the server looked and there are none. Said
+                    // plainly, because "no references" is what a deletion needs to
+                    // hear and it must not be confused with a failure.
+                    return {
+                        success: true,
+                        output: `No ${input.operation} found for the symbol at ${input.path}:${input.line}:${input.character}.`,
+                        data: { operation: input.operation, count: 0, locations: [] },
+                    };
+                }
+                const lines = result.locations.map((l) => `${l.path}:${l.line}:${l.character}`);
+                return {
+                    success: true,
+                    output: lines.join('\n'),
+                    data: {
+                        operation: input.operation,
+                        count: result.locations.length,
+                        locations: result.locations,
+                    },
+                };
+            }
+            case 'unsupported':
+                return { success: false, output: '', error: unsupportedMessage(result.reason) };
+            case 'failed':
+                return { success: false, output: '', error: failedMessage(result.error) };
+        }
+    },
+});
+/** Distinct from a failure on purpose: the model can fall back and know why. */
+function unsupportedMessage(reason) {
+    return `${reason} Fall back to \`grep\`, and treat the result as textual rather than resolved.`;
+}
+/** NOT an empty result. An agent told a symbol has no callers deletes it. */
+function failedMessage(error) {
+    return `Code navigation failed, so this answer is unknown rather than empty: ${error}`;
+}
+/**
+ * The tool, only when there is something for it to call.
+ *
+ * A function rather than a constant because the decision is per run: the
+ * same process can serve one session with a language server and one
+ * without, and a module-level constant would have to pick.
+ */
+export function getCodeNavigationTools(provider) {
+    return provider ? [LspTool] : [];
+}
+//# sourceMappingURL=lsp.js.map

package/dist/tools/builtins/lsp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp.js","sourceRoot":"","sources":["../../../src/tools/builtins/lsp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,SAAS,EAAE,CAAC;SACV,IAAI,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;SAC3C,QAAQ,CACR,yJAAyJ,CACzJ;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;IAC3F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACxE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kCAAkC,CAAC;CAC/E,CAAC,CAAA;AAEF,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACvB,SAAS,EAAE,CAAC;SACV,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CACR,yIAAyI,CACzI;IACF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IACpE,IAAI,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kFAAkF,CAAC;CAC9F,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,CAAC,CAAC,kBAAkB,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;AAI3E,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAC;IACjC,IAAI,EAAE,aAAa;IACnB,WAAW,EACV,+PAA+P;IAChQ,WAAW;IACX,QAAQ,EAAE,YAAY;IACtB,WAAW,EAAE,CAAC,WAAW,CAAC;IAC1B,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,KAAK;IAClB,eAAe,EAAE,IAAI;IAErB,KAAK,CAAC,OAAO,CAAC,KAAe,EAAE,OAAO;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAA;QACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,oEAAoE;YACpE,oEAAoE;YACpE,mEAAmE;YACnE,gCAAgC;YAChC,OAAO;gBACN,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,EAAE;gBACV,KAAK,EACJ,yLAAyL;aAC1L,CAAA;QACF,CAAC;QAED,8DAA8D;QAC9D,iEAAiE;QACjE,uEAAuE;QACvE,qDAAqD;QACrD,IAAI,QAA4B,CAAA;QAChC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACJ,QAAQ,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;YACzE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,OAAO;oBACN,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,EAAE;oBACV,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACvD,CAAA;YACF,CAAC;QACF,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;YAC5D,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,SAAS,CAAC,CAAC,CAAC;oBAChB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACjC,OAAO;4BACN,OAAO,EAAE,IAAI;4BACb,MAAM,EAAE,uBAAuB,KAAK,CAAC,KAAK,cAAc;4BACxD,IAAI,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;yBACrD,CAAA;oBACF,CAAC;oBACD,OAAO;wBACN,OAAO,EAAE,IAAI;wBACb,MAAM,EAAE,MAAM,CAAC,OAAO;6BACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;6BAC5D,IAAI,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;qBACrF,CAAA;gBACF,CAAC;gBACD,KAAK,aAAa;oBACjB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAA;gBAChF,KAAK,QAAQ;oBACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;YAC3E,CAAC;QACF,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAkB,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;YACpF,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO;oBACX,OAAO;wBACN,OAAO,EAAE,IAAI;wBACb,6DAA6D;wBAC7D,6DAA6D;wBAC7D,qBAAqB;wBACrB,MAAM,EACL,MAAM,CAAC,QAAQ;4BACf,sBAAsB,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,GAAG;wBACrE,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;qBACvD,CAAA;gBACF,KAAK,aAAa;oBACjB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAA;gBAChF,KAAK,QAAQ;oBACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;YAC3E,CAAC;QACF,CAAC;QAED,MAAM,MAAM,GACX,KAAK,CAAC,SAAS,KAAK,YAAY;YAC/B,CAAC,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,QAAkB,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC;YAC5E,CAAC,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,QAAkB,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;QAE9E,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,WAAW,CAAC,CAAC,CAAC;gBAClB,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnC,4DAA4D;oBAC5D,+DAA+D;oBAC/D,mDAAmD;oBACnD,OAAO;wBACN,OAAO,EAAE,IAAI;wBACb,MAAM,EAAE,MAAM,KAAK,CAAC,SAAS,4BAA4B,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,GAAG;wBACvG,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;qBAC7D,CAAA;gBACF,CAAC;gBACD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA;gBAC/E,OAAO;oBACN,OAAO,EAAE,IAAI;oBACb,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;oBACxB,IAAI,EAAE;wBACL,SAAS,EAAE,KAAK,CAAC,SAAS;wBAC1B,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,MAAM;wBAC9B,SAAS,EAAE,MAAM,CAAC,SAAS;qBAC3B;iBACD,CAAA;YACF,CAAC;YACD,KAAK,aAAa;gBACjB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAA;YAChF,KAAK,QAAQ;gBACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;QAC3E,CAAC;IACF,CAAC;CACD,CAAC,CAAA;AAEF,gFAAgF;AAChF,SAAS,kBAAkB,CAAC,MAAc;IACzC,OAAO,GAAG,MAAM,+EAA+E,CAAA;AAChG,CAAC;AAED,6EAA6E;AAC7E,SAAS,aAAa,CAAC,KAAa;IACnC,OAAO,wEAAwE,KAAK,EAAE,CAAA;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACrC,QAA4C;IAE5C,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACjC,CAAC"}

package/dist/tools/builtins/run-code.d.ts

@@ -0,0 +1,13 @@
+import type { CodeRuntime } from '../../execution/code-runtime/types.js';
+export declare const RUN_CODE_TOOL_NAME = "run_code";
+export interface RunCodeToolOptions {
+    /** Defaults to the `worker_threads` backend. */
+    readonly runtime?: CodeRuntime;
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+}
+export declare function buildRunCodeTool(options?: RunCodeToolOptions): import("../../public-types.js").ToolDefinition<{
+    code: string;
+    tools: string[];
+}>;
+//# sourceMappingURL=run-code.d.ts.map

package/dist/tools/builtins/run-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-code.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/run-code.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAA;AA0CxE,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC;AAKD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB;;;GAiGhE"}

package/dist/tools/builtins/run-code.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import { WorkerCodeRuntime } from '../../execution/code-runtime/worker.js';
+import { defineTool } from '../defineTool.js';
+/**
+ * A program the model wrote, calling the run's own tools.
+ *
+ * Twenty tool calls to filter a list is twenty model turns, each at full
+ * context size with the whole conversation resent. The same work is one
+ * loop. That is the entire argument for this tool, and it only holds if the
+ * loop cannot reach further than the twenty calls could have.
+ *
+ * **The program's reach is the RUN's reach, and nothing wider.** Every
+ * capability it can call is a tool already in this run's registry, already
+ * narrowed by the turn's `allowedTools`, already subject to the same
+ * dispatch that a model-issued call goes through — the permission gate, the
+ * approval policy, the audit record. There is no second path: the runtime
+ * hands the host a name and an input, and the host does exactly what it
+ * would have done for a `tool_use` block.
+ *
+ * Opt-in, and not in the default builtin set. A run that does not need
+ * model-authored control flow should not have a way to execute
+ * model-authored text, and "the tool was there so it got used" is not a
+ * threat model.
+ */
+const inputSchema = z.object({
+    code: z
+        .string()
+        .min(1)
+        .describe('An async JavaScript body. Call a tool with `await call("tool_name", { ...input })`, print with `print(...)`, and `return` the result. No require, no process, no fetch — everything goes through `call`.'),
+    tools: z
+        .array(z.string())
+        .describe('The tools this program may call. It is refused any name not in this list, so keep it to what the program actually needs.'),
+});
+export const RUN_CODE_TOOL_NAME = 'run_code';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_OUTPUT = 64 * 1024;
+export function buildRunCodeTool(options = {}) {
+    const runtime = options.runtime ?? new WorkerCodeRuntime();
+    return defineTool({
+        name: RUN_CODE_TOOL_NAME,
+        description: "Runs a short JavaScript program that can call this run's own tools in a loop. Use it when the same tool would otherwise be called many times in a row — filtering, retrying, fanning out — and not for a single call.",
+        inputSchema,
+        category: 'custom',
+        permissions: [],
+        // NOT read-only and NOT non-destructive, whatever the program turns
+        // out to do. Its effects are the union of the tools it calls, which
+        // is not knowable from the input — and a `readOnly: true` here would
+        // let a read-only preset auto-approve a program whose whole purpose
+        // is calling something else.
+        readOnly: false,
+        destructive: true,
+        concurrencySafe: false,
+        async execute(input, context) {
+            const dispatch = context.dispatchTool;
+            if (!dispatch) {
+                return {
+                    success: false,
+                    output: '',
+                    error: 'This run provides no way to dispatch a tool, so a program has nothing to call.',
+                };
+            }
+            // The intersection, computed HERE rather than trusted from the
+            // input. `tools` is model-authored: a program that listed every
+            // tool it wished for would otherwise widen its own grant, which is
+            // the privilege escalation this whole design exists to prevent.
+            const turnAllows = context.allowedTools;
+            const granted = input.tools.filter((name) => turnAllows === undefined || turnAllows.includes(name));
+            const refused = input.tools.filter((name) => !granted.includes(name));
+            const result = await runtime.run({
+                source: input.code,
+                allowedCalls: granted,
+                timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT,
+                ...(context.abortSignal ? { signal: context.abortSignal } : {}),
+                onHostCall: async (request) => {
+                    // Through the SAME registry, with the SAME context. Not a
+                    // parallel dispatch path: a second path is a second place
+                    // for the permission gate to be forgotten, and the one that
+                    // forgot it would be the one a model reached through a
+                    // program.
+                    try {
+                        const toolResult = await dispatch(request.name, request.input);
+                        return toolResult.success
+                            ? { ok: true, value: toolResult.output }
+                            : { ok: false, error: toolResult.error ?? 'the tool failed' };
+                    }
+                    catch (err) {
+                        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                    }
+                },
+            });
+            const notes = [
+                refused.length > 0
+                    ? `[not granted, and refused to the program: ${refused.join(', ')} — this turn allows only ${turnAllows?.join(', ') ?? 'the run default'}]`
+                    : '',
+                result.outputTruncated
+                    ? '[the program printed more than the output limit and was cut here]'
+                    : '',
+            ].filter(Boolean);
+            const body = [result.output, ...notes].filter(Boolean).join('\n');
+            switch (result.outcome.status) {
+                case 'completed':
+                    return {
+                        success: true,
+                        output: `${body}${body ? '\n' : ''}[returned] ${JSON.stringify(result.outcome.result) ?? 'undefined'}`,
+                        data: { calls: result.calls, truncated: result.outputTruncated },
+                    };
+                case 'timed-out':
+                    return {
+                        success: false,
+                        output: body,
+                        // The output is carried on the failure too. A program that
+                        // printed its progress and then hung has told the model
+                        // where it got to, and discarding that leaves the model
+                        // retrying from the start.
+                        error: `The program ran longer than ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms and was stopped.`,
+                    };
+                case 'cancelled':
+                    return { success: false, output: body, error: 'The program was cancelled.' };
+                default:
+                    return { success: false, output: body, error: result.outcome.error };
+            }
+        },
+    });
+}
+//# sourceMappingURL=run-code.js.map

package/dist/tools/builtins/run-code.js.map

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

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

@@ -0,0 +1,14 @@
+/**
+ * `allowed-tools` as a list.
+ *
+ * Comma-separated in the frontmatter because that is what authors write and
+ * what the field has always accepted. Split here rather than at parse so
+ * the stored metadata keeps the author's own string — the same reasoning
+ * `invocation` uses for not defaulting at parse.
+ */
+export declare function parseAllowedTools(declared: string | undefined): readonly string[] | undefined;
+export declare const SKILL_TOOL_NAME = "skill";
+export declare const SkillTool: import("../../public-types.js").ToolDefinition<{
+    name: string;
+}>;
+//# sourceMappingURL=skill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/skill.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAW7F;AAED,eAAO,MAAM,eAAe,UAAU,CAAA;AAEtC,eAAO,MAAM,SAAS;;EAgFpB,CAAA"}