@cogitator-ai/wasm-tools 0.5.10 → 0.6.0

package/README.md

@@ -16,6 +16,23 @@ WASM-based tools for Cogitator agents. Secure, sandboxed tool execution using We
 pnpm add @cogitator-ai/wasm-tools
 ```
 
+`@extism/extism` (>= 2.0.0-rc13, the current `latest` on npm) is installed as a dependency; the pre-built plugins are compiled with `extism-js` and need its host functions and WASI.
+
+## How Tools Execute
+
+Every tool created here carries a `sandbox: { type: 'wasm', ... }` config and a real `execute()`:
+
+- **Inside Cogitator**: when `@cogitator-ai/sandbox` is available, Cogitator runs the module through its WASM executor (plugin pooling, worker-thread timeouts). Otherwise it falls back to the tool's own `execute()`.
+- **Directly**: `await tool.execute(params, context)` validates `params` with the tool's Zod schema, runs the module in an Extism worker thread, enforces `timeout` (the worker is terminated) and honours `context.signal`. Compiled modules are cached per file and recompiled when the file changes.
+
+```typescript
+const calc = createCalcTool();
+await calc.execute({ expression: '(2 + 3) * 4' }, { agentId: 'a', runId: 'r', signal });
+// { result: 20, expression: '(2 + 3) * 4' }
+```
+
+Plugin-level errors are returned as data (`{ ..., error: '...' }`) so the agent can react; timeouts, aborts and invalid parameters reject the promise.
+
 ## Quick Start
 
 ### Pre-built Tools
@@ -146,11 +163,13 @@ interface WasmToolConfig<TParams> {
   parameters: ZodType<TParams>;
   category?: ToolCategory;
   tags?: string[];
-  timeout?: number; // Execution timeout in ms
-  wasi?: boolean; // Enable WASI support
+  timeout?: number; // Execution timeout in ms (default 5000), also set as tool.timeout
+  wasi?: boolean; // Enable WASI (required for modules compiled with extism-js)
 }
 ```
 
+`parameters` may use Zod transforms: the parsed (output) value is what the module receives, while `toJSON()` exposes the input schema to the LLM.
+
 ### createCalcTool(options?)
 
 Create a calculator tool for mathematical expressions.
@@ -158,8 +177,9 @@ Create a calculator tool for mathematical expressions.
 ```typescript
 const calc = createCalcTool({ timeout: 10000 });
 
-// Supports: +, -, *, /, %, parentheses
-// Example: "2 + 2 * 3" → 8
+// Supports: +, -, *, /, %, unary +/-, parentheses, decimals (".5", "2.")
+// Example: "2 + 2 * 3" → { result: 8, expression: "2 + 2 * 3" }
+// Errors (division by zero, malformed numbers, non-finite results) → { result: null, error }
 ```
 
 ### createJsonTool(options?)
@@ -169,9 +189,12 @@ Create a JSON processor tool with JSONPath query support.
 ```typescript
 const json = createJsonTool({ timeout: 10000 });
 
-// Example: { json: '{"a": {"b": 1}}', query: '$.a.b' } → 1
+// { json: '{"a": {"b": 1}}', query: '$.a.b' } → { result: 1, type: 'number', found: true }
+// { json, query: '$.items[*].id' } → { result: [1, 2], type: 'array', found: true }
 ```
 
+Supported JSONPath subset: `$`, `.key`, `['key']`, `[n]` (negative indexes allowed), `[start:end:step]`, `*` / `[*]`, and recursive descent `..key` / `..*`. Wildcards, slices and recursive descent always return an array. Missing paths return `{ result: null, type: 'undefined', found: false }`; filters (`[?()]`) and unions are rejected with an error.
+
 ### createHashTool(options?)
 
 Create a cryptographic hash tool supporting multiple algorithms.
@@ -192,9 +215,11 @@ 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 }
+// URL-safe: { text: "hello", operation: "encode", urlSafe: true } → "aGVsbG8" (no padding)
 ```
 
+Decoding accepts both alphabets, optional padding and whitespace, rejects invalid characters/lengths with an error, and replaces invalid UTF-8 sequences with U+FFFD.
+
 ### createSlugTool(options?)
 
 Generate URL-safe slugs from text with Unicode transliteration.
@@ -204,8 +229,11 @@ const slug = createSlugTool({ timeout: 10000 });
 
 // Example: { text: "Hello World!" } → "hello-world"
 // Example: { text: "Привет мир", separator: "_" } → "privet_mir"
+// Example: { text: "Crème brûlée, a/b" } → "creme-brulee-a-b"
 ```
 
