@liquidmetal-ai/precip 1.0.0

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "trailingComma": "none",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "avoid"
+}

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @liquidmetal-ai/precip
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @liquidmetal-ai/raindrop-framework@0.18.0

package/eslint.config.mjs

@@ -0,0 +1,28 @@
+import repo_config from '@liquidmetal-ai/eslint-config/eslint.config.mjs';
+
+/**
+ * @type {import('eslint').Linter.Config[]}
+ */
+const config = [
+  ...repo_config,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.eslint.json'
+      }
+    }
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'off'
+    }
+  },
+  {
+    // Vitest config is a config file, not part of the TypeScript project
+    ignores: ['vitest.config.ts']
+  }
+];
+
+export default config;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@liquidmetal-ai/precip",
+  "version": "1.0.0",
+  "description": "Agent SDK for building sophisticated LLM-powered agents on Raindrop",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./skills/frontmatter": {
+      "types": "./dist/skills/frontmatter.d.ts",
+      "default": "./dist/skills/frontmatter.js"
+    }
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "ai",
+    "raindrop"
+  ],
+  "author": "LiquidMetal AI",
+  "license": "MIT",
+  "dependencies": {
+    "@jitl/quickjs-ng-wasmfile-release-sync": "^0.31.0",
+    "quickjs-emscripten-core": "^0.31.0",
+    "zod": "^3"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.7.0",
+    "@typescript-eslint/parser": "^8.7.0",
+    "eslint": "^9.15.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.0.0",
+    "shx": "^0.4.0",
+    "typescript": "^5",
+    "vitest": "^3.1.3",
+    "@liquidmetal-ai/typescript-config": "0.0.0",
+    "@liquidmetal-ai/eslint-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@liquidmetal-ai/raindrop-framework": "0.18.0"
+  },
+  "scripts": {
+    "build": "shx rm -rf dist && tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint . --max-warnings=0",
+    "format": "prettier --write \"**/*.{ts,tsx,md}\""
+  }
+}

package/src/engine/agent.ts

