apex-code 0.0.1-alpha.0 → 0.0.1-alpha.10

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

@@ -0,0 +1,34 @@
+import type { AgentTool } from "apex-code-agent-core";
+import { type Static, Type } from "typebox";
+import type { ApexToolDefinition, PermissionSpec } from "./contract.ts";
+declare const testSchema: Type.TObject<{
+    executable: Type.TString;
+    args: Type.TArray<Type.TString>;
+}>;
+export type TestToolInput = Static<typeof testSchema>;
+export interface TestRunDetails {
+    cwd: string;
+    executable: string;
+    argv: string[];
+    exitCode: number | null;
+}
+export interface TestOperationResult {
+    exitCode: number | null;
+}
+export interface TestOperations {
+    run(input: {
+        executable: string;
+        argv: string[];
+        cwd: string;
+        signal?: AbortSignal;
+    }): Promise<TestOperationResult>;
+}
+export declare function createTestPermissionSpec(): PermissionSpec<typeof testSchema>;
+export interface TestToolOptions {
+    operations?: TestOperations;
+}
+/** Runs an argv-based test runner and returns its exit status as source-level evidence. */
+export declare function createTestToolDefinition(cwd: string, options?: TestToolOptions): ApexToolDefinition<typeof testSchema, TestRunDetails>;
+export declare function createTestTool(cwd: string, options?: TestToolOptions): AgentTool<typeof testSchema, TestRunDetails>;
+export {};
+//# sourceMappingURL=test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../../src/core/tools/test.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGxE,QAAA,MAAM,UAAU;;;EAKd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpH;AAwBD,wBAAgB,wBAAwB,IAAI,cAAc,CAAC,OAAO,UAAU,CAAC,CAO5E;AAED,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,kBAAkB,CAAC,OAAO,UAAU,EAAE,cAAc,CAAC,CA2BvD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,EAAE,cAAc,CAAC,CAEnH","sourcesContent":["import { spawn } from \"node:child_process\";\nimport type { AgentTool } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { waitForChildProcess } from \"../../utils/child-process.ts\";\nimport type { ApexToolDefinition, PermissionSpec } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst testSchema = Type.Object({\n\texecutable: Type.String({ description: \"Test runner executable, for example npm, npx, or pytest\" }),\n\targs: Type.Array(Type.String(), {\n\t\tdescription: \"Arguments passed directly to the test runner; never a shell command\",\n\t}),\n});\n\nexport type TestToolInput = Static<typeof testSchema>;\n\nexport interface TestRunDetails {\n\tcwd: string;\n\texecutable: string;\n\targv: string[];\n\texitCode: number | null;\n}\n\nexport interface TestOperationResult {\n\texitCode: number | null;\n}\n\nexport interface TestOperations {\n\trun(input: { executable: string; argv: string[]; cwd: string; signal?: AbortSignal }): Promise<TestOperationResult>;\n}\n\nconst defaultOperations: TestOperations = {\n\tasync run({ executable, argv, cwd, signal }) {\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\tconst child = spawn(executable, argv, {\n\t\t\tcwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\twindowsHide: true,\n\t\t});\n\t\tchild.stdout?.resume();\n\t\tchild.stderr?.resume();\n\t\tconst abort = () => child.kill();\n\t\tif (signal) signal.addEventListener(\"abort\", abort, { once: true });\n\t\ttry {\n\t\t\tconst exitCode = await waitForChildProcess(child);\n\t\t\treturn { exitCode };\n\t\t} finally {\n\t\t\tif (signal) signal.removeEventListener(\"abort\", abort);\n\t\t}\n\t},\n};\n\nexport function createTestPermissionSpec(): PermissionSpec<typeof testSchema> {\n\treturn {\n\t\tdefaultBehavior: \"ask\",\n\t\tmatches: (ruleContent, params) => ruleContent === JSON.stringify(params),\n\t\tdescribe: (ruleContent) => `Run test command: ${ruleContent}`,\n\t\truleForCall: (params) => JSON.stringify(params),\n\t};\n}\n\nexport interface TestToolOptions {\n\toperations?: TestOperations;\n}\n\n/** Runs an argv-based test runner and returns its exit status as source-level evidence. */\nexport function createTestToolDefinition(\n\tcwd: string,\n\toptions?: TestToolOptions,\n): ApexToolDefinition<typeof testSchema, TestRunDetails> {\n\tconst operations = options?.operations ?? defaultOperations;\n\treturn {\n\t\tname: \"test\",\n\t\tlabel: \"test\",\n\t\tdescription:\n\t\t\t\"Run a test executable with direct argv arguments. A non-zero exit code is reported as a test failure.\",\n\t\tparameters: testSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"exec\"]),\n\t\t\tpermission: createTestPermissionSpec(),\n\t\t\tcontext: { resultRecoverable: false, deferSchema: false },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"test\"]),\n\t\t\t\tcapture: (_params, result) => [{ kind: \"test\", ...result.details }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input, signal) {\n\t\t\tconst observed = await operations.run({ executable: input.executable, argv: input.args, cwd, signal });\n\t\t\tconst details: TestRunDetails = { ...observed, cwd, executable: input.executable, argv: [...input.args] };\n\t\t\tconst status = details.exitCode === 0 ? \"passed\" : `failed (exit code ${details.exitCode ?? \"unknown\"})`;\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `Test runner ${status}: ${input.executable} ${input.args.join(\" \")}` }],\n\t\t\t\tdetails,\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createTestTool(cwd: string, options?: TestToolOptions): AgentTool<typeof testSchema, TestRunDetails> {\n\treturn wrapToolDefinition(createTestToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/test.js

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import { Type } from "typebox";
+import { waitForChildProcess } from "../../utils/child-process.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const testSchema = Type.Object({
+    executable: Type.String({ description: "Test runner executable, for example npm, npx, or pytest" }),
+    args: Type.Array(Type.String(), {
+        description: "Arguments passed directly to the test runner; never a shell command",
+    }),
+});
+const defaultOperations = {
+    async run({ executable, argv, cwd, signal }) {
+        if (signal?.aborted)
+            throw new Error("Operation aborted");
+        const child = spawn(executable, argv, {
+            cwd,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        child.stdout?.resume();
+        child.stderr?.resume();
+        const abort = () => child.kill();
+        if (signal)
+            signal.addEventListener("abort", abort, { once: true });
+        try {
+            const exitCode = await waitForChildProcess(child);
+            return { exitCode };
+        }
+        finally {
+            if (signal)
+                signal.removeEventListener("abort", abort);
+        }
+    },
+};
+export function createTestPermissionSpec() {
+    return {
+        defaultBehavior: "ask",
+        matches: (ruleContent, params) => ruleContent === JSON.stringify(params),
+        describe: (ruleContent) => `Run test command: ${ruleContent}`,
+        ruleForCall: (params) => JSON.stringify(params),
+    };
+}
+/** Runs an argv-based test runner and returns its exit status as source-level evidence. */
+export function createTestToolDefinition(cwd, options) {
+    const operations = options?.operations ?? defaultOperations;
+    return {
+        name: "test",
+        label: "test",
+        description: "Run a test executable with direct argv arguments. A non-zero exit code is reported as a test failure.",
+        parameters: testSchema,
+        contract: {
+            capabilities: new Set(["exec"]),
+            permission: createTestPermissionSpec(),
+            context: { resultRecoverable: false, deferSchema: false },
+            evidence: {
+                emits: new Set(["test"]),
+                capture: (_params, result) => [{ kind: "test", ...result.details }],
+            },
+        },
+        async execute(_toolCallId, input, signal) {
+            const observed = await operations.run({ executable: input.executable, argv: input.args, cwd, signal });
+            const details = { ...observed, cwd, executable: input.executable, argv: [...input.args] };
+            const status = details.exitCode === 0 ? "passed" : `failed (exit code ${details.exitCode ?? "unknown"})`;
+            return {
+                content: [{ type: "text", text: `Test runner ${status}: ${input.executable} ${input.args.join(" ")}` }],
+                details,
+            };
+        },
+    };
+}
+export function createTestTool(cwd, options) {
+    return wrapToolDefinition(createTestToolDefinition(cwd, options));
+}
+//# sourceMappingURL=test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../../../src/core/tools/test.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport type { AgentTool } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { waitForChildProcess } from \"../../utils/child-process.ts\";\nimport type { ApexToolDefinition, PermissionSpec } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst testSchema = Type.Object({\n\texecutable: Type.String({ description: \"Test runner executable, for example npm, npx, or pytest\" }),\n\targs: Type.Array(Type.String(), {\n\t\tdescription: \"Arguments passed directly to the test runner; never a shell command\",\n\t}),\n});\n\nexport type TestToolInput = Static<typeof testSchema>;\n\nexport interface TestRunDetails {\n\tcwd: string;\n\texecutable: string;\n\targv: string[];\n\texitCode: number | null;\n}\n\nexport interface TestOperationResult {\n\texitCode: number | null;\n}\n\nexport interface TestOperations {\n\trun(input: { executable: string; argv: string[]; cwd: string; signal?: AbortSignal }): Promise<TestOperationResult>;\n}\n\nconst defaultOperations: TestOperations = {\n\tasync run({ executable, argv, cwd, signal }) {\n\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\tconst child = spawn(executable, argv, {\n\t\t\tcwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\twindowsHide: true,\n\t\t});\n\t\tchild.stdout?.resume();\n\t\tchild.stderr?.resume();\n\t\tconst abort = () => child.kill();\n\t\tif (signal) signal.addEventListener(\"abort\", abort, { once: true });\n\t\ttry {\n\t\t\tconst exitCode = await waitForChildProcess(child);\n\t\t\treturn { exitCode };\n\t\t} finally {\n\t\t\tif (signal) signal.removeEventListener(\"abort\", abort);\n\t\t}\n\t},\n};\n\nexport function createTestPermissionSpec(): PermissionSpec<typeof testSchema> {\n\treturn {\n\t\tdefaultBehavior: \"ask\",\n\t\tmatches: (ruleContent, params) => ruleContent === JSON.stringify(params),\n\t\tdescribe: (ruleContent) => `Run test command: ${ruleContent}`,\n\t\truleForCall: (params) => JSON.stringify(params),\n\t};\n}\n\nexport interface TestToolOptions {\n\toperations?: TestOperations;\n}\n\n/** Runs an argv-based test runner and returns its exit status as source-level evidence. */\nexport function createTestToolDefinition(\n\tcwd: string,\n\toptions?: TestToolOptions,\n): ApexToolDefinition<typeof testSchema, TestRunDetails> {\n\tconst operations = options?.operations ?? defaultOperations;\n\treturn {\n\t\tname: \"test\",\n\t\tlabel: \"test\",\n\t\tdescription:\n\t\t\t\"Run a test executable with direct argv arguments. A non-zero exit code is reported as a test failure.\",\n\t\tparameters: testSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"exec\"]),\n\t\t\tpermission: createTestPermissionSpec(),\n\t\t\tcontext: { resultRecoverable: false, deferSchema: false },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"test\"]),\n\t\t\t\tcapture: (_params, result) => [{ kind: \"test\", ...result.details }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input, signal) {\n\t\t\tconst observed = await operations.run({ executable: input.executable, argv: input.args, cwd, signal });\n\t\t\tconst details: TestRunDetails = { ...observed, cwd, executable: input.executable, argv: [...input.args] };\n\t\t\tconst status = details.exitCode === 0 ? \"passed\" : `failed (exit code ${details.exitCode ?? \"unknown\"})`;\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `Test runner ${status}: ${input.executable} ${input.args.join(\" \")}` }],\n\t\t\t\tdetails,\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createTestTool(cwd: string, options?: TestToolOptions): AgentTool<typeof testSchema, TestRunDetails> {\n\treturn wrapToolDefinition(createTestToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/todo-write.d.ts

@@ -0,0 +1,31 @@
+import { type Static, Type } from "typebox";
+import type { ApexToolDefinition } from "./contract.ts";
+declare const todoItemSchema: Type.TObject<{
+    content: Type.TString;
+    status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>;
+}>;
+declare const todoWriteSchema: Type.TObject<{
+    todos: Type.TArray<Type.TObject<{
+        content: Type.TString;
+        status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>;
+    }>>;
+}>;
+export type TodoItem = Static<typeof todoItemSchema>;
+export type TodoWriteInput = Static<typeof todoWriteSchema>;
+export interface TodoWriteDetails {
+    todos: TodoItem[];
+}
+export interface TodoWriteStore {
+    /** Persist the full replacement task list. */
+    write(todos: TodoItem[]): void;
+}
+/** Create the harness-state tool that lets an agent record and update its own task list. */
+export declare function createTodoWriteToolDefinition(store: TodoWriteStore): ApexToolDefinition<typeof todoWriteSchema, TodoWriteDetails>;
+export declare function createTodoWriteTool(store: TodoWriteStore): import("apex-code-agent-core").AgentTool<Type.TObject<{
+    todos: Type.TArray<Type.TObject<{
+        content: Type.TString;
+        status: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>;
+    }>>;
+}>, TodoWriteDetails>;
+export {};
+//# sourceMappingURL=todo-write.d.ts.map

package/dist/core/tools/todo-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-write.d.ts","sourceRoot":"","sources":["../../../src/core/tools/todo-write.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAKxD,QAAA,MAAM,cAAc;;;EAGlB,CAAC;AAEH,QAAA,MAAM,eAAe;;;;;EAInB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC9B,8CAA8C;IAC9C,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;CAC/B;AASD,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAC5C,KAAK,EAAE,cAAc,GACnB,kBAAkB,CAAC,OAAO,eAAe,EAAE,gBAAgB,CAAC,CA0B9D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc;;;;;sBAExD","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst todoStatus = Type.Union([Type.Literal(\"pending\"), Type.Literal(\"in_progress\"), Type.Literal(\"completed\")]);\n\nconst todoItemSchema = Type.Object({\n\tcontent: Type.String({ description: \"Short description of the task.\" }),\n\tstatus: todoStatus,\n});\n\nconst todoWriteSchema = Type.Object({\n\ttodos: Type.Array(todoItemSchema, {\n\t\tdescription: \"The complete, updated task list. Replaces whatever list was previously recorded.\",\n\t}),\n});\n\nexport type TodoItem = Static<typeof todoItemSchema>;\nexport type TodoWriteInput = Static<typeof todoWriteSchema>;\n\nexport interface TodoWriteDetails {\n\ttodos: TodoItem[];\n}\n\nexport interface TodoWriteStore {\n\t/** Persist the full replacement task list. */\n\twrite(todos: TodoItem[]): void;\n}\n\nfunction summarize(todos: TodoItem[]): string {\n\tif (todos.length === 0) return \"Task list cleared.\";\n\tconst counts = { pending: 0, in_progress: 0, completed: 0 };\n\tfor (const todo of todos) counts[todo.status]++;\n\treturn `Task list updated (${todos.length} total): ${counts.pending} pending, ${counts.in_progress} in_progress, ${counts.completed} completed.`;\n}\n\n/** Create the harness-state tool that lets an agent record and update its own task list. */\nexport function createTodoWriteToolDefinition(\n\tstore: TodoWriteStore,\n): ApexToolDefinition<typeof todoWriteSchema, TodoWriteDetails> {\n\treturn {\n\t\tname: \"todo_write\",\n\t\tlabel: \"todo_write\",\n\t\tdescription:\n\t\t\t\"Record or update the current task list. Always pass the complete, updated list -- it replaces whatever was recorded before.\",\n\t\tparameters: todoWriteSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"state\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Updating the task list\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: true, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(_toolCallId, { todos }: TodoWriteInput): Promise<AgentToolResult<TodoWriteDetails>> {\n\t\t\tstore.write(todos);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: summarize(todos) }],\n\t\t\t\tdetails: { todos },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createTodoWriteTool(store: TodoWriteStore) {\n\treturn wrapToolDefinition(createTodoWriteToolDefinition(store));\n}\n"]}

package/dist/core/tools/todo-write.js

@@ -0,0 +1,51 @@
+import { Type } from "typebox";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const todoStatus = Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")]);
+const todoItemSchema = Type.Object({
+    content: Type.String({ description: "Short description of the task." }),
+    status: todoStatus,
+});
+const todoWriteSchema = Type.Object({
+    todos: Type.Array(todoItemSchema, {
+        description: "The complete, updated task list. Replaces whatever list was previously recorded.",
+    }),
+});
+function summarize(todos) {
+    if (todos.length === 0)
+        return "Task list cleared.";
+    const counts = { pending: 0, in_progress: 0, completed: 0 };
+    for (const todo of todos)
+        counts[todo.status]++;
+    return `Task list updated (${todos.length} total): ${counts.pending} pending, ${counts.in_progress} in_progress, ${counts.completed} completed.`;
+}
+/** Create the harness-state tool that lets an agent record and update its own task list. */
+export function createTodoWriteToolDefinition(store) {
+    return {
+        name: "todo_write",
+        label: "todo_write",
+        description: "Record or update the current task list. Always pass the complete, updated list -- it replaces whatever was recorded before.",
+        parameters: todoWriteSchema,
+        contract: {
+            capabilities: new Set(["state"]),
+            permission: {
+                defaultBehavior: "allow",
+                matches: () => false,
+                describe: () => "Updating the task list",
+                ruleForCall: () => null,
+            },
+            context: { resultRecoverable: true, deferSchema: true },
+            evidence: { emits: new Set(), capture: () => [] },
+        },
+        async execute(_toolCallId, { todos }) {
+            store.write(todos);
+            return {
+                content: [{ type: "text", text: summarize(todos) }],
+                details: { todos },
+            };
+        },
+    };
+}
+export function createTodoWriteTool(store) {
+    return wrapToolDefinition(createTodoWriteToolDefinition(store));
+}
+//# sourceMappingURL=todo-write.js.map

package/dist/core/tools/todo-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-write.js","sourceRoot":"","sources":["../../../src/core/tools/todo-write.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAEjH,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC;IACvE,MAAM,EAAE,UAAU;CAClB,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC;IACnC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE;QACjC,WAAW,EAAE,kFAAkF;KAC/F,CAAC;CACF,CAAC,CAAC;AAcH,SAAS,SAAS,CAAC,KAAiB,EAAU;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,oBAAoB,CAAC;IACpD,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC5D,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAChD,OAAO,sBAAsB,KAAK,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,aAAa,MAAM,CAAC,WAAW,iBAAiB,MAAM,CAAC,SAAS,aAAa,CAAC;AAAA,CACjJ;AAED,4FAA4F;AAC5F,MAAM,UAAU,6BAA6B,CAC5C,KAAqB,EAC0C;IAC/D,OAAO;QACN,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,YAAY;QACnB,WAAW,EACV,6HAA6H;QAC9H,UAAU,EAAE,eAAe;QAC3B,QAAQ,EAAE;YACT,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,EAAE;gBACX,eAAe,EAAE,OAAO;gBACxB,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK;gBACpB,QAAQ,EAAE,GAAG,EAAE,CAAC,wBAAwB;gBACxC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI;aACvB;YACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;YACvD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;SACjD;QACD,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,KAAK,EAAkB,EAA8C;YACjG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,OAAO,EAAE,EAAE,KAAK,EAAE;aAClB,CAAC;QAAA,CACF;KACD,CAAC;AAAA,CACF;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAqB,EAAE;IAC1D,OAAO,kBAAkB,CAAC,6BAA6B,CAAC,KAAK,CAAC,CAAC,CAAC;AAAA,CAChE","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst todoStatus = Type.Union([Type.Literal(\"pending\"), Type.Literal(\"in_progress\"), Type.Literal(\"completed\")]);\n\nconst todoItemSchema = Type.Object({\n\tcontent: Type.String({ description: \"Short description of the task.\" }),\n\tstatus: todoStatus,\n});\n\nconst todoWriteSchema = Type.Object({\n\ttodos: Type.Array(todoItemSchema, {\n\t\tdescription: \"The complete, updated task list. Replaces whatever list was previously recorded.\",\n\t}),\n});\n\nexport type TodoItem = Static<typeof todoItemSchema>;\nexport type TodoWriteInput = Static<typeof todoWriteSchema>;\n\nexport interface TodoWriteDetails {\n\ttodos: TodoItem[];\n}\n\nexport interface TodoWriteStore {\n\t/** Persist the full replacement task list. */\n\twrite(todos: TodoItem[]): void;\n}\n\nfunction summarize(todos: TodoItem[]): string {\n\tif (todos.length === 0) return \"Task list cleared.\";\n\tconst counts = { pending: 0, in_progress: 0, completed: 0 };\n\tfor (const todo of todos) counts[todo.status]++;\n\treturn `Task list updated (${todos.length} total): ${counts.pending} pending, ${counts.in_progress} in_progress, ${counts.completed} completed.`;\n}\n\n/** Create the harness-state tool that lets an agent record and update its own task list. */\nexport function createTodoWriteToolDefinition(\n\tstore: TodoWriteStore,\n): ApexToolDefinition<typeof todoWriteSchema, TodoWriteDetails> {\n\treturn {\n\t\tname: \"todo_write\",\n\t\tlabel: \"todo_write\",\n\t\tdescription:\n\t\t\t\"Record or update the current task list. Always pass the complete, updated list -- it replaces whatever was recorded before.\",\n\t\tparameters: todoWriteSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"state\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Updating the task list\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: true, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(_toolCallId, { todos }: TodoWriteInput): Promise<AgentToolResult<TodoWriteDetails>> {\n\t\t\tstore.write(todos);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: summarize(todos) }],\n\t\t\t\tdetails: { todos },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createTodoWriteTool(store: TodoWriteStore) {\n\treturn wrapToolDefinition(createTodoWriteToolDefinition(store));\n}\n"]}

package/dist/core/tools/tool-definition-wrapper.d.ts

@@ -1,7 +1,18 @@
 import type { AgentTool } from "apex-code-agent-core";
+import type { TSchema } from "typebox";
 import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
-/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
-export declare function wrapToolDefinition<TDetails = unknown>(definition: ToolDefinition<any, TDetails>, ctxFactory?: () => ExtensionContext): AgentTool<any, TDetails>;
+/**
+ * Wrap a ToolDefinition into an AgentTool for the core runtime.
+ *
+ * `TParams` is generic here rather than fixed to `any`, so a caller passing a
+ * concretely-typed definition (e.g. one carrying a `contract`, per ADR 0010) gets
+ * `TParams` inferred as that concrete schema. Fixing it to `any` would instantiate
+ * every optional renderer's `Static<TParams>` as `Static<any>`, which TypeScript
+ * does not treat as `any` — it structurally resolves to `unknown` — and that turns a
+ * harmless assignability check into a real error for any definition with a
+ * concretely-typed `renderCall`/`renderResult`.
+ */
+export declare function wrapToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown>(definition: ToolDefinition<TParams, TDetails>, ctxFactory?: () => ExtensionContext): AgentTool<TParams, TDetails>;
 /** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */
 export declare function wrapToolDefinitions(definitions: ToolDefinition<any, any>[], ctxFactory?: () => ExtensionContext): AgentTool<any>[];
 /**

package/dist/core/tools/tool-definition-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition-wrapper.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE/E,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EACpD,UAAU,EAAE,cAAc,CAAC,GAAG,EAAE,QAAQ,CAAC,EACzC,UAAU,CAAC,EAAE,MAAM,gBAAgB,GACjC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAY1B;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EACvC,UAAU,CAAC,EAAE,MAAM,gBAAgB,GACjC,SAAS,CAAC,GAAG,CAAC,EAAE,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAWpG","sourcesContent":["import type { AgentTool } from \"apex-code-agent-core\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\n\n/** Wrap a ToolDefinition into an AgentTool for the core runtime. */\nexport function wrapToolDefinition<TDetails = unknown>(\n\tdefinition: ToolDefinition<any, TDetails>,\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any, TDetails> {\n\treturn {\n\t\tname: definition.name,\n\t\tlabel: definition.label,\n\t\tdescription: definition.description,\n\t\tparameters: definition.parameters,\n\t\tconstrainedSampling: definition.constrainedSampling,\n\t\tprepareArguments: definition.prepareArguments,\n\t\texecutionMode: definition.executionMode,\n\t\texecute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions(\n\tdefinitions: ToolDefinition<any, any>[],\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any>[] {\n\treturn definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));\n}\n\n/**\n * Synthesize a minimal ToolDefinition from an AgentTool.\n *\n * This keeps AgentSession's internal registry definition-first even when a caller\n * provides plain AgentTool overrides that do not include prompt metadata or renderers.\n */\nexport function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters as any,\n\t\tconstrainedSampling: tool.constrainedSampling,\n\t\tprepareArguments: tool.prepareArguments,\n\t\texecutionMode: tool.executionMode,\n\t\texecute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),\n\t};\n}\n"]}
+{"version":3,"file":"tool-definition-wrapper.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,EACvF,UAAU,EAAE,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC7C,UAAU,CAAC,EAAE,MAAM,gBAAgB,GACjC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAY9B;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAClC,WAAW,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EACvC,UAAU,CAAC,EAAE,MAAM,gBAAgB,GACjC,SAAS,CAAC,GAAG,CAAC,EAAE,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAWpG","sourcesContent":["import type { AgentTool } from \"apex-code-agent-core\";\nimport type { TSchema } from \"typebox\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\n\n/**\n * Wrap a ToolDefinition into an AgentTool for the core runtime.\n *\n * `TParams` is generic here rather than fixed to `any`, so a caller passing a\n * concretely-typed definition (e.g. one carrying a `contract`, per ADR 0010) gets\n * `TParams` inferred as that concrete schema. Fixing it to `any` would instantiate\n * every optional renderer's `Static<TParams>` as `Static<any>`, which TypeScript\n * does not treat as `any` — it structurally resolves to `unknown` — and that turns a\n * harmless assignability check into a real error for any definition with a\n * concretely-typed `renderCall`/`renderResult`.\n */\nexport function wrapToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown>(\n\tdefinition: ToolDefinition<TParams, TDetails>,\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<TParams, TDetails> {\n\treturn {\n\t\tname: definition.name,\n\t\tlabel: definition.label,\n\t\tdescription: definition.description,\n\t\tparameters: definition.parameters,\n\t\tconstrainedSampling: definition.constrainedSampling,\n\t\tprepareArguments: definition.prepareArguments,\n\t\texecutionMode: definition.executionMode,\n\t\texecute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions(\n\tdefinitions: ToolDefinition<any, any>[],\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any>[] {\n\treturn definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));\n}\n\n/**\n * Synthesize a minimal ToolDefinition from an AgentTool.\n *\n * This keeps AgentSession's internal registry definition-first even when a caller\n * provides plain AgentTool overrides that do not include prompt metadata or renderers.\n */\nexport function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters as any,\n\t\tconstrainedSampling: tool.constrainedSampling,\n\t\tprepareArguments: tool.prepareArguments,\n\t\texecutionMode: tool.executionMode,\n\t\texecute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),\n\t};\n}\n"]}

package/dist/core/tools/tool-definition-wrapper.js

@@ -1,4 +1,14 @@
-/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
+/**
+ * Wrap a ToolDefinition into an AgentTool for the core runtime.
+ *
+ * `TParams` is generic here rather than fixed to `any`, so a caller passing a
+ * concretely-typed definition (e.g. one carrying a `contract`, per ADR 0010) gets
+ * `TParams` inferred as that concrete schema. Fixing it to `any` would instantiate
+ * every optional renderer's `Static<TParams>` as `Static<any>`, which TypeScript
+ * does not treat as `any` — it structurally resolves to `unknown` — and that turns a
+ * harmless assignability check into a real error for any definition with a
+ * concretely-typed `renderCall`/`renderResult`.
+ */
 export function wrapToolDefinition(definition, ctxFactory) {
     return {
         name: definition.name,

package/dist/core/tools/tool-definition-wrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition-wrapper.js","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CACjC,UAAyC,EACzC,UAAmC,EACR;IAC3B,OAAO;QACN,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,mBAAmB,EAAE,UAAU,CAAC,mBAAmB;QACnD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;QAC7C,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAsB,EAAE,EAAE,CACzE,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAK,UAAU,EAAE,EAAuB,CAAC;KACtG,CAAC;AAAA,CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAClC,WAAuC,EACvC,UAAmC,EAChB;IACnB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AAAA,CACnF;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,IAAoB,EAAgC;IACrG,OAAO;QACN,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAiB;QAClC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;KAC3G,CAAC;AAAA,CACF","sourcesContent":["import type { AgentTool } from \"apex-code-agent-core\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\n\n/** Wrap a ToolDefinition into an AgentTool for the core runtime. */\nexport function wrapToolDefinition<TDetails = unknown>(\n\tdefinition: ToolDefinition<any, TDetails>,\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any, TDetails> {\n\treturn {\n\t\tname: definition.name,\n\t\tlabel: definition.label,\n\t\tdescription: definition.description,\n\t\tparameters: definition.parameters,\n\t\tconstrainedSampling: definition.constrainedSampling,\n\t\tprepareArguments: definition.prepareArguments,\n\t\texecutionMode: definition.executionMode,\n\t\texecute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions(\n\tdefinitions: ToolDefinition<any, any>[],\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any>[] {\n\treturn definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));\n}\n\n/**\n * Synthesize a minimal ToolDefinition from an AgentTool.\n *\n * This keeps AgentSession's internal registry definition-first even when a caller\n * provides plain AgentTool overrides that do not include prompt metadata or renderers.\n */\nexport function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters as any,\n\t\tconstrainedSampling: tool.constrainedSampling,\n\t\tprepareArguments: tool.prepareArguments,\n\t\texecutionMode: tool.executionMode,\n\t\texecute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),\n\t};\n}\n"]}
+{"version":3,"file":"tool-definition-wrapper.js","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CACjC,UAA6C,EAC7C,UAAmC,EACJ;IAC/B,OAAO;QACN,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,mBAAmB,EAAE,UAAU,CAAC,mBAAmB;QACnD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;QAC7C,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAsB,EAAE,EAAE,CACzE,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAK,UAAU,EAAE,EAAuB,CAAC;KACtG,CAAC;AAAA,CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAClC,WAAuC,EACvC,UAAmC,EAChB;IACnB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AAAA,CACnF;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,IAAoB,EAAgC;IACrG,OAAO;QACN,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAiB;QAClC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;KAC3G,CAAC;AAAA,CACF","sourcesContent":["import type { AgentTool } from \"apex-code-agent-core\";\nimport type { TSchema } from \"typebox\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\n\n/**\n * Wrap a ToolDefinition into an AgentTool for the core runtime.\n *\n * `TParams` is generic here rather than fixed to `any`, so a caller passing a\n * concretely-typed definition (e.g. one carrying a `contract`, per ADR 0010) gets\n * `TParams` inferred as that concrete schema. Fixing it to `any` would instantiate\n * every optional renderer's `Static<TParams>` as `Static<any>`, which TypeScript\n * does not treat as `any` — it structurally resolves to `unknown` — and that turns a\n * harmless assignability check into a real error for any definition with a\n * concretely-typed `renderCall`/`renderResult`.\n */\nexport function wrapToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown>(\n\tdefinition: ToolDefinition<TParams, TDetails>,\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<TParams, TDetails> {\n\treturn {\n\t\tname: definition.name,\n\t\tlabel: definition.label,\n\t\tdescription: definition.description,\n\t\tparameters: definition.parameters,\n\t\tconstrainedSampling: definition.constrainedSampling,\n\t\tprepareArguments: definition.prepareArguments,\n\t\texecutionMode: definition.executionMode,\n\t\texecute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions(\n\tdefinitions: ToolDefinition<any, any>[],\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any>[] {\n\treturn definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));\n}\n\n/**\n * Synthesize a minimal ToolDefinition from an AgentTool.\n *\n * This keeps AgentSession's internal registry definition-first even when a caller\n * provides plain AgentTool overrides that do not include prompt metadata or renderers.\n */\nexport function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters as any,\n\t\tconstrainedSampling: tool.constrainedSampling,\n\t\tprepareArguments: tool.prepareArguments,\n\t\texecutionMode: tool.executionMode,\n\t\texecute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),\n\t};\n}\n"]}

package/dist/core/tools/tool-schema.d.ts

@@ -0,0 +1,22 @@
+import { Type } from "typebox";
+import type { ApexToolDefinition } from "./contract.ts";
+declare const toolSchema: Type.TObject<{
+    name: Type.TString;
+}>;
+export interface ToolSchemaTarget {
+    name: string;
+    parameters: unknown;
+}
+export interface ToolSchemaResolver {
+    getTool(name: string): ToolSchemaTarget | undefined;
+    markLoaded(name: string): void;
+}
+/** Resolve one active tool schema and record that it is available on the next request. */
+export declare function loadToolSchema(resolver: ToolSchemaResolver, name: string): ToolSchemaTarget;
+/** Create the model-callable schema loader settled by ADR 0011. */
+export declare function createToolSchemaToolDefinition(resolver: ToolSchemaResolver): ApexToolDefinition<typeof toolSchema>;
+export declare function createToolSchemaTool(resolver: ToolSchemaResolver): import("apex-code-agent-core").AgentTool<Type.TObject<{
+    name: Type.TString;
+}>, unknown>;
+export {};
+//# sourceMappingURL=tool-schema.d.ts.map

package/dist/core/tools/tool-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,QAAA,MAAM,UAAU;;EAEd,CAAC;AAIH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACpD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAO3F;AAED,mEAAmE;AACnE,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,kBAAkB,GAAG,kBAAkB,CAAC,OAAO,UAAU,CAAC,CAyBlH;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB;;aAEhE","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst toolSchema = Type.Object({\n\tname: Type.String({ description: \"Name of the active tool whose parameter schema is needed.\" }),\n});\n\ntype ToolSchemaInput = Static<typeof toolSchema>;\n\nexport interface ToolSchemaTarget {\n\tname: string;\n\tparameters: unknown;\n}\n\nexport interface ToolSchemaResolver {\n\tgetTool(name: string): ToolSchemaTarget | undefined;\n\tmarkLoaded(name: string): void;\n}\n\n/** Resolve one active tool schema and record that it is available on the next request. */\nexport function loadToolSchema(resolver: ToolSchemaResolver, name: string): ToolSchemaTarget {\n\tconst target = resolver.getTool(name);\n\tif (!target) {\n\t\tthrow new Error(`Cannot load schema for inactive or unknown tool \"${name}\"`);\n\t}\n\tresolver.markLoaded(name);\n\treturn target;\n}\n\n/** Create the model-callable schema loader settled by ADR 0011. */\nexport function createToolSchemaToolDefinition(resolver: ToolSchemaResolver): ApexToolDefinition<typeof toolSchema> {\n\treturn {\n\t\tname: \"tool_schema\",\n\t\tlabel: \"tool_schema\",\n\t\tdescription: \"Load the full parameter schema for an active tool before calling it.\",\n\t\tparameters: toolSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set(),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Loading a tool parameter schema\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: true, deferSchema: false },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(_toolCallId, { name }: ToolSchemaInput): Promise<AgentToolResult<unknown>> {\n\t\t\tconst target = loadToolSchema(resolver, name);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: JSON.stringify({ name: target.name, parameters: target.parameters }) }],\n\t\t\t\tdetails: { name: target.name, parameters: target.parameters },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createToolSchemaTool(resolver: ToolSchemaResolver) {\n\treturn wrapToolDefinition(createToolSchemaToolDefinition(resolver));\n}\n"]}

package/dist/core/tools/tool-schema.js

@@ -0,0 +1,45 @@
+import { Type } from "typebox";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const toolSchema = Type.Object({
+    name: Type.String({ description: "Name of the active tool whose parameter schema is needed." }),
+});
+/** Resolve one active tool schema and record that it is available on the next request. */
+export function loadToolSchema(resolver, name) {
+    const target = resolver.getTool(name);
+    if (!target) {
+        throw new Error(`Cannot load schema for inactive or unknown tool "${name}"`);
+    }
+    resolver.markLoaded(name);
+    return target;
+}
+/** Create the model-callable schema loader settled by ADR 0011. */
+export function createToolSchemaToolDefinition(resolver) {
+    return {
+        name: "tool_schema",
+        label: "tool_schema",
+        description: "Load the full parameter schema for an active tool before calling it.",
+        parameters: toolSchema,
+        contract: {
+            capabilities: new Set(),
+            permission: {
+                defaultBehavior: "allow",
+                matches: () => false,
+                describe: () => "Loading a tool parameter schema",
+                ruleForCall: () => null,
+            },
+            context: { resultRecoverable: true, deferSchema: false },
+            evidence: { emits: new Set(), capture: () => [] },
+        },
+        async execute(_toolCallId, { name }) {
+            const target = loadToolSchema(resolver, name);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ name: target.name, parameters: target.parameters }) }],
+                details: { name: target.name, parameters: target.parameters },
+            };
+        },
+    };
+}
+export function createToolSchemaTool(resolver) {
+    return wrapToolDefinition(createToolSchemaToolDefinition(resolver));
+}
+//# sourceMappingURL=tool-schema.js.map

package/dist/core/tools/tool-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.js","sourceRoot":"","sources":["../../../src/core/tools/tool-schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2DAA2D,EAAE,CAAC;CAC/F,CAAC,CAAC;AAcH,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,QAA4B,EAAE,IAAY,EAAoB;IAC5F,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,oDAAoD,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC;AAAA,CACd;AAED,mEAAmE;AACnE,MAAM,UAAU,8BAA8B,CAAC,QAA4B,EAAyC;IACnH,OAAO;QACN,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE,sEAAsE;QACnF,UAAU,EAAE,UAAU;QACtB,QAAQ,EAAE;YACT,YAAY,EAAE,IAAI,GAAG,EAAE;YACvB,UAAU,EAAE;gBACX,eAAe,EAAE,OAAO;gBACxB,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK;gBACpB,QAAQ,EAAE,GAAG,EAAE,CAAC,iCAAiC;gBACjD,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI;aACvB;YACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE;YACxD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;SACjD;QACD,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,EAAmB,EAAqC;YACxF,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC9C,OAAO;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;gBACvG,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE;aAC7D,CAAC;QAAA,CACF;KACD,CAAC;AAAA,CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,QAA4B,EAAE;IAClE,OAAO,kBAAkB,CAAC,8BAA8B,CAAC,QAAQ,CAAC,CAAC,CAAC;AAAA,CACpE","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst toolSchema = Type.Object({\n\tname: Type.String({ description: \"Name of the active tool whose parameter schema is needed.\" }),\n});\n\ntype ToolSchemaInput = Static<typeof toolSchema>;\n\nexport interface ToolSchemaTarget {\n\tname: string;\n\tparameters: unknown;\n}\n\nexport interface ToolSchemaResolver {\n\tgetTool(name: string): ToolSchemaTarget | undefined;\n\tmarkLoaded(name: string): void;\n}\n\n/** Resolve one active tool schema and record that it is available on the next request. */\nexport function loadToolSchema(resolver: ToolSchemaResolver, name: string): ToolSchemaTarget {\n\tconst target = resolver.getTool(name);\n\tif (!target) {\n\t\tthrow new Error(`Cannot load schema for inactive or unknown tool \"${name}\"`);\n\t}\n\tresolver.markLoaded(name);\n\treturn target;\n}\n\n/** Create the model-callable schema loader settled by ADR 0011. */\nexport function createToolSchemaToolDefinition(resolver: ToolSchemaResolver): ApexToolDefinition<typeof toolSchema> {\n\treturn {\n\t\tname: \"tool_schema\",\n\t\tlabel: \"tool_schema\",\n\t\tdescription: \"Load the full parameter schema for an active tool before calling it.\",\n\t\tparameters: toolSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set(),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Loading a tool parameter schema\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: true, deferSchema: false },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(_toolCallId, { name }: ToolSchemaInput): Promise<AgentToolResult<unknown>> {\n\t\t\tconst target = loadToolSchema(resolver, name);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: JSON.stringify({ name: target.name, parameters: target.parameters }) }],\n\t\t\t\tdetails: { name: target.name, parameters: target.parameters },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createToolSchemaTool(resolver: ToolSchemaResolver) {\n\treturn wrapToolDefinition(createToolSchemaToolDefinition(resolver));\n}\n"]}

package/dist/core/tools/web-fetch.d.ts

@@ -0,0 +1,26 @@
+import { type Static, Type } from "typebox";
+import type { ApexToolDefinition } from "./contract.ts";
+declare const webFetchSchema: Type.TObject<{
+    url: Type.TString;
+}>;
+export type WebFetchInput = Static<typeof webFetchSchema>;
+export interface WebFetchDetails {
+    url: string;
+    status: number;
+    truncated: boolean;
+}
+export interface WebFetchOperations {
+    fetch(url: string, signal?: AbortSignal): Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+export interface WebFetchToolOptions {
+    operations?: WebFetchOperations;
+}
+export declare function createWebFetchToolDefinition(options?: WebFetchToolOptions): ApexToolDefinition<typeof webFetchSchema, WebFetchDetails>;
+export declare function createWebFetchTool(options?: WebFetchToolOptions): import("apex-code-agent-core").AgentTool<Type.TObject<{
+    url: Type.TString;
+}>, WebFetchDetails>;
+export {};
+//# sourceMappingURL=web-fetch.d.ts.map

package/dist/core/tools/web-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/web-fetch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAIxD,QAAA,MAAM,cAAc;;EAElB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpF;AAwBD,MAAM,WAAW,mBAAmB;IACnC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,CAAC,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,OAAO,cAAc,EAAE,eAAe,CAAC,CAkC5D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB;;qBAE/D","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, formatSize, truncateHead } from \"./truncate.ts\";\n\nconst webFetchSchema = Type.Object({\n\turl: Type.String({ description: \"The absolute URL to fetch (including scheme, e.g. https://).\" }),\n});\n\nexport type WebFetchInput = Static<typeof webFetchSchema>;\n\nexport interface WebFetchDetails {\n\turl: string;\n\tstatus: number;\n\ttruncated: boolean;\n}\n\nexport interface WebFetchOperations {\n\tfetch(url: string, signal?: AbortSignal): Promise<{ status: number; text: string }>;\n}\n\n/**\n * Runs in the same process as every other tool -- the sandboxed child, not the\n * supervisor. `globalThis.fetch` is undici's global fetch, made proxy-aware by\n * `configureHttpDispatcher` (an `EnvHttpProxyAgent` reading HTTP_PROXY/HTTPS_PROXY)\n * at CLI startup, including in `core/sandbox/child-entry.ts`'s sandboxed launch.\n * That is what routes an allowed host through the sandbox's allowlist proxy and\n * leaves a disallowed one with no route at all -- this tool does not implement or\n * bypass that boundary itself; it only participates in it via the ordinary fetch\n * path, deliberately never opening a raw socket that could sidestep the proxy.\n */\nconst defaultWebFetchOperations: WebFetchOperations = {\n\tasync fetch(url, signal) {\n\t\tconst response = await fetch(url, { signal });\n\t\treturn { status: response.status, text: await response.text() };\n\t},\n};\n\nfunction hostAndPath(url: string): string {\n\tconst parsed = new URL(url);\n\treturn `${parsed.hostname}${parsed.pathname}`;\n}\n\nexport interface WebFetchToolOptions {\n\toperations?: WebFetchOperations;\n}\n\nexport function createWebFetchToolDefinition(\n\toptions?: WebFetchToolOptions,\n): ApexToolDefinition<typeof webFetchSchema, WebFetchDetails> {\n\tconst ops = options?.operations ?? defaultWebFetchOperations;\n\treturn {\n\t\tname: \"web_fetch\",\n\t\tlabel: \"web_fetch\",\n\t\tdescription: \"Fetch the text contents of a URL over HTTP(S).\",\n\t\tparameters: webFetchSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"net\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(hostAndPath(params.url), ruleContent, { dot: true }),\n\t\t\t\tdescribe: (ruleContent) => `Fetch URLs matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => hostAndPath(params.url),\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ url }: WebFetchInput,\n\t\t\tsignal?: AbortSignal,\n\t\t): Promise<AgentToolResult<WebFetchDetails>> {\n\t\t\tconst { status, text } = await ops.fetch(url, signal);\n\t\t\tconst truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES });\n\t\t\tconst suffix = truncation.truncated\n\t\t\t\t? `\\n\\n[truncated: showing ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}]`\n\t\t\t\t: \"\";\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `${truncation.content}${suffix}` }],\n\t\t\t\tdetails: { url, status, truncated: truncation.truncated },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createWebFetchTool(options?: WebFetchToolOptions) {\n\treturn wrapToolDefinition(createWebFetchToolDefinition(options));\n}\n"]}

package/dist/core/tools/web-fetch.js

@@ -0,0 +1,62 @@
+import { minimatch } from "minimatch";
+import { Type } from "typebox";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
+const webFetchSchema = Type.Object({
+    url: Type.String({ description: "The absolute URL to fetch (including scheme, e.g. https://)." }),
+});
+/**
+ * Runs in the same process as every other tool -- the sandboxed child, not the
+ * supervisor. `globalThis.fetch` is undici's global fetch, made proxy-aware by
+ * `configureHttpDispatcher` (an `EnvHttpProxyAgent` reading HTTP_PROXY/HTTPS_PROXY)
+ * at CLI startup, including in `core/sandbox/child-entry.ts`'s sandboxed launch.
+ * That is what routes an allowed host through the sandbox's allowlist proxy and
+ * leaves a disallowed one with no route at all -- this tool does not implement or
+ * bypass that boundary itself; it only participates in it via the ordinary fetch
+ * path, deliberately never opening a raw socket that could sidestep the proxy.
+ */
+const defaultWebFetchOperations = {
+    async fetch(url, signal) {
+        const response = await fetch(url, { signal });
+        return { status: response.status, text: await response.text() };
+    },
+};
+function hostAndPath(url) {
+    const parsed = new URL(url);
+    return `${parsed.hostname}${parsed.pathname}`;
+}
+export function createWebFetchToolDefinition(options) {
+    const ops = options?.operations ?? defaultWebFetchOperations;
+    return {
+        name: "web_fetch",
+        label: "web_fetch",
+        description: "Fetch the text contents of a URL over HTTP(S).",
+        parameters: webFetchSchema,
+        contract: {
+            capabilities: new Set(["net"]),
+            permission: {
+                defaultBehavior: "ask",
+                matches: (ruleContent, params) => minimatch(hostAndPath(params.url), ruleContent, { dot: true }),
+                describe: (ruleContent) => `Fetch URLs matching "${ruleContent}"`,
+                ruleForCall: (params) => hostAndPath(params.url),
+            },
+            context: { resultRecoverable: false, deferSchema: true },
+            evidence: { emits: new Set(), capture: () => [] },
+        },
+        async execute(_toolCallId, { url }, signal) {
+            const { status, text } = await ops.fetch(url, signal);
+            const truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES });
+            const suffix = truncation.truncated
+                ? `\n\n[truncated: showing ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}]`
+                : "";
+            return {
+                content: [{ type: "text", text: `${truncation.content}${suffix}` }],
+                details: { url, status, truncated: truncation.truncated },
+            };
+        },
+    };
+}
+export function createWebFetchTool(options) {
+    return wrapToolDefinition(createWebFetchToolDefinition(options));
+}
+//# sourceMappingURL=web-fetch.js.map

package/dist/core/tools/web-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.js","sourceRoot":"","sources":["../../../src/core/tools/web-fetch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, formatSize, truncateHead } from \"./truncate.ts\";\n\nconst webFetchSchema = Type.Object({\n\turl: Type.String({ description: \"The absolute URL to fetch (including scheme, e.g. https://).\" }),\n});\n\nexport type WebFetchInput = Static<typeof webFetchSchema>;\n\nexport interface WebFetchDetails {\n\turl: string;\n\tstatus: number;\n\ttruncated: boolean;\n}\n\nexport interface WebFetchOperations {\n\tfetch(url: string, signal?: AbortSignal): Promise<{ status: number; text: string }>;\n}\n\n/**\n * Runs in the same process as every other tool -- the sandboxed child, not the\n * supervisor. `globalThis.fetch` is undici's global fetch, made proxy-aware by\n * `configureHttpDispatcher` (an `EnvHttpProxyAgent` reading HTTP_PROXY/HTTPS_PROXY)\n * at CLI startup, including in `core/sandbox/child-entry.ts`'s sandboxed launch.\n * That is what routes an allowed host through the sandbox's allowlist proxy and\n * leaves a disallowed one with no route at all -- this tool does not implement or\n * bypass that boundary itself; it only participates in it via the ordinary fetch\n * path, deliberately never opening a raw socket that could sidestep the proxy.\n */\nconst defaultWebFetchOperations: WebFetchOperations = {\n\tasync fetch(url, signal) {\n\t\tconst response = await fetch(url, { signal });\n\t\treturn { status: response.status, text: await response.text() };\n\t},\n};\n\nfunction hostAndPath(url: string): string {\n\tconst parsed = new URL(url);\n\treturn `${parsed.hostname}${parsed.pathname}`;\n}\n\nexport interface WebFetchToolOptions {\n\toperations?: WebFetchOperations;\n}\n\nexport function createWebFetchToolDefinition(\n\toptions?: WebFetchToolOptions,\n): ApexToolDefinition<typeof webFetchSchema, WebFetchDetails> {\n\tconst ops = options?.operations ?? defaultWebFetchOperations;\n\treturn {\n\t\tname: \"web_fetch\",\n\t\tlabel: \"web_fetch\",\n\t\tdescription: \"Fetch the text contents of a URL over HTTP(S).\",\n\t\tparameters: webFetchSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"net\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(hostAndPath(params.url), ruleContent, { dot: true }),\n\t\t\t\tdescribe: (ruleContent) => `Fetch URLs matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => hostAndPath(params.url),\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ url }: WebFetchInput,\n\t\t\tsignal?: AbortSignal,\n\t\t): Promise<AgentToolResult<WebFetchDetails>> {\n\t\t\tconst { status, text } = await ops.fetch(url, signal);\n\t\t\tconst truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES });\n\t\t\tconst suffix = truncation.truncated\n\t\t\t\t? `\\n\\n[truncated: showing ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}]`\n\t\t\t\t: \"\";\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: `${truncation.content}${suffix}` }],\n\t\t\t\tdetails: { url, status, truncated: truncation.truncated },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createWebFetchTool(options?: WebFetchToolOptions) {\n\treturn wrapToolDefinition(createWebFetchToolDefinition(options));\n}\n"]}

