@liquidmetal-ai/precip 1.0.0

package/src/tools/actor-storage-tools.ts

@@ -0,0 +1,250 @@
+/**
+ * Actor Storage Tools - Read, write, list, delete entries from ActorStorage mounts
+ * Mount-aware: operates on actor-storage mounts via path prefixes
+ *
+ * ActorStorage is strongly consistent, transactional KV local to an Actor instance.
+ * Values are stored as UTF-8 bytes (Uint8Array).
+ */
+
+import type { Tool } from '../types.js';
+import type { ActorStorage } from '@liquidmetal-ai/raindrop-framework';
+import { createPathBasedTool } from './tool-factory.js';
+
+/**
+ * Read a value from actor storage
+ *
+ * Example: read_state("/local/user-preferences")
+ */
+export const ReadStateTool: Tool = createPathBasedTool<{ path: string }, any>({
+  name: 'read_state',
+  description: `Read a value from actor storage (strongly consistent, transactional KV).
+
+Path format: /mount-name/key
+
+Returns: {path, content} or throws if key not found.
+
+Example: read_state("/local/user-preferences")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'Key path starting with /, e.g., /local/user-preferences',
+      required: true
+    }
+  },
+  allowedMountTypes: ['actor-storage'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    if (!parsed.path) {
+      throw new Error('Key is required. Path format: /mount-name/key');
+    }
+
+    const storage = mount.resource as ActorStorage;
+    const value = await storage.get(parsed.path);
+
+    if (value === undefined) {
+      throw new Error(`Key not found: ${params.path}`);
+    }
+
+    // Decode bytes back to string — values may be stored as Uint8Array (by sandbox bridge)
+    // or as plain strings/objects (by other callers)
+    let content: string;
+    if (typeof value === 'string') {
+      content = value;
+    } else if (value instanceof Uint8Array) {
+      content = new TextDecoder().decode(value);
+    } else if (value instanceof ArrayBuffer) {
+      content = new TextDecoder().decode(new Uint8Array(value));
+    } else {
+      content = JSON.stringify(value);
+    }
+
+    return {
+      path: params.path,
+      content
+    };
+  }
+});
+
+/**
+ * Write a value to actor storage
+ *
+ * Example: write_state("/local/user-preferences", '{"theme": "dark"}')
+ */
+export const WriteStateTool: Tool = createPathBasedTool<{ path: string; content: string }, any>({
+  name: 'write_state',
+  description: `Write a value to actor storage (strongly consistent, transactional KV).
+
+Path format: /mount-name/key
+
+Values are stored as UTF-8 bytes. Non-string content is JSON-serialized.
+Note: Mount must have mode 'rw' to allow writes.
+
+Returns: {path, success, size}
+
+Example: write_state("/local/user-preferences", '{"theme": "dark"}')`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'Key path starting with /, e.g., /local/user-preferences',
+      required: true
+    },
+    content: {
+      type: 'string',
+      description: 'Content to store (string or JSON)',
+      required: true
+    }
+  },
+  allowedMountTypes: ['actor-storage'],
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    if (!parsed.path) {
+      throw new Error('Key is required. Path format: /mount-name/key');
+    }
+
+    const storage = mount.resource as ActorStorage;
+    const value = typeof params.content === 'string' ? params.content : JSON.stringify(params.content);
+    const bytes = new TextEncoder().encode(value);
+    await storage.put(parsed.path, bytes);
+
+    return {
+      path: params.path,
+      success: true,
+      size: bytes.length
+    };
+  }
+});
+
+/**
+ * List keys in actor storage
+ *
+ * Example: list_state("/local/") or list_state("/local/conversations/")
+ */
+export const ListStateTool: Tool = createPathBasedTool<{
+  path: string;
+  limit?: number;
+  start?: string;
+  end?: string;
+  reverse?: boolean;
+}, any>({
+  name: 'list_state',
+  description: `List keys in actor storage with optional prefix, range, and ordering.
+
+Path format: /mount-name/ or /mount-name/prefix/
+
+Supports range queries via options. ActorStorage list is strongly consistent.
+
+Returns: {keys: [{key, path}], count}
+
+Example: list_state("/local/")
+Example with prefix: list_state("/local/conversations/")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'Mount path with optional prefix, e.g., /local/ or /local/conversations/',
+      required: true
+    },
+    limit: {
+      type: 'number',
+      description: 'Maximum number of keys to return',
+      required: false
+    },
+    start: {
+      type: 'string',
+      description: 'Start key (inclusive) for range queries',
+      required: false
+    },
+    end: {
+      type: 'string',
+      description: 'End key (exclusive) for range queries',
+      required: false
+    },
+    reverse: {
+      type: 'boolean',
+      description: 'List in reverse order',
+      required: false
+    }
+  },
+  allowedMountTypes: ['actor-storage'],
+  mode: 'read',
+
+  async executor(mount, parsed, params) {
+    const storage = mount.resource as ActorStorage;
+    const listOptions: Record<string, any> = {};
+
+    if (parsed.path) {
+      listOptions.prefix = parsed.path;
+    }
+    if (params.start !== undefined) listOptions.start = params.start;
+    if (params.end !== undefined) listOptions.end = params.end;
+    if (params.reverse !== undefined) listOptions.reverse = params.reverse;
+    if (params.limit !== undefined) listOptions.limit = params.limit;
+
+    const entries = await storage.list(
+      Object.keys(listOptions).length > 0 ? listOptions : undefined
+    );
+
+    const keys = Array.from(entries).map(([key]) => ({
+      key,
+      path: `/${mount.name}/${key}`
+    }));
+
+    return {
+      keys,
+      count: keys.length
+    };
+  }
+});
+
+/**
+ * Delete a key from actor storage
+ *
+ * Example: delete_state("/local/old-session")
+ */
+export const DeleteStateTool: Tool = createPathBasedTool<{ path: string }, any>({
+  name: 'delete_state',
+  description: `Delete a key from actor storage.
+
+Path format: /mount-name/key
+
+Note: Mount must have mode 'rw' to allow deletes.
+
+Returns: {path, success, deleted}
+
+Example: delete_state("/local/old-session")`,
+  parameters: {
+    path: {
+      type: 'string',
+      description: 'Key path starting with /, e.g., /local/old-session',
+      required: true
+    }
+  },
+  allowedMountTypes: ['actor-storage'],
+  mode: 'write',
+
+  async executor(mount, parsed, params) {
+    if (!parsed.path) {
+      throw new Error('Key is required. Path format: /mount-name/key');
+    }
+
+    const storage = mount.resource as ActorStorage;
+    const deleted = await storage.delete(parsed.path);
+
+    return {
+      path: params.path,
+      success: true,
+      deleted
+    };
+  }
+});
+
+/**
+ * All actor storage tools
+ */
+export const ActorStorageTools: Tool[] = [
+  ReadStateTool,
+  WriteStateTool,
+  ListStateTool,
+  DeleteStateTool
+];

