@cogitator-ai/wasm-tools 0.2.8 → 0.3.1

package/README.md

@@ -2,77 +2,208 @@
 
 WASM-based tools for Cogitator agents. Secure, sandboxed tool execution using WebAssembly.
 
+## Features
+
+- 🚀 **100-500x faster cold start** than Docker containers
+- 🔒 **Memory-safe execution** in isolated Extism sandbox
+- 📦 **~20x lower memory footprint** compared to containers
+- 🛠️ **Custom tool framework** - create your own WASM tools
+
 ## Installation
 
 ```bash
 pnpm add @cogitator-ai/wasm-tools
 ```
 
-## Usage
+## Quick Start
 
-This package provides WASM tool configurations to be used with `@cogitator-ai/sandbox`.
+### Pre-built Tools
 
-### With Sandbox Executor
+Use the built-in WASM tools:
 
 ```typescript
-import { WasmSandbox } from '@cogitator-ai/sandbox';
-import { calcToolConfig, jsonToolConfig } from '@cogitator-ai/wasm-tools';
+import {
+  createCalcTool,
+  createJsonTool,
+  createHashTool,
+  createBase64Tool,
+} from '@cogitator-ai/wasm-tools';
+import { Cogitator, Agent } from '@cogitator-ai/core';
 
-// Create executor
-const sandbox = new WasmSandbox(calcToolConfig);
+const calc = createCalcTool();
+const json = createJsonTool();
+const hash = createHashTool();
+const base64 = createBase64Tool();
 
-// Calculate expression
-const result = await sandbox.execute({ expression: '2 + 2 * 3' });
-// { result: 8, expression: '2 + 2 * 3' }
+const agent = new Agent({
+  name: 'utility-assistant',
+  model: 'gpt-4o',
+  tools: [calc, json, hash, base64],
+});
+
+const cog = new Cogitator({ llm: { defaultProvider: 'openai' } });
+const result = await cog.run(agent, {
+  input: 'Calculate the SHA-256 hash of "hello world"',
+});
 ```
 
-### With Cogitator Tools
+### Custom WASM Tools
 
-```typescript
-import { tool } from '@cogitator-ai/core';
-import { WasmSandbox } from '@cogitator-ai/sandbox';
-import {
-  calcToolConfig,
-  calcToolSchema,
-  jsonToolConfig,
-  jsonToolSchema,
-} from '@cogitator-ai/wasm-tools';
+Create custom tools that run in the WASM sandbox:
 
-const calcSandbox = new WasmSandbox(calcToolConfig);
+```typescript
+import { defineWasmTool } from '@cogitator-ai/wasm-tools';
+import { z } from 'zod';
+
+const hashTool = defineWasmTool({
+  name: 'hash_text',
+  description: 'Hash text using various algorithms',
+  wasmModule: './my-hash.wasm',
+  wasmFunction: 'hash',
+  parameters: z.object({
+    text: z.string().describe('Text to hash'),
+    algorithm: z.enum(['sha256', 'sha512', 'md5']),
+  }),
+  category: 'utility',
+  tags: ['hash', 'crypto'],
+  timeout: 5000,
+});
 