+Any run of non-alphanumeric characters becomes one separator; apostrophes are dropped; accents are stripped after transliteration. `maxLength` must be a positive integer and cuts at a separator when possible.
+
 ### createValidationTool(options?)
 
 Validate common formats: email, URL, UUID, IPv4, IPv6.
@@ -213,10 +241,15 @@ Validate common formats: email, URL, UUID, IPv4, IPv6.
 ```typescript
 const validation = createValidationTool({ timeout: 10000 });
 
-// Example: { value: "test@example.com", type: "email" } → { valid: true }
-// Example: { value: "192.168.1.1", type: "ipv4" } → { valid: true }
+// Example: { value: "test@example.com", type: "email" } → { valid: true, normalized: "test@example.com" }
+// Example: { value: "2001:DB8:0:0:0:0:0:1", type: "ipv6" } → { valid: true, normalized: "2001:db8::1" }
 ```
 
+- **email**: dot-atom local part (no leading/trailing/consecutive dots, ≤ 64 chars), valid hostname labels; only the domain is lower-cased.
+- **url**: `http`, `https`, `ftp`, `ftps`; userinfo, ports ≤ 65535 and bracketed IPv6 hosts are supported; whitespace and control characters are rejected. Missing schemes default to `https://`.
+- **ipv4**: dotted quad without leading zeros (`01.2.3.4` is rejected, matching Node's `net.isIPv4`).
+- **ipv6**: full RFC 4291 syntax including `::` and embedded IPv4; normalized to the RFC 5952 canonical form. Zone IDs are rejected.
+
 ### createDiffTool(options?)
 
 Compare texts using Myers diff algorithm.
@@ -224,10 +257,12 @@ Compare texts using Myers diff algorithm.
 ```typescript
 const diff = createDiffTool({ timeout: 10000 });
 
-// Example: { original: "hello", modified: "hallo" }
-// Returns unified diff with additions/deletions count
+// { original: "a\nb\n", modified: "a\nc\n" } →
+// { diff: "--- original\n+++ modified\n@@ -1,2 +1,2 @@\n a\n-b\n+c", additions: 1, deletions: 1, changes: [...] }
 ```
 
+`format` is `unified` (default, standard hunks with `context` lines, default 3), `inline` or `json`. A trailing newline is not treated as an extra line.
+
 ### createRegexTool(options?)
 
 Safe regex operations with ReDoS protection.
@@ -239,6 +274,8 @@ const regex = createRegexTool({ timeout: 10000 });
 // Supports: match, matchAll, test, replace, split
 ```
 
+Patterns with nested unbounded quantifiers (e.g. `(a+)+`, `(\w+\s?)+`) are rejected up front. Other catastrophic patterns (e.g. overlapping alternations like `(a|aa)+$`) are stopped by the execution timeout, which terminates the worker.
+
 ### createCsvTool(options?)
 
 RFC 4180 compliant CSV parsing and generation.
@@ -246,10 +283,12 @@ RFC 4180 compliant CSV parsing and generation.
 ```typescript
 const csv = createCsvTool({ timeout: 10000 });
 
-// Parse: { data: "a,b\n1,2", operation: "parse" }
-// Stringify: { data: [["a","b"],["1","2"]], operation: "stringify" }
+// Parse: { data: "a,b\n1,2", operation: "parse", headers: true } → headers ["a","b"], result [["1","2"]]
+// Stringify: { data: [["a","b"],["1","2"]], operation: "stringify", headers: ["x","y"] }
 ```
 
+Quotes only open a quoted field at the start of a field; unterminated quotes and characters after a closing quote are errors. A UTF-8 BOM is ignored. For `parse`, `headers` may also be an array of column names. Objects are JSON-encoded when stringifying.
+
 ### createMarkdownTool(options?)
 
 Convert Markdown to HTML (GFM subset).
@@ -259,9 +298,12 @@ const markdown = createMarkdownTool({ timeout: 10000 });
 
 // Example: { markdown: "# Hello\n**bold**" }
 // Returns: { html: "<h1>Hello</h1>\n<p><strong>bold</strong></p>" }
-// Supports: headers, bold, italic, links, code, lists, tables
+// Supports: headings, emphasis, strikethrough, links, images, autolinks, code spans/blocks,
+// lists (ordered with start number), blockquotes, rules, GFM tables with alignment, backslash escapes
 ```
 
+`options.sanitize` defaults to `true`: raw HTML is escaped and link/image URLs with schemes other than `http`, `https`, `mailto`, `tel` and `ftp` (e.g. `javascript:`, `data:`) are replaced with `#`. Code content and generated attribute values are always escaped. Intraword underscores (`snake_case`) are not treated as emphasis.
+
 ### createXmlTool(options?)
 
 Parse XML to JSON with XPath-like queries.
@@ -273,6 +315,8 @@ const xml = createXmlTool({ timeout: 10000 });
 // Supports: elements, attributes, CDATA, comments
 ```
 
+Query syntax: absolute paths start at the root element (`/root/item`), relative paths start below it (`item`), `//name` searches descendants, `*` matches any element, `name[2]` selects the 2nd match (1-based), `/@attr` (or `@*`) returns attribute values and `/text()` returns text content. One match returns a value, several return an array, none returns `{ result: null, type: 'empty' }`. Malformed documents (unclosed or mismatched tags, multiple roots, unterminated attributes) are errors; DTD entities are never expanded.
+
 ### createDatetimeTool(options?)
 
 Date/time operations with UTC and offset timezone support.
@@ -286,18 +330,24 @@ const datetime = createDatetimeTool({ timeout: 10000 });
 // Diff: { date: "2024-01-01", operation: "diff", endDate: "2024-01-15", unit: "days" }
 ```
 
+- Accepts ISO dates (`2024-01-15`, `2024-01-15 10:30`, fractional seconds, `Z`/`+04:00`/`+0400`/`+04`), Unix timestamps (10 digits = seconds, 11-13 = ms) and anything `Date.parse` understands. Impossible dates such as `2023-02-29` are rejected.
+- Month/year arithmetic clamps to the end of the month (`2024-01-31` + 1 month = `2024-02-29`).
+- Format tokens: `YYYY MM DD HH mm ss SSS Z`, every occurrence is replaced; wrap literal text in brackets (`[at]`).
+- `diff` returns whole units, truncated toward zero, negative when `endDate` is earlier.
+
 ### createCompressionTool(options?)
 
-Gzip/deflate/zlib compression and decompression.
+Gzip compression and decompression (RFC 1952), interoperable with zlib.
 
 ```typescript
 const compression = createCompressionTool({ timeout: 30000 });
 
-// Compress: { data: "hello", algorithm: "gzip", operation: "compress" }
-// Decompress: { data: "H4sIAAAA...", algorithm: "gzip", operation: "decompress" }
-// Returns base64-encoded compressed data with size info
+// Compress: { data: "hello", operation: "compress", level: 6 } → { result: "H4sI...", originalSize, resultSize, ratio }
+// Decompress: { data: "H4sIAAAA...", operation: "decompress" } → { result: "hello", ... }
 ```
 
+Defaults: `compress` reads UTF-8 and returns base64; `decompress` reads base64 and returns UTF-8. Use `inputEncoding`/`outputEncoding: 'base64'` for binary data. `level` is an integer 0-9. Decompression verifies the gzip CRC32 and size and is capped at 64 MB of output.
+
 ### createSigningTool(options?)
 
 Ed25519 digital signatures for message authentication.
@@ -310,6 +360,8 @@ const signing = createSigningTool({ timeout: 10000 });
 // Verify: { operation: "verify", algorithm: "ed25519", message: "hello", publicKey: "...", signature: "..." }
 ```
 
+WASM has no secure random source, so `signingToolSchema` generates a 32-byte seed on the host with `node:crypto` when `generateKeypair` is called without `seed`; the seed is the private key. Keys and signatures use `encoding: 'hex'` (default) or `'base64'`. Signatures are RFC 8032 Ed25519 and interoperate with `node:crypto`; non-canonical or off-curve public keys fail verification. Empty messages are allowed.
+
 ### getWasmPath(name)
 
 Get the path to a pre-built WASM module.
@@ -329,6 +381,7 @@ Manage WASM tools with hot-reload support.
 interface WasmToolManagerOptions {
   debounceMs?: number; // File change debounce delay (default: 100ms)
   useWasi?: boolean; // Enable WASI for all modules
+  timeout?: number; // Per-call timeout in ms (default: 30000)
 }
 
 interface WasmToolCallbacks {
@@ -362,6 +415,8 @@ class WasmToolManager {
 }
 ```
 
+Manager tools call the module's exported `run` function with the JSON-encoded parameters. Plugins run in Extism worker threads: when a call times out or its `context.signal` aborts, the call rejects and the plugin is replaced with a fresh instance so the tool keeps working.
+
 ### Legacy Exports
 
 For direct sandbox usage:
@@ -399,22 +454,26 @@ declare const Host: {
 };
 ```
 
-Build with:
+Build with (an interface file `my-tool.d.ts` declaring `declare module 'main' { export function run(): I32; }` lists the exports):
 
 ```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
+esbuild my-tool.ts --outfile=temp/my-tool.js --bundle --format=cjs --target=es2020
+extism-js temp/my-tool.js -i my-tool.d.ts -o dist/my-tool.wasm
 ```
 
+Modules compiled with `extism-js` embed QuickJS and require WASI: pass `wasi: true` to `defineWasmTool` (or `useWasi: true` to `WasmToolManager`).
+
+The package build (`pnpm build`) compiles `src/plugins/*.ts` with `extism-js` when it is installed and fails if any plugin fails to compile. Without `extism-js` it writes empty placeholder `.wasm` files; executing a tool then fails with a clear "placeholder build" error.
+
 ## Security
 
 WASM tools run in a secure Extism sandbox:
 
-- ❌ No filesystem access (unless WASI enabled)
-- ❌ No network access
-- ✅ Memory limits enforced
-- ✅ Timeout enforcement
-- ✅ Isolated execution environment
+- ❌ No filesystem access (no directories are pre-opened, even with WASI)
+- ❌ No network access (no allowed hosts)
+- ✅ Timeout enforcement (the worker thread is terminated)
+- ✅ Abort support via `ToolContext.signal`
+- ✅ Isolated linear memory per plugin instance
 
 ## License
 

package/dist/index.d.ts

@@ -39,7 +39,7 @@ export interface WasmToolConfig<TParams = unknown> {
     description: string;
     wasmModule: string;
     wasmFunction?: string;
-    parameters: ZodType<TParams>;
+    parameters: ZodType<TParams, unknown>;
     category?: ToolCategory;
     tags?: string[];
     timeout?: number;
@@ -292,7 +292,7 @@ export declare const compressionToolSchema: z.ZodObject<{
     }>>;
     level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-export declare const signingToolSchema: z.ZodObject<{
+export declare const signingToolSchema: z.ZodPipe<z.ZodObject<{
     operation: z.ZodEnum<{
         generateKeypair: "generateKeypair";
         sign: "sign";
@@ -309,7 +309,26 @@ export declare const signingToolSchema: z.ZodObject<{
         base64: "base64";
         hex: "hex";
     }>>;
-}, z.core.$strip>;
+    seed: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    operation: "generateKeypair" | "sign" | "verify";
+    algorithm: "ed25519";
+    message?: string | undefined;
+    privateKey?: string | undefined;
+    publicKey?: string | undefined;
+    signature?: string | undefined;
+    encoding?: "base64" | "hex" | undefined;
+    seed?: string | undefined;
+}, {
+    operation: "generateKeypair" | "sign" | "verify";
+    algorithm: "ed25519";
+    message?: string | undefined;
+    privateKey?: string | undefined;
+    publicKey?: string | undefined;
+    signature?: string | undefined;
+    encoding?: "base64" | "hex" | undefined;
+    seed?: string | undefined;
+}>>;
 export declare function createSlugTool(options?: {
     timeout?: number;
 }): Tool<SlugToolInput, unknown>;

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -30,8 +30,10 @@
  * ```
  */
 import { z } from 'zod';
+import { randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { invokeWasm } from './runtime.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Create a custom WASM tool for agent use.
@@ -64,11 +66,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * ```
  */
 export function defineWasmTool(config) {
+    const wasmFunction = config.wasmFunction ?? 'run';
+    const timeout = config.timeout ?? 5000;
     const sandboxConfig = {
         type: 'wasm',
         wasmModule: config.wasmModule,
-        wasmFunction: config.wasmFunction ?? 'run',
-        timeout: config.timeout ?? 5000,
+        wasmFunction,
+        timeout,
         wasi: config.wasi,
     };
     const tool = {
@@ -77,9 +81,19 @@ export function defineWasmTool(config) {
         category: config.category,
         tags: config.tags,
         parameters: config.parameters,
+        timeout,
         sandbox: sandboxConfig,
-        execute: async (params, _context) => {
-            return params;
+        execute: async (params, context) => {
+            const validated = config.parameters.parse(params);
+            return invokeWasm({
+                toolName: config.name,
+                wasmModule: config.wasmModule,
+                wasmFunction,
+                wasi: config.wasi ?? false,
+                timeout,
+                input: JSON.stringify(validated),
+                signal: context?.signal,
+            });
         },
         toJSON: () => wasmToolToSchema(tool),
     };
@@ -89,6 +103,7 @@ function wasmToolToSchema(t) {
     const jsonSchema = z.toJSONSchema(t.parameters, {
         target: 'openapi-3.0',
         unrepresentable: 'any',
+        io: 'input',
     });
     const schema = jsonSchema;
     const properties = (schema.properties ?? {});
@@ -114,7 +129,10 @@ export const calcToolSchema = z.object({
 });
 export const jsonToolSchema = z.object({
     json: z.string().describe('JSON string to parse and process'),
-    query: z.string().optional().describe('Optional JSONPath query'),
+    query: z
+        .string()
+        .optional()
+        .describe('Optional JSONPath query, e.g. "$.items[*].id", "$..price", "$.a[0:2]"'),
 });
 export const hashToolSchema = z.object({
     text: z.string().describe('Text to hash'),
@@ -147,6 +165,7 @@ export function createCalcTool(options) {
         name: 'calculate',
         description: 'Evaluate a mathematical expression safely. Supports +, -, *, /, %, and parentheses.',
         wasmModule: getWasmPath('calc'),
+        wasi: true,
         wasmFunction: 'calculate',
         parameters: calcToolSchema,
         category: 'math',
@@ -176,6 +195,7 @@ export function createJsonTool(options) {
         name: 'process_json',
         description: 'Parse and query JSON data. Supports JSONPath queries for extracting nested values.',
         wasmModule: getWasmPath('json'),
+        wasi: true,
         wasmFunction: 'process',
         parameters: jsonToolSchema,
         category: 'utility',
@@ -205,6 +225,7 @@ export function createHashTool(options) {
         name: 'hash_text',
         description: 'Compute cryptographic hash of text. Supports SHA-256, SHA-1, and MD5 algorithms.',
         wasmModule: getWasmPath('hash'),
+        wasi: true,
         wasmFunction: 'hash',
         parameters: hashToolSchema,
         category: 'utility',
@@ -234,6 +255,7 @@ export function createBase64Tool(options) {
         name: 'base64',
         description: 'Encode or decode Base64 text. Supports standard and URL-safe variants.',
         wasmModule: getWasmPath('base64'),
+        wasi: true,
         wasmFunction: 'base64',
         parameters: base64ToolSchema,
         category: 'utility',
@@ -244,24 +266,28 @@ export function createBase64Tool(options) {
 export const calcToolConfig = {
     type: 'wasm',
     wasmModule: getWasmPath('calc'),
+    wasi: true,
     wasmFunction: 'calculate',
     timeout: 5000,
 };
 export const jsonToolConfig = {
     type: 'wasm',
     wasmModule: getWasmPath('json'),
+    wasi: true,
     wasmFunction: 'process',
     timeout: 5000,
 };
 export const hashToolConfig = {
     type: 'wasm',
     wasmModule: getWasmPath('hash'),
+    wasi: true,
     wasmFunction: 'hash',
     timeout: 5000,
 };
 export const base64ToolConfig = {
     type: 'wasm',
     wasmModule: getWasmPath('base64'),
+    wasi: true,
     wasmFunction: 'base64',
     timeout: 5000,
 };
@@ -269,7 +295,7 @@ export const slugToolSchema = z.object({
     text: z.string().describe('Text to convert to URL-safe slug'),
     separator: z.string().optional().describe('Separator character (default: "-")'),
     lowercase: z.boolean().optional().describe('Convert to lowercase (default: true)'),
-    maxLength: z.number().optional().describe('Maximum length of the slug'),
+    maxLength: z.number().int().min(1).optional().describe('Maximum length of the slug'),
 });
 export const validationToolSchema = z.object({
     value: z.string().describe('Value to validate'),
@@ -279,7 +305,12 @@ export const diffToolSchema = z.object({
     original: z.string().describe('Original text'),
     modified: z.string().describe('Modified text'),
     format: z.enum(['unified', 'inline', 'json']).optional().describe('Output format'),
-    context: z.number().optional().describe('Context lines for unified diff'),
+    context: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Context lines for unified diff (default 3)'),
 });
 export const regexToolSchema = z.object({
     text: z.string().describe('Text to search/replace'),
@@ -287,7 +318,7 @@ export const regexToolSchema = z.object({
     flags: z.string().optional().describe('Regex flags (g, i, m, etc.)'),
     operation: z.enum(['match', 'matchAll', 'test', 'replace', 'split']).describe('Operation'),
     replacement: z.string().optional().describe('Replacement text for replace operation'),
-    limit: z.number().optional().describe('Limit number of matches/splits'),
+    limit: z.number().int().min(0).optional().describe('Limit number of matches/splits'),
 });
 export const csvToolSchema = z.object({
     data: z.union([z.string(), z.array(z.array(z.unknown()))]).describe('CSV string or array data'),
@@ -310,12 +341,18 @@ export const markdownToolSchema = z.object({
 });
 export const xmlToolSchema = z.object({
     xml: z.string().describe('XML string to parse'),
-    query: z.string().optional().describe('XPath-like query (e.g., "/root/child", "//element")'),
+    query: z
+        .string()
+        .optional()
+        .describe('XPath-like query, e.g. "/root/child", "//item[2]", "//item/@id", "//item/text()"'),
 });
 export const datetimeToolSchema = z.object({
     date: z.string().optional().describe('Date string to process'),
     operation: z.enum(['parse', 'format', 'add', 'subtract', 'diff', 'now']).describe('Operation'),
-    format: z.string().optional().describe('Date format (YYYY, MM, DD, HH, mm, ss, SSS, Z)'),
+    format: z
+        .string()
+        .optional()
+        .describe('Date format tokens: YYYY MM DD HH mm ss SSS Z; wrap literal text in [brackets]'),
     timezone: z.string().optional().describe('Timezone offset (e.g., "+04:00", "UTC")'),
     amount: z.number().optional().describe('Amount for add/subtract'),
     unit: z
@@ -326,11 +363,18 @@ export const datetimeToolSchema = z.object({
 export const compressionToolSchema = z.object({
     data: z.string().describe('Data to compress/decompress'),
     operation: z.enum(['compress', 'decompress']).describe('Operation'),
-    inputEncoding: z.enum(['base64', 'utf8']).optional().describe('Input encoding'),
-    outputEncoding: z.enum(['base64', 'utf8']).optional().describe('Output encoding'),
-    level: z.number().optional().describe('Compression level (0-9)'),
+    inputEncoding: z
+        .enum(['base64', 'utf8'])
+        .optional()
+        .describe('Input encoding (default: utf8 for compress, base64 for decompress)'),
+    outputEncoding: z
+        .enum(['base64', 'utf8'])
+        .optional()
+        .describe('Output encoding (default: base64 for compress, utf8 for decompress)'),
+    level: z.number().int().min(0).max(9).optional().describe('Compression level (0-9, default 6)'),
 });
-export const signingToolSchema = z.object({
+export const signingToolSchema = z
+    .object({
     operation: z.enum(['generateKeypair', 'sign', 'verify']).describe('Operation'),
     algorithm: z.enum(['ed25519']).describe('Signing algorithm'),
     message: z.string().optional().describe('Message to sign/verify'),
@@ -338,12 +382,26 @@ export const signingToolSchema = z.object({
     publicKey: z.string().optional().describe('Public key (hex or base64)'),
     signature: z.string().optional().describe('Signature to verify'),
     encoding: z.enum(['hex', 'base64']).optional().describe('Key/signature encoding'),
+    seed: z
+        .string()
+        .optional()
+        .describe('Optional 32-byte seed for generateKeypair (hex or base64). A cryptographically secure seed is generated on the host when omitted.'),
+})
+    .transform((input) => {
+    if (input.operation !== 'generateKeypair' || input.seed !== undefined)
+        return input;
+    const seed = randomBytes(32);
+    return {
+        ...input,
+        seed: input.encoding === 'base64' ? seed.toString('base64') : seed.toString('hex'),
+    };
 });
 export function createSlugTool(options) {
     return defineWasmTool({
         name: 'slug',
         description: 'Convert text to URL-safe slug with transliteration support',
         wasmModule: getWasmPath('slug'),
+        wasi: true,
         wasmFunction: 'slug',
         parameters: slugToolSchema,
         category: 'utility',
@@ -356,6 +414,7 @@ export function createValidationTool(options) {
         name: 'validate',
         description: 'Validate email, URL, UUID, IPv4, or IPv6 addresses',
         wasmModule: getWasmPath('validation'),
+        wasi: true,
         wasmFunction: 'validate',
         parameters: validationToolSchema,
         category: 'utility',
@@ -368,6 +427,7 @@ export function createDiffTool(options) {
         name: 'diff',
         description: 'Generate diff between two texts using Myers algorithm',
         wasmModule: getWasmPath('diff'),
+        wasi: true,
         wasmFunction: 'diff',
         parameters: diffToolSchema,
         category: 'utility',
@@ -380,6 +440,7 @@ export function createRegexTool(options) {
         name: 'regex',
         description: 'Execute regex operations with ReDoS protection',
         wasmModule: getWasmPath('regex'),
+        wasi: true,
         wasmFunction: 'regex',
         parameters: regexToolSchema,
         category: 'utility',
@@ -392,6 +453,7 @@ export function createCsvTool(options) {
         name: 'csv',
         description: 'Parse and generate CSV data (RFC 4180 compliant)',
         wasmModule: getWasmPath('csv'),
+        wasi: true,
         wasmFunction: 'csv',
         parameters: csvToolSchema,
         category: 'utility',
@@ -404,6 +466,7 @@ export function createMarkdownTool(options) {
         name: 'markdown',
         description: 'Convert Markdown to HTML (GFM subset)',
         wasmModule: getWasmPath('markdown'),
+        wasi: true,
         wasmFunction: 'markdown',
         parameters: markdownToolSchema,
         category: 'utility',
@@ -416,6 +479,7 @@ export function createXmlTool(options) {
         name: 'xml',
         description: 'Parse XML to JSON with XPath-like query support',
         wasmModule: getWasmPath('xml'),
+        wasi: true,
         wasmFunction: 'xml',
         parameters: xmlToolSchema,
         category: 'utility',
@@ -428,6 +492,7 @@ export function createDatetimeTool(options) {
         name: 'datetime',
         description: 'Parse, format, and manipulate dates (UTC + offset timezones)',
         wasmModule: getWasmPath('datetime'),
+        wasi: true,
         wasmFunction: 'datetime',
         parameters: datetimeToolSchema,
         category: 'utility',
@@ -440,6 +505,7 @@ export function createCompressionTool(options) {
         name: 'compression',
         description: 'Compress and decompress data using gzip',
         wasmModule: getWasmPath('compression'),
+        wasi: true,
         wasmFunction: 'compression',
         parameters: compressionToolSchema,
         category: 'utility',
@@ -452,6 +518,7 @@ export function createSigningTool(options) {
         name: 'signing',
         description: 'Digital signatures with Ed25519 (keypair generation, sign, verify)',
         wasmModule: getWasmPath('signing'),
+        wasi: true,
         wasmFunction: 'signing',
         parameters: signingToolSchema,
         category: 'utility',