package/src/tools/code-tools.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest';
+import { formatToolOutput } from './code-tools.js';
+
+describe('Code Tools - Output Formatting', () => {
+  it('should format output with only console.log', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['Line 1', 'Line 2', 'Line 3']
+    };
+
+    const formatted = formatToolOutput(result);
+
+    // No [result] section when there's no result value
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Line 1');
+    expect(formatted.output).toContain('Line 2');
+    expect(formatted.output).toContain('Line 3');
+  });
+
+  it('should format output with only return value', () => {
+    const result = {
+      success: true,
+      result: { count: 42, status: 'ok' }
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('"count": 42');
+    expect(formatted.output).toContain('"status": "ok"');
+  });
+
+  it('should format output with both console.log and return value', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['Starting process...', 'Processing complete'],
+      result: { success: true, count: 100 }
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Starting process...');
+    expect(formatted.output).toContain('Processing complete');
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('"success": true');
+    expect(formatted.output).toContain('"count": 100');
+  });
+
+  it('should handle no output', () => {
+    const result = {
+      success: true
+    };
+
+    const formatted = formatToolOutput(result);
+
+    // Always return output field, even if empty
+    expect(formatted).toEqual({ output: '(no output)' });
+  });
+
+  it('should handle empty console output', () => {
+    const result = {
+      success: true,
+      consoleOutput: [],
+      result: 'done'
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('done');
+    // Only return output field for consistency
+    expect(formatted.success).toBeUndefined();
+  });
+
+  it('should only return output field', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['debug'],
+      result: { data: 'test' },
+      executionTime: 123
+    };
+
+    const formatted = formatToolOutput(result);
+
+    // Only return output field for OpenAI chat completion compatibility
+    expect(formatted).toHaveProperty('output');
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('debug');
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('"data": "test"');
+    // Original properties should not be spread
+    expect(formatted.success).toBeUndefined();
+    expect(formatted.consoleOutput).toBeUndefined();
+    expect(formatted.result).toBeUndefined();
+    expect(formatted.executionTime).toBeUndefined();
+  });
+
+  it('should format string return value', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['Log message'],
+      result: 'Return value'
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Log message');
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('Return value');
+  });
+
+  it('should format null return value', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['Processing'],
+      result: null
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Processing');
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('null');
+  });
+
+  it('should format undefined return value', () => {
+    const result = {
+      success: true,
+      consoleOutput: ['Done'],
+      result: undefined
+    };
+
+    const formatted = formatToolOutput(result);
+
+    // When result is undefined, we don't show [result] section
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Done');
+  });
+
+  it('should format error output', () => {
+    const result = {
+      success: false,
+      error: 'ReferenceError: x is not defined',
+      consoleOutput: ['Before error']
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[error]');
+    expect(formatted.output).toContain('ReferenceError: x is not defined');
+    expect(formatted.output).toContain('[stdout]');
+    expect(formatted.output).toContain('Before error');
+  });
+
+  it('should truncate very large result objects', () => {
+    const largeArray = Array.from({ length: 10000 }, (_, i) => ({ id: i, data: 'x'.repeat(100) }));
+    const result = {
+      success: true,
+      result: largeArray
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('...(truncated)');
+    // Should be capped at roughly 50k chars
+    expect(formatted.output.length).toBeLessThan(60000);
+  });
+
+  it('should handle circular reference in result gracefully', () => {
+    const obj: any = { a: 1 };
+    obj.self = obj;
+    const result = {
+      success: true,
+      result: obj
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[result]');
+    // Should not throw, falls back to String()
+    expect(formatted.output).toBeDefined();
+  });
+
+  it('should format number return value', () => {
+    const result = {
+      success: true,
+      result: 42
+    };
+
+    const formatted = formatToolOutput(result);
+
+    expect(formatted.output).toContain('[result]');
+    expect(formatted.output).toContain('42');
+  });
+});