@@ -0,0 +1,478 @@
+/**
+ * Precip Agent - Multi-turn conversation agent with tool calling
+ */
+
+import type {
+  AgentConfig,
+  AgentResponse,
+  AgentEvent,
+  LLMMessage,
+  ToolContext,
+  ToolCallResult,
+  ConversationState,
+  Logger
+} from '../types.js';
+import { createLLMProvider } from './llm-provider.js';
+import { MountManager } from '../mounts/mount-manager.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { discoverSkills, generateSkillsPrompt } from '../skills/index.js';
+
+export class PrecipAgent {
+  private llmProvider: ReturnType<typeof createLLMProvider>;
+  private mountManager: MountManager;
+  private toolRegistry: ToolRegistry;
+  private systemPrompt: string;
+  private maxTurns: number;
+  private logger?: Logger;
+  private conversationState: ConversationState;
+  private config: AgentConfig;
+  private initialized: boolean = false;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.logger = config.logger;
+    this.maxTurns = config.maxTurns || 10;
+
+    // Initialize LLM provider
+    this.llmProvider = createLLMProvider(config.llm, this.logger, config.retry);
+
+    // Initialize mount manager
+    this.mountManager = new MountManager(config.mounts || {}, this.logger);
+
+    // Build system prompt with mounts description (skills added async via init())
+    this.systemPrompt = this.buildSystemPrompt(
+      config.system || 'You are a helpful assistant.',
+      ''
+    );
+
+    // Initialize tool registry
+    this.toolRegistry = new ToolRegistry(this.logger);
+
+    // Register tools
+    if (config.tools) {
+      for (const tool of config.tools) {
+        if (typeof tool === 'function') {
+          // Tool class constructor
+          const toolContext: ToolContext = {
+            mounts: this.mountManager,
+            logger: this.logger
+          };
+          const toolInstance = new (tool as any)(toolContext);
+          this.toolRegistry.register(toolInstance);
+        } else {
+          // Tool instance
+          this.toolRegistry.register(tool);
+        }
+      }
+    }
+
+    // Initialize conversation state
+    this.conversationState = {
+      messages: [],
+      turnCount: 0,
+      totalTokens: 0
+    };
+  }
+
+  /**
+   * Initialize async components (skills discovery).
+   * Called automatically on first run() if not called explicitly.
+   *
+   * Call this explicitly if you want to control when skill discovery happens:
+   * ```typescript
+   * const agent = new PrecipAgent(config);
+   * await agent.init(); // discover skills now
+   * const response = await agent.run("...");
+   * ```
+   */
+  async init(): Promise<void> {
+    if (this.initialized) return;
+
+    if (this.config.skills) {
+      const skills = await discoverSkills(
+        this.mountManager,
+        this.config.skills,
+        this.logger
+      );
+
+      const skillsPrompt = generateSkillsPrompt(skills);
+      this.systemPrompt = this.buildSystemPrompt(
+        this.config.system || 'You are a helpful assistant.',
+        skillsPrompt
+      );
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Build system prompt with mounts description and skills appended
+   */
+  private buildSystemPrompt(baseSystemPrompt: string, skillsPrompt: string): string {
+    const mountsDescription = this.mountManager.getMountsDescription();
+
+    let prompt = baseSystemPrompt;
+
+    if (mountsDescription) {
+      prompt += mountsDescription;
+    }
+
+    if (skillsPrompt) {
+      prompt += skillsPrompt;
+    }
+
+    return prompt;
+  }
+
+  /**
+   * Run the agent with a user message (non-streaming).
+   * Internally consumes runStream() and returns the final response.
+   */
+  async run(userMessage: string): Promise<AgentResponse> {
+    const stream = this.runStream(userMessage);
+    let result: IteratorResult<AgentEvent, AgentResponse>;
+    do {
+      result = await stream.next();
+    } while (!result.done);
+    return result.value;
+  }
+
+  /**
+   * Run the agent with streaming events.
+   * Yields AgentEvent at each step; returns AgentResponse when done.
+   */
+  async *runStream(userMessage: string): AsyncGenerator<AgentEvent, AgentResponse, undefined> {
+    // Auto-initialize if not done yet (discovers skills)
+    await this.init();
+
+    // Reset conversation state for new run
+    this.conversationState = {
+      messages: [
+        { role: 'system', content: this.systemPrompt },
+        { role: 'user', content: userMessage }
+      ],
+      turnCount: 0,
+      totalTokens: 0
+    };
+
+    this.logger?.info?.('Starting agent run', { message: userMessage });
+
+    return yield* this.executeMultiTurnStream();
+  }
+
+  /**
+   * Continue an existing conversation (non-streaming).
+   */
+  async continue(userMessage: string): Promise<AgentResponse> {
+    const stream = this.continueStream(userMessage);
+    let result: IteratorResult<AgentEvent, AgentResponse>;
+    do {
+      result = await stream.next();
+    } while (!result.done);
+    return result.value;
+  }
+
+  /**
+   * Continue an existing conversation with streaming events.
+   */
+  async *continueStream(userMessage: string): AsyncGenerator<AgentEvent, AgentResponse, undefined> {
+    // Add user message to existing conversation
+    this.conversationState.messages.push({
+      role: 'user',
+      content: userMessage
+    });
+
+    this.logger?.info?.('Continuing conversation', { message: userMessage });
+
+    // Continue the multi-turn loop WITHOUT resetting state
+    return yield* this.executeMultiTurnStream();
+  }
+
+  /**
+   * Core multi-turn loop as an async generator.
+   * Yields AgentEvent at each step; returns the final AgentResponse.
+   */
+  private async *executeMultiTurnStream(): AsyncGenerator<AgentEvent, AgentResponse, undefined> {
+    const allToolResults: ToolCallResult[] = [];
+    let finalContent = '';
+    let finalFinishReason: string | null = null;
+
+    // Multi-turn conversation loop
+    while (this.conversationState.turnCount < this.maxTurns) {
+      this.conversationState.turnCount++;
+      const currentTurn = this.conversationState.turnCount;
+
+      // Get tool definitions
+      const toolDefinitions = this.toolRegistry.getToolDefinitions();
+
+      // Call LLM
+      const llmResponse = await this.llmProvider.chat(
+        this.conversationState.messages,
+        toolDefinitions.length > 0 ? toolDefinitions : undefined
+      );
+
+      // Update token usage
+      if (llmResponse.usage) {
+        this.conversationState.totalTokens += llmResponse.usage.totalTokens;
+      }
+
+      finalContent = llmResponse.content || '';
+      finalFinishReason = llmResponse.finishReason;
+
+      // Add assistant message to history
+      const assistantMessage: LLMMessage = {
+        role: 'assistant',
+        content: llmResponse.content
+      };
+
+      if (llmResponse.toolCalls.length > 0) {
+        assistantMessage.tool_calls = llmResponse.toolCalls;
+      }
+
+      this.conversationState.messages.push(assistantMessage);
+
+      // Yield LLM response event
+      yield {
+        type: 'llm_response',
+        turn: currentTurn,
+        message: llmResponse.content || undefined,
+        finishReason: llmResponse.finishReason,
+        usage: llmResponse.usage,
+      };
+
+      // If no tool calls, we're done!
+      if (llmResponse.toolCalls.length === 0) {
+        this.logger?.info?.('Agent run complete', {
+          turns: currentTurn,
+          toolCallsTotal: allToolResults.length
+        });
+
+        // Yield turn_complete
+        yield { type: 'turn_complete', turn: currentTurn };
+        break;
+      }
+
+      // Execute tool calls
+      for (const toolCall of llmResponse.toolCalls) {
+        let params: any = {};
+        try {
+          params = JSON.parse(toolCall.function.arguments);
+        } catch (_e) {
+          // Malformed tool arguments — report to the LLM so it can self-correct
+          this.logger?.warn?.('Failed to parse tool arguments', {
+            tool: toolCall.function.name,
+            arguments: toolCall.function.arguments,
+          });
+
+          const parseError = `Failed to parse tool arguments: invalid JSON in arguments string`;
+
+          allToolResults.push({
+            turn: currentTurn,
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            arguments: {},
+            result: null,
+            success: false,
+            error: parseError,
+          });
+
+          this.conversationState.messages.push({
+            role: 'tool',
+            tool_call_id: toolCall.id,
+            content: JSON.stringify({ error: parseError }),
+          });
+
+          yield {
+            type: 'tool_call_start',
+            turn: currentTurn,
+            toolCall: {
+              id: toolCall.id,
+              name: toolCall.function.name,
+              arguments: {},
+            },
+          };
+
+          yield {
+            type: 'tool_call_end',
+            turn: currentTurn,
+            toolResult: {
+              id: toolCall.id,
+              name: toolCall.function.name,
+              result: null,
+              success: false,
+              error: parseError,
+            },
+          };
+
+          continue;
+        }
+
+        // Yield tool_call_start
+        yield {
+          type: 'tool_call_start',
+          turn: currentTurn,
+          toolCall: {
+            id: toolCall.id,
+            name: toolCall.function.name,
+            arguments: params,
+          },
+        };
+
+        try {
+          // Execute tool
+          const toolContext: ToolContext = {
+            mounts: this.mountManager as any, // Pass mount manager
+            logger: this.logger
+          };
+
+          const result = await this.toolRegistry.execute(
+            toolCall.function.name,
+            params,
+            toolContext
+          );
+
+          // Record tool result
+          const toolResult: ToolCallResult = {
+            turn: currentTurn,
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            arguments: params,
+            result: result.result,
+            success: result.success,
+            error: result.error
+          };
+
+          allToolResults.push(toolResult);
+
+          // Add tool result to message history
+          const resultContent = result.success
+            ? this.truncateForContext(result.result, 4000)
+            : JSON.stringify({ error: result.error });
+
+          this.conversationState.messages.push({
+            role: 'tool',
+            tool_call_id: toolCall.id,
+            content: resultContent
+          });
+
+          // Yield tool_call_end
+          yield {
+            type: 'tool_call_end',
+            turn: currentTurn,
+            toolResult: {
+              id: toolCall.id,
+              name: toolCall.function.name,
+              result: result.result,
+              success: result.success,
+              error: result.error,
+            },
+          };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+
+          this.logger?.error?.('Tool execution error', {
+            tool: toolCall.function.name,
+            error: errorMessage
+          });
+
+          // Record error
+          allToolResults.push({
+            turn: currentTurn,
+            toolCallId: toolCall.id,
+            toolName: toolCall.function.name,
+            arguments: params,
+            result: null,
+            success: false,
+            error: errorMessage
+          });
+
+          // Add error to message history
+          this.conversationState.messages.push({
+            role: 'tool',
+            tool_call_id: toolCall.id,
+            content: JSON.stringify({ error: errorMessage })
+          });
+
+          // Yield tool_call_end with error
+          yield {
+            type: 'tool_call_end',
+            turn: currentTurn,
+            toolResult: {
+              id: toolCall.id,
+              name: toolCall.function.name,
+              result: null,
+              success: false,
+              error: errorMessage,
+            },
+          };
+        }
+      }
+
+      // Yield turn_complete
+      yield { type: 'turn_complete', turn: currentTurn };
+
+      // Continue to next turn...
+    }
+
+    // Check if we hit max turns
+    if (this.conversationState.turnCount >= this.maxTurns) {
+      this.logger?.warn?.('Agent hit max turns limit', {
+        maxTurns: this.maxTurns
+      });
+    }
+
+    return {
+      message: finalContent,
+      toolCalls: allToolResults.length > 0 ? allToolResults : undefined,
+      turns: this.conversationState.turnCount,
+      finishReason: finalFinishReason,
+      usage:
+        this.conversationState.totalTokens > 0
+          ? {
+              promptTokens: 0, // Not tracked separately
+              completionTokens: 0,
+              totalTokens: this.conversationState.totalTokens
+            }
+          : undefined
+    };
+  }
+
+  /**
+   * Get current conversation state
+   */
+  getConversation(): ConversationState {
+    return { ...this.conversationState };
+  }
+
+  /**
+   * Reset conversation
+   */
+  reset(): void {
+    this.conversationState = {
+      messages: [],
+      turnCount: 0,
+      totalTokens: 0
+    };
+  }
+
+  /**
+   * Get the full system prompt (base prompt + mounts description)
+   * Useful for debugging and testing
+   */
+  getSystemPrompt(): string {
+    return this.systemPrompt;
+  }
+
+  /**
+   * Truncate large results for context management
+   */
+  private truncateForContext(obj: any, maxLength: number = 4000): string {
+    const str = JSON.stringify(obj);
+    if (str.length <= maxLength) {
+      return str;
+    }
+
+    const truncated = str.substring(0, maxLength);
+    return truncated + `... [TRUNCATED: ${str.length - maxLength} more characters]`;
+  }
+}