-const calculator = tool({
-  name: 'calculator',
-  description: 'Evaluate mathematical expressions safely',
-  parameters: calcToolSchema,
-  execute: async (input) => {
-    const result = await calcSandbox.execute(input);
-    return result;
-  },
+const agent = new Agent({
+  name: 'hasher',
+  tools: [hashTool],
 });
 ```
 
-### Available Exports
+## API Reference
 
-| Export              | Description                                   |
-| ------------------- | --------------------------------------------- |
-| `calcToolConfig`    | Sandbox config for calculator WASM module     |
-| `calcToolSchema`    | Zod schema for calculator input               |
-| `jsonToolConfig`    | Sandbox config for JSON processor WASM module |
-| `jsonToolSchema`    | Zod schema for JSON processor input           |
-| `getWasmPath(name)` | Get path to a WASM module by name             |
+### defineWasmTool(config)
 
-## Security
+Create a custom WASM tool for agent use.
+
+```typescript
+interface WasmToolConfig<TParams> {
+  name: string;
+  description: string;
+  wasmModule: string; // Path to .wasm file
+  wasmFunction?: string; // Function to call (default: 'run')
+  parameters: ZodType<TParams>;
+  category?: ToolCategory;
+  tags?: string[];
+  timeout?: number; // Execution timeout in ms
+  wasi?: boolean; // Enable WASI support
+  memoryPages?: number; // WASM memory limit
+}
+```
 
-WASM tools run in a secure sandbox:
+### createCalcTool(options?)
+
+Create a calculator tool for mathematical expressions.
+
+```typescript
+const calc = createCalcTool({ timeout: 10000 });
+
+// Supports: +, -, *, /, %, parentheses
+// Example: "2 + 2 * 3" → 8
+```
+
+### createJsonTool(options?)
+
+Create a JSON processor tool with JSONPath query support.
+
+```typescript
+const json = createJsonTool({ timeout: 10000 });
+
+// Example: { json: '{"a": {"b": 1}}', query: '$.a.b' } → 1
+```
+
+### createHashTool(options?)
+
+Create a cryptographic hash tool supporting multiple algorithms.
+
+```typescript
+const hash = createHashTool({ timeout: 10000 });
 
-- No filesystem access
-- No network access
-- Memory limits enforced
-- Timeout enforcement
+// Supports: sha256, sha1, md5
+// Example: { text: "hello", algorithm: "sha256" } → "2cf24dba5fb0a30e..."
+```
+
+### createBase64Tool(options?)
+
+Create a Base64 encoding/decoding tool with URL-safe variant support.
+
+```typescript
+const base64 = createBase64Tool({ timeout: 10000 });
+
+// Example: { text: "hello", operation: "encode" } → "aGVsbG8="
+// Example: { text: "aGVsbG8=", operation: "decode" } → "hello"
+// URL-safe: { text: "hello", operation: "encode", urlSafe: true }
+```
+
+### getWasmPath(name)
+
+Get the path to a pre-built WASM module.
+
+```typescript
+import { getWasmPath } from '@cogitator-ai/wasm-tools';
+
+const calcPath = getWasmPath('calc'); // Path to calc.wasm
+const jsonPath = getWasmPath('json'); // Path to json.wasm
+```
+
+### Legacy Exports
+
+For direct sandbox usage:
+
+| Export             | Description                               |
+| ------------------ | ----------------------------------------- |
+| `calcToolConfig`   | Sandbox config for calculator WASM module |
+| `calcToolSchema`   | Zod schema for calculator input           |
+| `jsonToolConfig`   | Sandbox config for JSON processor         |
+| `jsonToolSchema`   | Zod schema for JSON processor input       |
+| `hashToolConfig`   | Sandbox config for hash WASM module       |
+| `hashToolSchema`   | Zod schema for hash input                 |
+| `base64ToolConfig` | Sandbox config for base64 WASM module     |
+| `base64ToolSchema` | Zod schema for base64 input               |
+
+## Building Custom WASM Modules
+
+WASM modules use the Extism JS PDK:
+
+```typescript
+// my-tool.ts
+export function run(): number {
+  const input = JSON.parse(Host.inputString());
+
+  // Your logic here
+  const result = { processed: input.data };
+
+  Host.outputString(JSON.stringify(result));
+  return 0; // 0 = success
+}
+
+declare const Host: {
+  inputString(): string;
+  outputString(s: string): void;
+};
+```
+
+Build with:
+
+```bash
+esbuild my-tool.ts -o temp/my-tool.js --bundle --format=cjs --target=es2020
+extism-js temp/my-tool.js -o dist/my-tool.wasm
+```
+
+## Security
 
-## Documentation
+WASM tools run in a secure Extism sandbox:
 
-See the [Cogitator documentation](https://github.com/eL1fe/cogitator) for full API reference.
+- ❌ No filesystem access (unless WASI enabled)
+- ❌ No network access
+- ✅ Memory limits enforced
+- ✅ Timeout enforcement
+- ✅ Isolated execution environment
 
 ## License
 

package/dist/index.d.ts

@@ -1,25 +1,86 @@
 /**
  * @cogitator-ai/wasm-tools - WASM-based tools for Cogitator agents
  *
- * This package provides pre-built WASM tools that run in the Extism sandbox.
+ * This package provides pre-built WASM tools and a framework for creating
+ * custom WASM tools that run in the Extism sandbox.
+ *
  * WASM tools offer:
  * - 100-500x faster cold start than Docker
  * - Memory-safe execution in isolated sandbox
  * - ~20x lower memory footprint
+ *
+ * @example
+ * ```ts
+ * import { defineWasmTool, createCalcTool } from '@cogitator-ai/wasm-tools';
+ *
+ * // Use pre-built tools
+ * const calc = createCalcTool();
+ *
+ * // Create custom WASM tools
+ * const myTool = defineWasmTool({
+ *   name: 'image_processor',
+ *   description: 'Process images in WASM sandbox',
+ *   wasmModule: './my-image-proc.wasm',
+ *   wasmFunction: 'process',
+ *   parameters: z.object({
+ *     imageData: z.string(),
+ *     operation: z.enum(['resize', 'crop', 'rotate']),
+ *   }),
+ * });
+ * ```
  */
-import { z } from 'zod';
-import type { SandboxConfig } from '@cogitator-ai/types';
+import { z, type ZodType } from 'zod';
+import type { Tool, SandboxConfig, ToolCategory } from '@cogitator-ai/types';
 /**
- * Get the path to a WASM module in this package
+ * Configuration for defining a custom WASM tool
  */
-export declare function getWasmPath(name: string): string;
+export interface WasmToolConfig<TParams = unknown> {
+    name: string;
+    description: string;
+    wasmModule: string;
+    wasmFunction?: string;
+    parameters: ZodType<TParams>;
+    category?: ToolCategory;
+    tags?: string[];
+    timeout?: number;
+    wasi?: boolean;
+    memoryPages?: number;
+}
 /**
- * Calculator tool configuration for WASM execution
+ * Create a custom WASM tool for agent use.
+ *
+ * WASM tools run in an isolated Extism sandbox with memory-safe execution.
+ * The execute function passes parameters to the WASM module, which handles
+ * the actual computation.
+ *
+ * @param config - WASM tool configuration
+ * @returns A Tool instance configured for WASM sandbox execution
+ *
+ * @example
+ * ```ts
+ * const hashTool = defineWasmTool({
+ *   name: 'hash_text',
+ *   description: 'Hash text using various algorithms',
+ *   wasmModule: './hash.wasm',
+ *   wasmFunction: 'hash',
+ *   parameters: z.object({
+ *     text: z.string(),
+ *     algorithm: z.enum(['sha256', 'sha512', 'md5']),
+ *   }),
+ * });
+ *
+ * // Use with an agent
+ * const agent = new Agent({
+ *   name: 'hasher',
+ *   tools: [hashTool],
+ * });
+ * ```
  */
-export declare const calcToolConfig: SandboxConfig;
+export declare function defineWasmTool<TParams>(config: WasmToolConfig<TParams>): Tool<TParams, unknown>;
 /**
- * Calculator tool schema
+ * Get the path to a pre-built WASM module in this package
  */
+export declare function getWasmPath(name: string): string;
 export declare const calcToolSchema: z.ZodObject<{
     expression: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -27,13 +88,6 @@ export declare const calcToolSchema: z.ZodObject<{
 }, {
     expression: string;
 }>;
-/**
- * JSON processor tool configuration
- */
-export declare const jsonToolConfig: SandboxConfig;
-/**
- * JSON processor tool schema
- */
 export declare const jsonToolSchema: z.ZodObject<{
     json: z.ZodString;
     query: z.ZodOptional<z.ZodString>;
@@ -44,6 +98,115 @@ export declare const jsonToolSchema: z.ZodObject<{
     json: string;
     query?: string | undefined;
 }>;
+export declare const hashToolSchema: z.ZodObject<{
+    text: z.ZodString;
+    algorithm: z.ZodEnum<["sha256", "sha1", "md5"]>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    algorithm: "sha256" | "sha1" | "md5";
+}, {
+    text: string;
+    algorithm: "sha256" | "sha1" | "md5";
+}>;
+export declare const base64ToolSchema: z.ZodObject<{
+    text: z.ZodString;
+    operation: z.ZodEnum<["encode", "decode"]>;
+    urlSafe: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    operation: "encode" | "decode";
+    urlSafe?: boolean | undefined;
+}, {
+    text: string;
+    operation: "encode" | "decode";
+    urlSafe?: boolean | undefined;
+}>;
+/**
+ * Create a calculator WASM tool.
+ *
+ * Evaluates mathematical expressions safely in a WASM sandbox.
+ * Supports basic arithmetic: +, -, *, /, %, parentheses.
+ *
+ * @param options - Optional configuration overrides
+ * @returns A Tool for mathematical calculations
+ *
+ * @example
+ * ```ts
+ * const calc = createCalcTool();
+ * const agent = new Agent({ tools: [calc] });
+ *
+ * // Agent can now use: calculate({ expression: "2 + 2 * 3" })
+ * ```
+ */
+export declare function createCalcTool(options?: {
+    timeout?: number;
+}): Tool<CalcToolInput, unknown>;
+/**
+ * Create a JSON processor WASM tool.
+ *
+ * Parses and queries JSON data safely in a WASM sandbox.
+ * Supports JSONPath queries for extracting nested data.
+ *
+ * @param options - Optional configuration overrides
+ * @returns A Tool for JSON processing
+ *
+ * @example
+ * ```ts
+ * const jsonTool = createJsonTool();
+ * const agent = new Agent({ tools: [jsonTool] });
+ *
+ * // Agent can now use: process_json({ json: '{"a": 1}', query: '$.a' })
+ * ```
+ */
+export declare function createJsonTool(options?: {
+    timeout?: number;
+}): Tool<JsonToolInput, unknown>;
+/**
+ * Create a hash WASM tool.
+ *
+ * Computes cryptographic hashes safely in a WASM sandbox.
+ * Supports SHA-256, SHA-1, and MD5 algorithms.
+ *
+ * @param options - Optional configuration overrides
+ * @returns A Tool for hashing text
+ *
+ * @example
+ * ```ts
+ * const hashTool = createHashTool();
+ * const agent = new Agent({ tools: [hashTool] });
+ *
+ * // Agent can now use: hash_text({ text: "hello", algorithm: "sha256" })
+ * ```
+ */
+export declare function createHashTool(options?: {
+    timeout?: number;
+}): Tool<HashToolInput, unknown>;
+/**
+ * Create a Base64 encoding/decoding WASM tool.
+ *
+ * Encodes and decodes Base64 safely in a WASM sandbox.
+ * Supports both standard and URL-safe Base64 variants.
+ *
+ * @param options - Optional configuration overrides
+ * @returns A Tool for Base64 operations
+ *
+ * @example
+ * ```ts
+ * const b64Tool = createBase64Tool();
+ * const agent = new Agent({ tools: [b64Tool] });
+ *
+ * // Agent can now use: base64({ text: "hello", operation: "encode" })
+ * ```
+ */
+export declare function createBase64Tool(options?: {
+    timeout?: number;
+}): Tool<Base64ToolInput, unknown>;
+export declare const calcToolConfig: SandboxConfig;
+export declare const jsonToolConfig: SandboxConfig;
+export declare const hashToolConfig: SandboxConfig;
+export declare const base64ToolConfig: SandboxConfig;
 export type CalcToolInput = z.infer<typeof calcToolSchema>;
 export type JsonToolInput = z.infer<typeof jsonToolSchema>;
+export type HashToolInput = z.infer<typeof hashToolSchema>;
+export type Base64ToolInput = z.infer<typeof base64ToolSchema>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;EAEzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAO1F;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,GAAG,OAAO;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAuB/F;AAuBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,eAAO,MAAM,cAAc;;;;;;EAEzB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAY3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAY3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAW3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAW/F;AAED,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,aAK9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC3D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}