@absolutejs/ai 0.0.10 → 0.0.12

package/dist/src/ai/tools/codeMode.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `codeModeTool` — Code Mode for AI agents.
+ *
+ * Instead of exposing N tools to the model and having it call them one
+ * at a time (N round-trips per turn, N tool-call tokens, the model has
+ * to track intermediate state in context), Code Mode exposes ONE tool:
+ * `run_code`. The model sees the typed TypeScript signatures of all
+ * underlying tools and emits a single function that chains them.
+ *
+ * Pattern was popularized by Cloudflare's Dynamic Workers (April 2026
+ * blog post: "100× faster than containers"). Anthropic's programmatic
+ * tool calling is the same idea — execution pauses on a sub-tool call,
+ * the API yields a tool_use, you return a result, execution resumes.
+ * Both vendors report ~80% token reduction on multi-tool turns.
+ *
+ * ```ts
+ * import { codeModeTool } from '@absolutejs/ai/tools';
+ *
+ * const tools = {
+ *   run_code: codeModeTool({
+ *     timeout: 5000,
+ *     tools: {
+ *       search_products: {
+ *         description: 'Full-text search the product catalogue.',
+ *         tsSignature: '(query: string) => Promise<Product[]>',
+ *         handler: async (q) => db.products.search(q as string),
+ *       },
+ *       get_product: {
+ *         description: 'Fetch one product by id.',
+ *         tsSignature: '(id: string) => Promise<Product | null>',
+ *         handler: async (id) => db.products.findById(id as string),
+ *       },
+ *     },
+ *     types: `
+ *       type Product = { id: string; name: string; price: number };
+ *     `,
+ *   }),
+ * };
+ * ```
+ *
+ * The model emits a single function:
+ *
+ * ```js
+ * const items = await search_products('hat');
+ * const cheapest = items.sort((a, b) => a.price - b.price)[0];
+ * const detail = await get_product(cheapest.id);
+ * return { name: detail.name, price: detail.price };
+ * ```
+ *
+ * One sandbox eval. Two host-fn calls. One returned value. The model's
+ * context only ever sees the final return — intermediate tool results
+ * don't enter the conversation window, so multi-step workflows are
+ * dramatically cheaper.
+ *
+ * Each underlying tool's `handler` runs on the HOST side (not in the
+ * sandbox). Async host fns work on both FFI (via the 0.4 pump) and
+ * Worker backends since isolated-jsc 0.4+. Errors thrown by host
+ * handlers propagate into the sandbox as JS Errors the model can
+ * catch and recover from.
+ */
+import type { AIToolDefinition } from "../../../types/ai";
+/**
+ * One callable surfaced to the sandbox. The `tsSignature` shows up in
+ * the model-visible description; `handler` runs on the host when the
+ * sandbox calls it.
+ */
+export type CodeModeHostTool = {
+    /** One-line human description of what this tool does. */
+    description: string;
+    /** TypeScript signature shown to the model. Example:
+     * `'(query: string, options?: { limit?: number }) => Promise<Item[]>'`.
+     * The model writes JS against this signature; we don't enforce it at
+     * runtime — type-check is the model's responsibility. */
+    tsSignature: string;
+    /** Host implementation. Receives positional args as the model passed
+     * them. Return value is structure-cloned back into the sandbox. */
+    handler: (...args: unknown[]) => unknown;
+};
+/** Options for {@link codeModeTool}. */
+export type CodeModeToolOptions = {
+    /** Map of host-tool name → {@link CodeModeHostTool}. */
+    tools: Record<string, CodeModeHostTool>;
+    /**
+     * Optional shared TypeScript declarations stitched into the prompt
+     * (type aliases, interfaces, etc.) so signatures can reference them.
+     * Use raw TS source; no parsing happens host-side.
+     */
+    types?: string;
+    /**
+     * Per-isolate heap memory cap (MB). Default 64. As with the regular
+     * code-execution tool, FFI's cold heap is much smaller than Worker's,
+     * but per-call retention scales similarly.
+     */
+    memoryLimit?: number;
+    /** Wall-clock timeout per `run_code` call (ms). Default 5000. */
+    timeout?: number;
+    /**
+     * isolated-jsc backend. Defaults to `'auto'`. Since isolated-jsc 0.4
+     * both backends support async host fns, so the choice is purely
+     * about cold spawn (FFI wins ~6×) vs Web APIs availability (Worker
+     * has `URL` / `TextEncoder` / `WebSocket`; FFI does not).
+     */
+    backend?: "auto" | "ffi" | "worker";
+    /**
+     * Override the auto-generated description. By default we emit the
+     * model-facing prompt: a short instruction header + the host fn
+     * signatures + any shared `types`.
+     */
+    description?: string;
+    /** Pool size cap. Default 8. */
+    poolSize?: number;
+    /** Recycle the isolate after N successful runs. Default 50. */
+    recycleAfter?: number;
+};
+export declare const codeModeTool: (options: CodeModeToolOptions) => AIToolDefinition;

