@liquidmetal-ai/precip 1.0.0

package/src/tools/tool-factory.ts

@@ -0,0 +1,119 @@
+/**
+ * Tool Factory - Reduces boilerplate for path-based tools
+ *
+ * This factory handles common patterns:
+ * - Mount validation and resolution
+ * - Path parsing
+ * - Mount type checking
+ * - Permission (mode) checking
+ * - Consistent error messages
+ */
+
+import type { Tool, ToolContext, ToolParameter } from '../types.js';
+import type { MountInfo, MountProvider, ParsedPath } from '../types.js';
+
+/**
+ * Configuration for creating a path-based tool
+ */
+export interface PathBasedToolConfig<TConfig extends Record<string, any>, TResult> {
+  name: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+  allowedMountTypes: MountInfo['type'][];
+  mode?: 'read' | 'write';
+  /** Name of the parameter containing the path (default: 'path', also checks 'database') */
+  pathParameterName?: string;
+  executor: (mount: MountInfo, parsed: ParsedPath, params: TConfig) => Promise<TResult>;
+}
+
+/**
+ * Mount access validation utilities
+ */
+export class MountAccess {
+  /**
+   * Resolve a mount path with validation
+   */
+  static async getWithValidation(
+    mountManager: MountProvider,
+    path: string,
+    allowedTypes: MountInfo['type'][],
+    mode?: 'read' | 'write'
+  ): Promise<{ mount: MountInfo; parsed: ParsedPath }> {
+    const parsed = mountManager.parsePath(path);
+    const mount = mountManager.getMount(parsed.mountName);
+
+    if (!mount) {
+      throw this.createMountNotFoundError(parsed.mountName, mountManager);
+    }
+
+    if (!allowedTypes.includes(mount.type)) {
+      throw this.createTypeError(mount, allowedTypes);
+    }
+
+    if (mode === 'write' && mount.mode !== 'rw') {
+      throw new Error(`Cannot write to read-only mount: ${mount.name}. Mount must have mode 'rw'.`);
+    }
+
+    return { mount, parsed };
+  }
+
+  /**
+   * Create a "mount not found" error with helpful message
+   */
+  static createMountNotFoundError(name: string, mountManager: MountProvider): Error {
+    const available = Array.from(mountManager.getAllMounts().keys()).join(', ');
+    return new Error(`Mount not found: ${name}. Available: ${available}`);
+  }
+
+  /**
+   * Create a mount type mismatch error
+   */
+  static createTypeError(
+    mount: MountInfo,
+    allowedTypes: MountInfo['type'][]
+  ): Error {
+    const typeList = allowedTypes.join(' or ');
+    return new Error(
+      `Mount '${mount.name}' is not ${typeList} (it's ${mount.type})`
+    );
+  }
+}
+
+/**
+ * Create a path-based tool with automatic mount validation
+ *
+ * This eliminates ~80% of boilerplate from tools that operate on mounted resources.
+ */
+export function createPathBasedTool<TConfig extends Record<string, any>, TResult>(
+  config: PathBasedToolConfig<TConfig, TResult>
+): Tool {
+  return {
+    definition: {
+      name: config.name,
+      description: config.description,
+      parameters: config.parameters
+    },
+
+    async execute(params: any, context: ToolContext) {
+      const mountManager = context.mounts;
+
+      // Extract path from params using configured parameter name
+      const pathParam = config.pathParameterName || 'path';
+      const path = params[pathParam] || (pathParam === 'path' ? params.database : undefined);
+      if (!path) {
+        throw new Error(`Parameter '${pathParam}' is required`);
+      }
+
+      // Validate mount and get resource
+      const { mount, parsed } = await MountAccess.getWithValidation(
+        mountManager,
+        path,
+        config.allowedMountTypes,
+        config.mode
+      );
+
+      // Execute the tool's logic with properly typed params
+      return config.executor(mount, parsed, params);
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,512 @@
+/**
+ * Core type definitions for Precip Agent SDK
+ */
+
+// Use Raindrop framework types
+import type {
+  Ai,
+  Bucket,
+  SmartBucket,
+  KvCache,
+  SqlDatabase,
+  Actor,
+  ActorNamespace,
+  ActorStorage
+} from '@liquidmetal-ai/raindrop-framework';
+import type { BridgeInstaller } from './sandbox/bridges/types.js';
+import type { z } from 'zod';
+
+// ============================================================================
+// LLM Provider Types
+// ============================================================================
+
+export type LLMProvider = 'openai' | 'anthropic' | 'liquidmetal';
+
+export interface LLMConfig {
+  provider: LLMProvider;
+  model: string;
+  apiKey?: string;
+  baseUrl?: string;
+  temperature?: number;
+  maxTokens?: number;
+  streaming?: boolean;
+  aiBinding?: Ai;
+}
+
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | null;
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: LLMToolCall[];
+}
+
+export interface LLMToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string; // JSON string
+  };
+}
+
+export interface LLMResponse {
+  content: string | null;
+  toolCalls: LLMToolCall[];
+  finishReason: string | null;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+// ============================================================================
+// Mount Types
+// ============================================================================
+
+/** Mount types */
+export type MountType = 'bucket' | 'smartbucket' | 'kv' | 'database' | 'actor' | 'actor-storage';
+
+// ----------------------------------------------------------------------------
+// Actor Method Schema (Zod-based)
+// ----------------------------------------------------------------------------
+
+/**
+ * Schema definition for an actor RPC method.
+ * Uses Zod for type-safe, self-documenting method signatures.
+ *
+ * Arguments are represented as a tuple (z.tuple), matching the actual
+ * method signature. For example, a method `doSomething(a: string, b: number)`
+ * should have `params: z.tuple([z.string().describe("a"), z.number().describe("b")])`.
+ * A method with no arguments uses `params: z.tuple([])`.
+ *
+ * Use `.describe()` on each tuple element to name the parameter — these names
+ * appear in generated documentation and system prompts for LLMs.
+ */
+export interface ActorMethodSchema {
+  /** Human-readable description of what this method does */
+  description: string;
+  /**
+   * Zod tuple schema for method arguments.
+   * Each element in the tuple corresponds to a positional argument.
+   * Use `.describe("name")` on each element to provide a parameter name.
+   *
+   * Examples:
+   * - No args: `z.tuple([])`
+   * - Single arg: `z.tuple([z.object({ theme: z.string() }).describe("prefs")])`
+   * - Multiple args: `z.tuple([z.string().describe("userId"), z.number().describe("limit")])`
+   */
+  params: z.ZodTuple<[z.ZodTypeAny, ...z.ZodTypeAny[]] | [], z.ZodTypeAny | null>;
+  /** Zod schema for return type */
+  returns: z.ZodType;
+}
+
+// ----------------------------------------------------------------------------
+// Discriminated Mount Configurations
+// ----------------------------------------------------------------------------
+
+/** Mount access mode */
+export type MountMode = 'ro' | 'rw';
+
+/** Base config for all mount types */
+interface BaseMountConfig {
+  /** Human-readable description of what this resource is for */
+  description?: string;
+  /** Access mode: 'ro' (read-only) or 'rw' (read-write). Default: 'ro' */
+  mode?: MountMode;
+}
+
+/** Config for Bucket mounts */
+export interface BucketMountConfig extends BaseMountConfig {
+  type: 'bucket';
+  resource: Bucket;
+}
+
+/** Config for SmartBucket mounts */
+export interface SmartBucketMountConfig extends BaseMountConfig {
+  type: 'smartbucket';
+  resource: SmartBucket;
+}
+
+/** Config for KvCache mounts */
+export interface KvMountConfig extends BaseMountConfig {
+  type: 'kv';
+  resource: KvCache;
+}
+
+/** Config for SqlDatabase mounts */
+export interface SqlMountConfig extends BaseMountConfig {
+  type: 'database';
+  resource: SqlDatabase;
+}
+
+/** Config for Actor mounts - requires method schemas */
+export interface ActorMountConfig<T extends Actor<unknown> = Actor<unknown>>
+  extends BaseMountConfig {
+  type: 'actor';
+  resource: ActorNamespace<T>;
+  /** Zod schemas for each RPC method the actor exposes */
+  methods: Record<string, ActorMethodSchema>;
+}
+
+/** Config for ActorStorage mounts - exposes actor's local state.storage as a filesystem-like mount */
+export interface ActorStorageMountConfig extends BaseMountConfig {
+  type: 'actor-storage';
+  resource: ActorStorage;
+}
+
+/** Discriminated union of all mount configs */
+export type MountConfigType =
+  | BucketMountConfig
+  | SmartBucketMountConfig
+  | KvMountConfig
+  | SqlMountConfig
+  | ActorMountConfig
+  | ActorStorageMountConfig;
+
+/** Mount configuration map - requires explicit type for each mount */
+export interface MountConfig {
+  [mountName: string]: MountConfigType;
+}
+
+// ----------------------------------------------------------------------------
+// Internal Mount Info (normalized)
+// ----------------------------------------------------------------------------
+
+/** Base mount info after normalization */
+interface BaseMountInfo {
+  name: string;
+  type: MountType;
+  description?: string;
+  /** Access mode: 'ro' (read-only) or 'rw' (read-write). Default: 'ro' */
+  mode?: MountMode;
+}
+
+/** Normalized info for Bucket mounts */
+export interface BucketMountInfo extends BaseMountInfo {
+  type: 'bucket';
+  resource: Bucket;
+}
+
+/** Normalized info for SmartBucket mounts */
+export interface SmartBucketMountInfo extends BaseMountInfo {
+  type: 'smartbucket';
+  resource: SmartBucket;
+}
+
+/** Normalized info for KvCache mounts */
+export interface KvMountInfo extends BaseMountInfo {
+  type: 'kv';
+  resource: KvCache;
+}
+
+/** Normalized info for SqlDatabase mounts */
+export interface SqlMountInfo extends BaseMountInfo {
+  type: 'database';
+  resource: SqlDatabase;
+}
+
+/** Normalized info for Actor mounts */
+export interface ActorMountInfo extends BaseMountInfo {
+  type: 'actor';
+  resource: ActorNamespace<Actor<unknown>>;
+  methods: Record<string, ActorMethodSchema>;
+}
+
+/** Normalized info for ActorStorage mounts */
+export interface ActorStorageMountInfo extends BaseMountInfo {
+  type: 'actor-storage';
+  resource: ActorStorage;
+}
+
+/** Union of all normalized mount info types (discriminated by type) */
+export type MountInfo =
+  | BucketMountInfo
+  | SmartBucketMountInfo
+  | KvMountInfo
+  | SqlMountInfo
+  | ActorMountInfo
+  | ActorStorageMountInfo;
+
+export interface ParsedPath {
+  mountName: string;
+  path: string;
+  fullPath: string;
+}
+
+// ============================================================================
+// Tool Types
+// ============================================================================
+
+export interface ToolParameter {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description: string;
+  required?: boolean;
+  enum?: string[];
+  items?: ToolParameter;
+  properties?: Record<string, ToolParameter>;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+}
+
+/**
+ * Interface for mount management in tool contexts.
+ * Provides path-based access to mounted resources.
+ * Implemented by MountManager.
+ */
+export interface MountProvider {
+  /** Get mount by name */
+  getMount(name: string): MountInfo | undefined;
+  /** Get all mounts as a map */
+  getAllMounts(): Map<string, MountInfo>;
+  /** Parse a full path into mount name and resource path */
+  parsePath(fullPath: string): ParsedPath;
+  /** Resolve a path to a mount and resource path */
+  resolvePath(fullPath: string): { mount: MountInfo; path: string };
+  /** List all mounts of a given type */
+  getMountsByType<T extends MountInfo['type']>(type: T): MountInfo[];
+  /** Get all actor mounts with their schemas */
+  getActorMounts(): Map<string, ActorMountInfo>;
+  /** Generate a formatted description of all mounts for system prompts */
+  getMountsDescription(): string;
+  /** Create sandbox globals from mounts */
+  createSandboxGlobals(): Record<string, unknown>;
+}
+
+export interface ToolContext {
+  mounts: MountProvider;
+  logger?: Logger;
+  env?: unknown;
+}
+
+export interface Tool {
+  definition: ToolDefinition;
+  execute: (params: any, context: ToolContext) => Promise<any>;
+}
+
+export interface ToolResult {
+  success: boolean;
+  result?: any;
+  error?: string;
+}
+
+// ============================================================================
+// Agent Types
+// ============================================================================
+
+export interface AgentConfig {
+  llm: LLMConfig;
+  system?: string;
+  mounts?: MountConfig;
+  tools?: (Tool | ToolClass)[];
+  /**
+   * Agent Skills configuration.
+   * Scans a mount path for skills and injects their metadata into the system prompt.
+   * @see https://agentskills.io/specification
+   */
+  skills?: {
+    /** Mount path where skills are stored, e.g. "/knowledge/skills/" */
+    path: string;
+  };
+  maxTurns?: number;
+  /**
+   * Retry configuration for transient LLM failures.
+   * When set, LLM calls that throw are retried with exponential backoff.
+   * By default retries on any error — use `retryOn` to filter.
+   */
+  retry?: RetryConfig;
+  logger?: Logger;
+}
+
+/**
+ * Configuration for retrying failed LLM calls.
+ *
+ * Defaults retry on every error. Provide `retryOn` to be selective
+ * (e.g. only retry HTTP 5xx but not 4xx auth errors).
+ */
+export interface RetryConfig {
+  /**
+   * Maximum number of retry attempts after the initial call (default: 2).
+   * Total attempts = maxRetries + 1.
+   * For example, maxRetries=2 means the initial call plus 2 retries (3 attempts total).
+   */
+  maxRetries?: number;
+  /** Initial delay in ms before first retry (default: 1000) */
+  initialDelayMs?: number;
+  /** Backoff multiplier applied after each retry (default: 2) */
+  backoffMultiplier?: number;
+  /** Maximum delay cap in ms (default: 30000) */
+  maxDelayMs?: number;
+  /**
+   * Predicate to decide whether a given error should be retried.
+   * Return true to retry, false to fail immediately.
+   * Default: retry on any error.
+   */
+  retryOn?: (error: Error) => boolean;
+}
+
+export interface AgentResponse {
+  message: string;
+  reasoning?: string;
+  toolCalls?: ToolCallResult[];
+  turns: number;
+  finishReason: string | null;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface ToolCallResult {
+  turn: number;
+  toolCallId: string;
+  toolName: string;
+  arguments: any;
+  result: any;
+  success: boolean;
+  error?: string;
+}
+
+export interface ConversationState {
+  messages: LLMMessage[];
+  turnCount: number;
+  totalTokens: number;
+}
+
+// ============================================================================
+// Sandbox Types
+// ============================================================================
+
+export interface SandboxResult {
+  success: boolean;
+  result?: any;
+  error?: string;
+  executionTime?: number;
+  consoleOutput?: string[];
+}
+
+export interface SandboxOptions {
+  timeoutMs?: number;
+  memoryLimitBytes?: number;
+  logger?: Logger;
+  /** Additional bridge installers to run after standard bridges */
+  bridgeInstallers?: BridgeInstaller[];
+}
+
+// ----------------------------------------------------------------------------
+// Typed Sandbox Globals
+// ----------------------------------------------------------------------------
+
+/** An async function to expose in the sandbox — always returns a promise to sandbox code */
+export interface AsyncSandboxGlobal {
+  kind: 'async';
+  fn: (...args: any[]) => Promise<any>;
+}
+
+/** A sync function to expose in the sandbox — returns the value directly */
+export interface SyncSandboxGlobal {
+  kind: 'sync';
+  fn: (...args: any[]) => any;
+}
+
+/** An object with typed methods and optional static properties */
+export interface ObjectSandboxGlobal {
+  kind: 'object';
+  methods: Record<string, AsyncSandboxGlobal | SyncSandboxGlobal>;
+  properties?: Record<string, any>;
+}
+
+/** A single sandbox global entry */
+export type SandboxGlobal =
+  | AsyncSandboxGlobal
+  | SyncSandboxGlobal
+  | ObjectSandboxGlobal
+  | number
+  | string
+  | boolean
+  | null
+  | undefined
+  | any[]
+  | Record<string, unknown>;
+
+/** Map of named globals to inject into the sandbox */
+export interface SandboxGlobals {
+  [key: string]: SandboxGlobal;
+}
+
+// Helper constructors for typed globals
+
+/** Wrap an async function for sandbox injection */
+export function sandboxAsync(fn: (...args: any[]) => Promise<any>): AsyncSandboxGlobal {
+  return { kind: 'async', fn };
+}
+
+/** Wrap a sync function for sandbox injection */
+export function sandboxSync(fn: (...args: any[]) => any): SyncSandboxGlobal {
+  return { kind: 'sync', fn };
+}
+
+/** Wrap an object with typed methods for sandbox injection */
+export function sandboxObject(
+  methods: Record<string, AsyncSandboxGlobal | SyncSandboxGlobal>,
+  properties?: Record<string, any>
+): ObjectSandboxGlobal {
+  return { kind: 'object', methods, properties };
+}
+
+// ============================================================================
+// Agent Streaming Event Types
+// ============================================================================
+
+export type AgentEventType =
+  | 'tool_call_start'
+  | 'tool_call_end'
+  | 'llm_response'
+  | 'turn_complete';
+
+export interface AgentEvent {
+  type: AgentEventType;
+  turn: number;
+  toolCall?: {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  };
+  toolResult?: {
+    id: string;
+    name: string;
+    result: unknown;
+    success: boolean;
+    error?: string;
+  };
+  message?: string;
+  finishReason?: string | null;
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
+}
+
+// ============================================================================
+// Logger Types
+// ============================================================================
+
+export interface Logger {
+  info(message: string, data?: any): void;
+  warn(message: string, data?: any): void;
+  error(message: string, data?: any): void;
+  debug(message: string, data?: any): void;
+  with?(data: any): Logger;
+  withError?(error: Error): Logger;
+}
+
+// ============================================================================
+// Tool Class Interface
+// ============================================================================
+
+export interface ToolClass {
+  new (context: ToolContext): Tool;
+}

package/tsconfig.eslint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@liquidmetal-ai/typescript-config/base.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "WebWorker"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": false,
+    "outDir": "./dist",
+    "strict": true,
+    "types": ["@liquidmetal-ai/raindrop-framework"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["eslint.config.js", "node_modules", "dist", "examples", "src/**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    testTimeout: 10000,
+    passWithNoTests: true
+  },
+  plugins: [
+    {
+      name: 'wasm-stub',
+      enforce: 'pre',
+      resolveId(id) {
+        // Stub the /wasm export from @jitl packages.
+        // In Raindrop this resolves to a WebAssembly.Module,
+        // but in Node.js tests the quickjs library loads WASM from disk
+        // automatically, so we just need to prevent the import from failing.
+        if (id.includes('/wasm') && id.includes('@jitl')) {
+          return '\0virtual:wasm-stub';
+        }
+      },
+      load(id) {
+        if (id === '\0virtual:wasm-stub') {
+          return 'export default undefined;';
+        }
+      }
+    }
+  ],
+  build: {
+    target: 'esnext'
+  }
+});