@liquidmetal-ai/precip 1.0.0

package/src/mounts/zod-to-string.ts

@@ -0,0 +1,213 @@
+/**
+ * Zod Schema to Human-Readable Type String
+ *
+ * Converts Zod schemas to concise type strings for prompt documentation.
+ * Designed to give LLMs enough information to understand the API without overwhelming detail.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Convert a Zod schema to a human-readable type string.
+ *
+ * Examples:
+ * - z.string() → "string"
+ * - z.object({ name: z.string() }) → "{ name: string }"
+ * - z.array(z.number()) → "Array<number>"
+ * - z.object({ name: z.string().optional() }) → "{ name?: string }"
+ * - z.enum(['a', 'b']) → "'a' | 'b'"
+ */
+export function zodToTypeString(schema: z.ZodType, depth: number = 0): string {
+  // Prevent infinite recursion for deeply nested types
+  if (depth > 5) {
+    return '...';
+  }
+
+  // Handle ZodOptional - unwrap and mark
+  if (schema instanceof z.ZodOptional) {
+    return zodToTypeString(schema.unwrap(), depth);
+  }
+
+  // Handle ZodNullable
+  if (schema instanceof z.ZodNullable) {
+    return `${zodToTypeString(schema.unwrap(), depth)} | null`;
+  }
+
+  // Handle ZodDefault - unwrap
+  if (schema instanceof z.ZodDefault) {
+    return zodToTypeString(schema._def.innerType, depth);
+  }
+
+  // Primitives
+  if (schema instanceof z.ZodString) {
+    return 'string';
+  }
+  if (schema instanceof z.ZodNumber) {
+    return 'number';
+  }
+  if (schema instanceof z.ZodBoolean) {
+    return 'boolean';
+  }
+  if (schema instanceof z.ZodNull) {
+    return 'null';
+  }
+  if (schema instanceof z.ZodUndefined) {
+    return 'undefined';
+  }
+  if (schema instanceof z.ZodVoid) {
+    return 'void';
+  }
+  if (schema instanceof z.ZodAny) {
+    return 'any';
+  }
+  if (schema instanceof z.ZodUnknown) {
+    return 'unknown';
+  }
+  if (schema instanceof z.ZodNever) {
+    return 'never';
+  }
+
+  // Literal
+  if (schema instanceof z.ZodLiteral) {
+    const val = schema._def.value;
+    if (typeof val === 'string') {
+      return `'${val}'`;
+    }
+    return String(val);
+  }
+
+  // Enum
+  if (schema instanceof z.ZodEnum) {
+    const values = schema._def.values as string[];
+    return values.map(v => `'${v}'`).join(' | ');
+  }
+
+  // Native Enum
+  if (schema instanceof z.ZodNativeEnum) {
+    return 'enum';
+  }
+
+  // Array
+  if (schema instanceof z.ZodArray) {
+    const itemType = zodToTypeString(schema._def.type, depth + 1);
+    return `Array<${itemType}>`;
+  }
+
+  // Object
+  if (schema instanceof z.ZodObject) {
+    const shape = schema._def.shape();
+    const entries = Object.entries(shape);
+
+    // Empty object
+    if (entries.length === 0) {
+      return '{}';
+    }
+
+    // For shallow depth or few properties, show inline
+    if (depth < 2 && entries.length <= 4) {
+      const props = entries.map(([key, value]) => {
+        const isOptional = value instanceof z.ZodOptional;
+        const typeStr = zodToTypeString(value as z.ZodType, depth + 1);
+        return `${key}${isOptional ? '?' : ''}: ${typeStr}`;
+      });
+      return `{ ${props.join(', ')} }`;
+    }
+
+    // For deeper nesting or many properties, abbreviate
+    const propNames = entries.map(([key, value]) => {
+      const isOptional = value instanceof z.ZodOptional;
+      return `${key}${isOptional ? '?' : ''}`;
+    });
+    return `{ ${propNames.join(', ')} }`;
+  }
+
+  // Record
+  if (schema instanceof z.ZodRecord) {
+    const valueType = zodToTypeString(schema._def.valueType, depth + 1);
+    return `Record<string, ${valueType}>`;
+  }
+
+  // Map
+  if (schema instanceof z.ZodMap) {
+    const keyType = zodToTypeString(schema._def.keyType, depth + 1);
+    const valueType = zodToTypeString(schema._def.valueType, depth + 1);
+    return `Map<${keyType}, ${valueType}>`;
+  }
+
+  // Set
+  if (schema instanceof z.ZodSet) {
+    const valueType = zodToTypeString(schema._def.valueType, depth + 1);
+    return `Set<${valueType}>`;
+  }
+
+  // Tuple
+  if (schema instanceof z.ZodTuple) {
+    const items = schema._def.items as z.ZodType[];
+    const itemTypes = items.map(item => zodToTypeString(item, depth + 1));
+    return `[${itemTypes.join(', ')}]`;
+  }
+
+  // Union
+  if (schema instanceof z.ZodUnion) {
+    const options = schema._def.options as z.ZodType[];
+    const types = options.map(opt => zodToTypeString(opt, depth + 1));
+    return types.join(' | ');
+  }
+
+  // Discriminated Union
+  if (schema instanceof z.ZodDiscriminatedUnion) {
+    const options = schema._def.options as z.ZodType[];
+    const types = options.map(opt => zodToTypeString(opt, depth + 1));
+    return types.join(' | ');
+  }
+
+  // Intersection
+  if (schema instanceof z.ZodIntersection) {
+    const left = zodToTypeString(schema._def.left, depth + 1);
+    const right = zodToTypeString(schema._def.right, depth + 1);
+    return `${left} & ${right}`;
+  }
+
+  // Promise
+  if (schema instanceof z.ZodPromise) {
+    const inner = zodToTypeString(schema._def.type, depth + 1);
+    return `Promise<${inner}>`;
+  }
+
+  // Function
+  if (schema instanceof z.ZodFunction) {
+    return 'Function';
+  }
+
+  // Date
+  if (schema instanceof z.ZodDate) {
+    return 'Date';
+  }
+
+  // Effects (refinements, transforms, etc.) - unwrap
+  if (schema instanceof z.ZodEffects) {
+    return zodToTypeString(schema._def.schema, depth);
+  }
+
+  // Branded - unwrap
+  if (schema instanceof z.ZodBranded) {
+    return zodToTypeString(schema._def.type, depth);
+  }
+
+  // Lazy - try to resolve
+  if (schema instanceof z.ZodLazy) {
+    try {
+      return zodToTypeString(schema._def.getter(), depth + 1);
+    } catch {
+      return 'lazy';
+    }
+  }
+
+  // Pipeline - show output type
+  if (schema instanceof z.ZodPipeline) {
+    return zodToTypeString(schema._def.out, depth);
+  }
+
+  // Fallback
+  return 'unknown';
+}

