/** * Zero-dependency browser counterpart to `createCodeTool` from `./ai`. * * Returns a plain JSON Schema tool descriptor instead of an AI SDK `Tool`. * No `ai`, no `zod` — just JSON Schema and browser APIs. JSON Schema is used * for generated types only; this helper does not perform runtime validation. */ import { generateTypesFromJsonSchema, type JsonSchemaToolDescriptor, type JsonSchemaToolDescriptors } from "./json-schema-types"; import { runCode } from "./run-code"; import { sanitizeToolName } from "./utils"; import type { Executor, ResolvedProvider } from "./executor-types"; import type { CodeInput, CodeOutput } from "./shared"; import { IframeSandboxExecutor } from "./iframe-executor"; // -- Types -- /** * A JSON Schema tool descriptor with an execute function attached. */ export interface JsonSchemaExecutableToolDescriptor extends JsonSchemaToolDescriptor { name?: string; execute: (args: Record) => Promise; } export type JsonSchemaExecutableToolDescriptors = Record< string, JsonSchemaExecutableToolDescriptor >; interface ApprovalAwareJsonSchemaExecutableToolDescriptor extends JsonSchemaExecutableToolDescriptor { needsApproval?: boolean | ((...args: unknown[]) => unknown); } type ApprovalAwareJsonSchemaExecutableToolDescriptors = Record< string, ApprovalAwareJsonSchemaExecutableToolDescriptor >; export interface BrowserCodeToolDescriptor { name: string; description: string; inputSchema: { type: "object"; properties: { code: { type: "string"; description: string }; }; required: ["code"]; }; outputSchema: { type: "object"; properties: { result: { description: string }; logs: { type: "array"; items: { type: "string" }; description: string; }; }; required: ["result"]; }; execute: (args: CodeInput) => Promise; } export interface CreateBrowserCodeToolOptions { /** * Tools available inside the sandbox via `codemode.*`. * * Accepts either an array (like `listTools()` returns) with `name` on each item, * or an object keyed by tool name (like `createCodeTool` expects). */ tools: | ApprovalAwareJsonSchemaExecutableToolDescriptor[] | ApprovalAwareJsonSchemaExecutableToolDescriptors; /** * Executor to use. Defaults to a new `IframeSandboxExecutor`. */ executor?: Executor; /** * Custom tool description. Use `{{types}}` as a placeholder for generated type definitions. */ description?: string; } // -- Implementation -- const DEFAULT_DESCRIPTION = `Execute code to achieve a goal. Available: {{types}} Write an async arrow function in JavaScript that returns the result. Do NOT use TypeScript syntax — no type annotations, interfaces, or generics. Do NOT define named functions then call them — just write the arrow function body directly. Example: async () => { const r = await codemode.searchWeb({ query: "test" }); return r; }`; function toRecord( tools: | ApprovalAwareJsonSchemaExecutableToolDescriptor[] | ApprovalAwareJsonSchemaExecutableToolDescriptors ): ApprovalAwareJsonSchemaExecutableToolDescriptors { if (!Array.isArray(tools)) return tools; const record: ApprovalAwareJsonSchemaExecutableToolDescriptors = {}; for (const tool of tools) { if (!tool.name) { throw new Error( "Tool descriptors in array form must have a `name` property" ); } record[tool.name] = tool; } return record; } function hasNeedsApproval(tool: Record): boolean { return ( tool.needsApproval === true || typeof tool.needsApproval === "function" ); } /** * Create a codemode tool descriptor using only JSON Schema and browser APIs. * * This is the browser counterpart to `createCodeTool` from * `@cloudflare/codemode/ai`. * It returns a plain object with `{ name, description, inputSchema, outputSchema, execute }` * that can be passed to any framework — including * `navigator.modelContext.registerTool()`. * * Tools with `needsApproval` are excluded, matching the current codemode * behavior for approval-gated tools. JSON Schema is used for prompt/type * generation only and is not enforced at runtime. */ export function createBrowserCodeTool( options: CreateBrowserCodeToolOptions ): BrowserCodeToolDescriptor { const allTools = toRecord(options.tools); const toolMap: JsonSchemaExecutableToolDescriptors = {}; for (const [name, tool] of Object.entries(allTools)) { if (!hasNeedsApproval(tool as unknown as Record)) { toolMap[name] = tool; } } const executor = options.executor ?? new IframeSandboxExecutor(); // Generate TypeScript type descriptions for the LLM prompt const schemaOnly: JsonSchemaToolDescriptors = {}; for (const [name, tool] of Object.entries(toolMap)) { schemaOnly[name] = { description: tool.description, inputSchema: tool.inputSchema, outputSchema: tool.outputSchema }; } const types = generateTypesFromJsonSchema(schemaOnly); const description = (options.description ?? DEFAULT_DESCRIPTION).replace( "{{types}}", types ); // Extract execute functions, keyed by sanitized name const fns: Record Promise> = {}; const sanitizedNames = new Map(); for (const [name, tool] of Object.entries(toolMap)) { if (tool.execute) { const sanitizedName = sanitizeToolName(name); const existingName = sanitizedNames.get(sanitizedName); if (existingName && existingName !== name) { throw new Error( `Tool names "${existingName}" and "${name}" both sanitize to "${sanitizedName}"` ); } sanitizedNames.set(sanitizedName, name); fns[sanitizedName] = tool.execute as (args: unknown) => Promise; } } const resolvedProviders: ResolvedProvider[] = [{ name: "codemode", fns }]; return { name: "codemode", description, inputSchema: { type: "object", properties: { code: { type: "string", description: "JavaScript async arrow function to execute" } }, required: ["code"] }, outputSchema: { type: "object", properties: { result: { description: "The return value of the executed code" }, logs: { type: "array", items: { type: "string" }, description: "Console output captured during execution" } }, required: ["result"] }, execute: async ({ code }) => runCode({ code, executor, providers: resolvedProviders }) }; }