package/dist/core/tools/web-search-exa.d.ts

@@ -0,0 +1,33 @@
+import type { WebSearchOperations } from "./web-search.ts";
+/** Exa's hosted search endpoint. */
+export declare const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+/** Host of {@link EXA_SEARCH_ENDPOINT}, for the sandbox network allowlist. */
+export declare const EXA_SEARCH_HOST = "api.exa.ai";
+/** Exa's own default is 10; matching it keeps an unconfigured session predictable. */
+export declare const DEFAULT_EXA_RESULT_COUNT = 10;
+/**
+ * Snippet budget per result. Exa returns whole page text when asked, which is the
+ * wrong unit for a search result -- ten full pages would dwarf every other tool
+ * result in the context window. 800 characters is roughly a paragraph, enough for
+ * the model to judge relevance and decide whether to spend a `web_fetch` on it.
+ */
+export declare const DEFAULT_EXA_SNIPPET_CHARACTERS = 800;
+export interface ExaWebSearchOptions {
+    /** Resolved key, never a `$VAR` reference -- resolution happens before this call. */
+    apiKey: string;
+    /** Override for an Exa-compatible endpoint. Defaults to {@link EXA_SEARCH_ENDPOINT}. */
+    endpoint?: string;
+    numResults?: number;
+    snippetMaxCharacters?: number;
+}
+/**
+ * Exa-backed `web_search` backend.
+ *
+ * Reaches the network through `globalThis.fetch` for the same reason `web_fetch`
+ * does: that is the dispatcher `configureHttpDispatcher` made proxy-aware, so an
+ * allowlisted host routes through the sandbox proxy and a disallowed one has no
+ * route at all. Opening a raw socket here would sidestep a boundary this tool is
+ * supposed to sit behind.
+ */
+export declare function createExaWebSearchOperations(options: ExaWebSearchOptions): WebSearchOperations;
+//# sourceMappingURL=web-search-exa.d.ts.map