package/dist/src/ai/tools/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@absolutejs/ai/tools` — first-party `AIToolDefinition`s ready to drop
+ * into the `tools: {...}` map you hand to `streamAI` / `generateAI`.
+ *
+ * - {@link codeExecutionTool} — execute model-generated JavaScript in a
+ *   sandboxed `@absolutejs/isolated-jsc` isolate. Optional peer; install
+ *   `@absolutejs/isolated-jsc` to use it.
+ * - {@link codeModeTool} — "Code Mode" wrapper for N host tools: model
+ *   sees typed TS signatures, emits one function chaining several
+ *   tool calls, ~80% token reduction vs N separate tool calls.
+ */
+export { codeExecutionTool, type CodeExecutionToolOptions, } from "./codeExecution";
+export { type CodeModeHostTool, codeModeTool, type CodeModeToolOptions, } from "./codeMode";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/ai",
-	"version": "0.0.10",
+	"version": "0.0.12",
 	"description": "AI runtime, providers, streaming, and framework adapters extracted from AbsoluteJS",
 	"license": "BSL-1.1",
 	"type": "module",
@@ -62,6 +62,10 @@
 		"./providers": {
 			"import": "./dist/ai/providers/openaiCompatible.js",
 			"types": "./dist/src/ai/providers/openaiCompatible.d.ts"
+		},
+		"./tools": {
+			"import": "./dist/ai/tools/index.js",
+			"types": "./dist/src/ai/tools/index.d.ts"
 		}
 	},
 	"dependencies": {
@@ -69,6 +73,7 @@
 		"@absolutejs/sync": "0.7.0"
 	},
 	"peerDependencies": {
+		"@absolutejs/isolated-jsc": ">= 0.4.0",
 		"@angular/core": "^21.0.0",
 		"elysia": "^1.4.18",
 		"react": "^19.2.0",
@@ -76,6 +81,9 @@
 		"vue": "^3.5.27"
 	},
 	"peerDependenciesMeta": {
+		"@absolutejs/isolated-jsc": {
+			"optional": true
+		},
 		"@angular/core": {
 			"optional": true
 		},
@@ -91,21 +99,22 @@
 	},
 	"devDependencies": {
 		"@absolutejs/absolute": "^0.19.0-beta.1051",
+		"@absolutejs/isolated-jsc": "0.6.0",
 		"@angular/core": "^21.0.0",
+		"@eslint/js": "^10.0.1",
 		"@types/bun": "1.3.9",
 		"@types/react": "19.2.0",
 		"elysia": "1.4.18",
-		"react": "19.2.1",
-		"svelte": "5.55.0",
-		"typescript": "^5.9.3",
-		"vue": "3.5.27",
-		"@eslint/js": "^10.0.1",
 		"eslint": "^10.0.3",
+		"eslint-plugin-absolute": "^0.2.6",
+		"eslint-plugin-promise": "^7.2.1",
 		"globals": "^17.4.0",
 		"prettier": "^3.5.3",
+		"react": "19.2.1",
+		"svelte": "5.55.0",
+		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.56.1",
-		"eslint-plugin-absolute": "^0.2.6",
-		"eslint-plugin-promise": "^7.2.1"
+		"vue": "3.5.27"
 	},
 	"scripts": {
 		"build": "bun run scripts/build.ts",