package/src/presets/agent-tools.ts

@@ -0,0 +1,57 @@
+/**
+ * Prebuilt Agent Tool Sets
+ *
+ * Two opinionated tool configurations for common agent patterns:
+ *
+ * **ScriptAgentTools** — Code-first agent. Scripts and ad-hoc code handle all data access
+ * through sandbox bridges (read, write, query, search, etc.). Lean prompt, maximum flexibility.
+ *   - run_script: Execute scripts from skill mounts with args
+ *   - run_code: Ad-hoc JavaScript for anything a script doesn't cover
+ *   - read_file: Read files directly (SKILL.md, configs, quick lookups)
+ *
+ * **ToolAgentTools** — Tool-first agent. Each operation is a discrete, auditable tool call.
+ * Every action is visible in the conversation. More constrained, more transparent.
+ *   - File CRUD: read_file, write_file, list_files, delete_file
+ *   - SQL: sql_query, sql_execute, sql_batch
+ *   - Search: semantic_search, chunk_search, get_search_page
+ *   - Actor state: read_state, write_state, list_state, delete_state
+ *
+ * Mix and match, or build your own:
+ *   tools: [...ScriptAgentTools, SqlQueryTool]
+ */
+
+import type { Tool } from '../types.js';
+import { ScriptExecutionTool } from '../tools/script-tools.js';
+import { CodeExecutionTool } from '../tools/code-tools.js';
+import { ReadFileTool, FileTools } from '../tools/file-tools.js';
+import { SqlTools } from '../tools/sql-tools.js';
+import { SmartBucketTools } from '../tools/smartbucket-tools.js';
+import { ActorStorageTools } from '../tools/actor-storage-tools.js';
+
+/**
+ * Code-first agent tools.
+ *
+ * Scripts and ad-hoc code handle data access through sandbox bridges.
+ * Lean prompt (~1,200 tokens for tool descriptions). Maximum flexibility.
+ *
+ * Tools: run_script, run_code, read_file
+ */
+export const ScriptAgentTools: Tool[] = [ScriptExecutionTool, CodeExecutionTool, ReadFileTool];
+
+/**
+ * Tool-first agent tools.
+ *
+ * Each operation is a discrete, auditable tool call. Every action visible
+ * in the conversation history. More constrained, more transparent.
+ *
+ * Tools: read_file, write_file, list_files, delete_file,
+ *        sql_query, sql_execute, sql_batch,
+ *        semantic_search, chunk_search, get_search_page,
+ *        read_state, write_state, list_state, delete_state
+ */
+export const ToolAgentTools: Tool[] = [
+  ...FileTools,
+  ...SqlTools,
+  ...SmartBucketTools,
+  ...ActorStorageTools
+];

package/src/presets/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Prebuilt agent presets
+ */
+
+export { ScriptAgentTools, ToolAgentTools } from './agent-tools.js';