package/dist/core/tools/web-search-exa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search-exa.d.ts","sourceRoot":"","sources":["../../../src/core/tools/web-search-exa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAmB,MAAM,iBAAiB,CAAC;AAE5E,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D,8EAA8E;AAC9E,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,MAAM,WAAW,mBAAmB;IACnC,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAwED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAgD9F","sourcesContent":["import type { WebSearchOperations, WebSearchResult } from \"./web-search.ts\";\n\n/** Exa's hosted search endpoint. */\nexport const EXA_SEARCH_ENDPOINT = \"https://api.exa.ai/search\";\n\n/** Host of {@link EXA_SEARCH_ENDPOINT}, for the sandbox network allowlist. */\nexport const EXA_SEARCH_HOST = \"api.exa.ai\";\n\n/** Exa's own default is 10; matching it keeps an unconfigured session predictable. */\nexport const DEFAULT_EXA_RESULT_COUNT = 10;\n\n/**\n * Snippet budget per result. Exa returns whole page text when asked, which is the\n * wrong unit for a search result -- ten full pages would dwarf every other tool\n * result in the context window. 800 characters is roughly a paragraph, enough for\n * the model to judge relevance and decide whether to spend a `web_fetch` on it.\n */\nexport const DEFAULT_EXA_SNIPPET_CHARACTERS = 800;\n\nexport interface ExaWebSearchOptions {\n\t/** Resolved key, never a `$VAR` reference -- resolution happens before this call. */\n\tapiKey: string;\n\t/** Override for an Exa-compatible endpoint. Defaults to {@link EXA_SEARCH_ENDPOINT}. */\n\tendpoint?: string;\n\tnumResults?: number;\n\tsnippetMaxCharacters?: number;\n}\n\n/** Separator between highlights, which are non-contiguous passages rather than prose. */\nconst HIGHLIGHT_SEPARATOR = \" … \";\n\n/** The subset of Exa's `/search` response this adapter reads. */\ninterface ExaSearchResult {\n\ttitle?: string | null;\n\turl?: string | null;\n\ttext?: string | null;\n\thighlights?: string[] | null;\n}\n\ninterface ExaSearchResponse {\n\tresults?: ExaSearchResult[] | null;\n}\n\nfunction isAbortError(error: unknown): boolean {\n\treturn error instanceof Error && error.name === \"AbortError\";\n}\n\nfunction hostOf(endpoint: string): string {\n\ttry {\n\t\treturn new URL(endpoint).host;\n\t} catch {\n\t\treturn endpoint;\n\t}\n}\n\n/**\n * Text arrives with the source document's line structure intact. Collapsing it to a\n * single line costs nothing in meaning and keeps a ten-result list readable as a list\n * rather than ten wrapped blocks.\n */\nfunction toSnippet(text: string | null | undefined, maxCharacters: number): string {\n\tif (!text) return \"\";\n\tconst collapsed = text.replace(/\\s+/g, \" \").trim();\n\tif (collapsed.length <= maxCharacters) return collapsed;\n\tconst capped = collapsed.slice(0, maxCharacters);\n\t// End on a whole word when one fits: a snippet cut mid-word (\"specificatio\")\n\t// reads as corruption rather than truncation. A cap that lands inside the first\n\t// word has no boundary to retreat to, so the hard cut stands.\n\tconst boundary = capped.lastIndexOf(\" \");\n\treturn boundary > 0 ? capped.slice(0, boundary) : capped;\n}\n\n/**\n * Prefer highlights, fall back to page text.\n *\n * `contents.text` returns the top of the document, which on a real page is navigation\n * chrome and a repeat of the title before any content. Highlights are the passages Exa\n * judged relevant to the query, so they are both shorter and more useful. Text remains\n * the fallback because a page can yield no highlights, and an empty snippet is worse\n * than a boilerplate one.\n */\nfunction snippetFor(result: ExaSearchResult, maxCharacters: number): string {\n\tconst highlights = (result.highlights ?? []).map((highlight) => highlight?.trim()).filter(Boolean);\n\tif (highlights.length > 0) return toSnippet(highlights.join(HIGHLIGHT_SEPARATOR), maxCharacters);\n\treturn toSnippet(result.text, maxCharacters);\n}\n\nfunction toWebSearchResults(payload: ExaSearchResponse, maxCharacters: number): WebSearchResult[] {\n\tconst results: WebSearchResult[] = [];\n\tfor (const result of payload.results ?? []) {\n\t\tconst url = result?.url?.trim();\n\t\t// A result the model cannot cite or fetch is worse than one fewer result.\n\t\tif (!url) continue;\n\t\tresults.push({ title: result.title?.trim() || url, url, snippet: snippetFor(result, maxCharacters) });\n\t}\n\treturn results;\n}\n\n/**\n * Exa-backed `web_search` backend.\n *\n * Reaches the network through `globalThis.fetch` for the same reason `web_fetch`\n * does: that is the dispatcher `configureHttpDispatcher` made proxy-aware, so an\n * allowlisted host routes through the sandbox proxy and a disallowed one has no\n * route at all. Opening a raw socket here would sidestep a boundary this tool is\n * supposed to sit behind.\n */\nexport function createExaWebSearchOperations(options: ExaWebSearchOptions): WebSearchOperations {\n\tconst apiKey = options.apiKey?.trim();\n\tif (!apiKey) {\n\t\tthrow new Error(\"Exa web search requires an API key; none was resolved.\");\n\t}\n\tconst endpoint = options.endpoint ?? EXA_SEARCH_ENDPOINT;\n\tconst host = hostOf(endpoint);\n\tconst numResults = options.numResults ?? DEFAULT_EXA_RESULT_COUNT;\n\tconst snippetMaxCharacters = options.snippetMaxCharacters ?? DEFAULT_EXA_SNIPPET_CHARACTERS;\n\n\treturn {\n\t\tasync search(query, signal) {\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await fetch(endpoint, {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: { \"content-type\": \"application/json\", \"x-api-key\": apiKey },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tquery,\n\t\t\t\t\t\tnumResults,\n\t\t\t\t\t\tcontents: {\n\t\t\t\t\t\t\t// `query` steers which passages Exa picks. The deprecated\n\t\t\t\t\t\t\t// `numSentences` and `highlightsPerUrl` options are deliberately\n\t\t\t\t\t\t\t// unused; the latter is documented as ignored.\n\t\t\t\t\t\t\thighlights: { query, maxCharacters: snippetMaxCharacters },\n\t\t\t\t\t\t\ttext: { maxCharacters: snippetMaxCharacters },\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t\tsignal,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (isAbortError(error)) throw error;\n\t\t\t\t// `fetch failed` alone names neither the host nor the remedy. The sandbox\n\t\t\t\t// refusal wrapper's message, when it produced one, is preserved verbatim here.\n\t\t\t\tconst detail = error instanceof Error ? error.message : String(error);\n\t\t\t\tthrow new Error(`web_search request to ${host} failed: ${detail}`, { cause: error });\n\t\t\t}\n\n\t\t\tif (!response.ok) {\n\t\t\t\t// The body can echo request fields, so only the status is reported -- a\n\t\t\t\t// pasted-through body is how an API key ends up in a transcript.\n\t\t\t\tthrow new Error(`web_search request to ${host} failed with HTTP ${response.status}.`);\n\t\t\t}\n\n\t\t\tconst payload = (await response.json()) as ExaSearchResponse;\n\t\t\treturn toWebSearchResults(payload, snippetMaxCharacters);\n\t\t},\n\t};\n}\n"]}