@artyfacts/claude 1.2.6 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artyfacts/claude",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "Claude adapter for Artyfacts - Execute tasks using Claude Code CLI",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/executor-with-tools.ts

@@ -0,0 +1,402 @@
+/**
+ * Claude Executor with Tools Support
+ * 
+ * Executes tasks using Claude with full tool support.
+ * Uses the Anthropic SDK directly (not the CLI) to enable function calling.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { ContextFetcher, createContextFetcher, buildPromptWithContext, TaskFullContext } from './context';
+import { getToolsForPermissions, executeTool, ToolSchema, ApiClient, createApiClient } from './tools';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TaskContext {
+  /** Task ID (UUID or section_id) */
+  taskId: string;
+  /** Task heading/title */
+  heading: string;
+  /** Task content/description */
+  content: string;
+  /** Parent artifact ID */
+  artifactId: string;
+  /** Parent artifact title */
+  artifactTitle?: string;
+  /** Task priority (1=high, 2=medium, 3=low) */
+  priority?: number;
+  /** Additional context */
+  context?: Record<string, unknown>;
+}
+
+export interface ExecutionResult {
+  /** Whether execution was successful */
+  success: boolean;
+  /** The generated output */
+  output: string;
+  /** Summary of what was accomplished */
+  summary: string;
+  /** Any error message if failed */
+  error?: string;
+  /** The prompt that was used (for debugging) */
+  promptUsed?: string;
+  /** Tool calls made during execution */
+  toolCalls?: Array<{
+    name: string;
+    input: Record<string, unknown>;
+    output: unknown;
+  }>;
+}
+
+export interface ExecutorConfig {
+  /** Anthropic API key */
+  anthropicApiKey?: string;
+  /** Model to use (default: claude-sonnet-4-20250514) */
+  model?: string;
+  /** Timeout in milliseconds (default: 5 minutes) */
+  timeout?: number;
+  /** System prompt prefix */
+  systemPromptPrefix?: string;
+  /** Artyfacts API base URL */
+  baseUrl: string;
+  /** Artyfacts API key */
+  apiKey: string;
+  /** Agent's permissions (determines available tools) */
+  permissions?: string[];
+  /** Whether to use full context from API (default: true) */
+  useFullContext?: boolean;
+  /** Max tool call iterations (default: 10) */
+  maxToolIterations?: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_MAX_TOOL_ITERATIONS = 10;
+
+const DEFAULT_SYSTEM_PROMPT = `You are an AI agent working within the Artyfacts task management system.
+
+You have access to tools that let you interact with Artyfacts - creating sections, artifacts, agents, and more.
+
+Your job is to complete tasks assigned to you. For each task:
+1. Understand the requirements from the task heading and content
+2. Use the available tools to accomplish the task
+3. Provide a clear summary of what you did
+
+Guidelines:
+- USE TOOLS to create tangible outputs (sections, artifacts, agents)
+- Don't just describe what you would do - actually do it using the tools
+- Create sections on artifacts to document your work
+- If creating agents, use the create_agent tool with full details
+- If you cannot complete the task, explain why
+
+After completing the task, provide a brief summary of what you accomplished.`;
+
+// ============================================================================
+// Executor Class
+// ============================================================================
+
+export class ClaudeExecutorWithTools {
+  private config: ExecutorConfig;
+  private anthropic: Anthropic;
+  private contextFetcher: ContextFetcher | null = null;
+  private apiClient: ApiClient;
+  private tools: ToolSchema[];
+
+  constructor(config: ExecutorConfig) {
+    this.config = {
+      model: DEFAULT_MODEL,
+      timeout: DEFAULT_TIMEOUT,
+      maxToolIterations: DEFAULT_MAX_TOOL_ITERATIONS,
+      permissions: ['sections:read', 'sections:write', 'artifacts:read', 'org:read'],
+      ...config,
+    };
+
+    // Initialize Anthropic client
+    this.anthropic = new Anthropic({
+      apiKey: config.anthropicApiKey,
+    });
+
+    // Initialize context fetcher
+    this.contextFetcher = createContextFetcher({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+    });
+
+    // Initialize API client for tool handlers
+    this.apiClient = createApiClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+    });
+
+    // Get tools based on permissions
+    this.tools = getToolsForPermissions(this.config.permissions || []);
+    
+    console.log(`  🔧 Loaded ${this.tools.length} tools based on permissions`);
+  }
+
+  /**
+   * Execute a task using Claude with tools
+   */
+  async execute(task: TaskContext): Promise<ExecutionResult> {
+    const toolCalls: ExecutionResult['toolCalls'] = [];
+    
+    try {
+      let prompt: string;
+      let fullContext: TaskFullContext | null = null;
+
+      // Try to fetch full context if configured
+      const useFullContext = this.config.useFullContext !== false && this.contextFetcher;
+      
+      if (useFullContext) {
+        try {
+          fullContext = await this.contextFetcher!.fetchTaskContext(task.taskId);
+          prompt = buildPromptWithContext(fullContext);
+          console.log('  📚 Using full context (org, project, artifact, related sections)');
+        } catch (contextError) {
+          console.warn('  ⚠️  Could not fetch full context, using minimal prompt');
+          console.warn(`     ${contextError instanceof Error ? contextError.message : contextError}`);
+          prompt = this.buildTaskPrompt(task);
+        }
+      } else {
+        prompt = this.buildTaskPrompt(task);
+      }
+
+      // Build messages array
+      const messages: Anthropic.MessageParam[] = [
+        { role: 'user', content: prompt }
+      ];
+
+      // Build system prompt
+      const systemPrompt = this.config.systemPromptPrefix 
+        ? `${this.config.systemPromptPrefix}\n\n${DEFAULT_SYSTEM_PROMPT}`
+        : DEFAULT_SYSTEM_PROMPT;
+
+      // Convert tool schemas to Anthropic format
+      const anthropicTools: Anthropic.Tool[] = this.tools.map(tool => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.input_schema as unknown as Anthropic.Tool.InputSchema,
+      }));
+
+      // Execute with tool loop
+      let iterations = 0;
+      let finalOutput = '';
+      let finalSummary = '';
+
+      while (iterations < (this.config.maxToolIterations || DEFAULT_MAX_TOOL_ITERATIONS)) {
+        iterations++;
+
+        // Call Claude
+        const response = await this.anthropic.messages.create({
+          model: this.config.model || DEFAULT_MODEL,
+          max_tokens: 4096,
+          system: systemPrompt,
+          tools: anthropicTools.length > 0 ? anthropicTools : undefined,
+          messages,
+        });
+
+        // Check stop reason
+        if (response.stop_reason === 'end_turn') {
+          // Claude is done, extract final text
+          const textBlocks = response.content.filter(
+            (block): block is Anthropic.TextBlock => block.type === 'text'
+          );
+          finalOutput = textBlocks.map(b => b.text).join('\n');
+          break;
+        }
+
+        if (response.stop_reason === 'tool_use') {
+          // Process tool calls
+          const toolUseBlocks = response.content.filter(
+            (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use'
+          );
+
+          // Add assistant message with tool use
+          messages.push({ role: 'assistant', content: response.content });
+
+          // Process each tool call
+          const toolResults: Anthropic.ToolResultBlockParam[] = [];
+          
+          for (const toolUse of toolUseBlocks) {
+            console.log(`  🔧 Tool call: ${toolUse.name}`);
+            
+            // Execute the tool
+            const result = await executeTool(
+              toolUse.name,
+              toolUse.input as Record<string, unknown>,
+              this.apiClient
+            );
+
+            // Track tool calls
+            toolCalls.push({
+              name: toolUse.name,
+              input: toolUse.input as Record<string, unknown>,
+              output: result.data || result.error,
+            });
+
+            // Format result for Claude
+            const resultContent = result.success
+              ? JSON.stringify(result.data, null, 2)
+              : `Error: ${result.error}`;
+
+            toolResults.push({
+              type: 'tool_result',
+              tool_use_id: toolUse.id,
+              content: resultContent,
+              is_error: !result.success,
+            });
+
+            if (result.success) {
+              console.log(`    ✅ Success`);
+            } else {
+              console.log(`    ❌ Error: ${result.error}`);
+            }
+          }
+
+          // Add tool results to messages
+          messages.push({ role: 'user', content: toolResults });
+          
+          continue;
+        }
+
+        // Unexpected stop reason
+        console.warn(`  ⚠️  Unexpected stop reason: ${response.stop_reason}`);
+        break;
+      }
+
+      if (iterations >= (this.config.maxToolIterations || DEFAULT_MAX_TOOL_ITERATIONS)) {
+        console.warn('  ⚠️  Max tool iterations reached');
+      }
+
+      // Extract summary
+      const { content, summary } = this.parseResponse(finalOutput, task.heading);
+      finalSummary = summary;
+
+      return {
+        success: true,
+        output: content,
+        summary: finalSummary,
+        promptUsed: prompt,
+        toolCalls,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      
+      return {
+        success: false,
+        output: '',
+        summary: `Failed: ${errorMessage}`,
+        error: errorMessage,
+        toolCalls,
+      };
+    }
+  }
+
+  /**
+   * Build the task prompt (fallback when full context unavailable)
+   */
+  private buildTaskPrompt(task: TaskContext): string {
+    const parts: string[] = [];
+
+    // Task header
+    parts.push(`# Task: ${task.heading}`);
+    parts.push('');
+
+    // Artifact context
+    if (task.artifactTitle) {
+      parts.push(`**Artifact:** ${task.artifactTitle}`);
+    }
+    if (task.artifactId) {
+      parts.push(`**Artifact ID:** ${task.artifactId}`);
+    }
+    
+    // Priority
+    if (task.priority) {
+      const priorityLabels = ['High', 'Medium', 'Low'];
+      parts.push(`**Priority:** ${priorityLabels[task.priority - 1] || 'Medium'}`);
+    }
+    parts.push('');
+
+    // Task content
+    parts.push('## Description');
+    parts.push(task.content || 'No additional description provided.');
+    parts.push('');
+
+    // Additional context
+    if (task.context && Object.keys(task.context).length > 0) {
+      parts.push('## Additional Context');
+      parts.push('```json');
+      parts.push(JSON.stringify(task.context, null, 2));
+      parts.push('```');
+      parts.push('');
+    }
+
+    // Instructions
+    parts.push('## Instructions');
+    parts.push('Use the available tools to complete this task.');
+    parts.push('Create sections, artifacts, or agents as needed.');
+    parts.push('Provide a summary when done.');
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Parse the response to extract output and summary
+   */
+  private parseResponse(
+    fullOutput: string,
+    taskHeading: string
+  ): { content: string; summary: string } {
+    // Try to find SUMMARY: line
+    const summaryMatch = fullOutput.match(/SUMMARY:\s*(.+?)(?:\n|$)/i);
+    
+    if (summaryMatch) {
+      const summary = summaryMatch[1].trim();
+      const content = fullOutput.replace(/SUMMARY:\s*.+?(?:\n|$)/i, '').trim();
+      return { content, summary };
+    }
+
+    // No explicit summary, generate one from first line
+    const lines = fullOutput.split('\n').filter((l) => l.trim());
+    const firstLine = lines[0] || '';
+    
+    // Take first 100 chars as summary
+    const summary = firstLine.length > 100
+      ? `${firstLine.substring(0, 97)}...`
+      : firstLine || `Completed: ${taskHeading}`;
+
+    return { content: fullOutput, summary };
+  }
+
+  /**
+   * Get available tools for this executor
+   */
+  getAvailableTools(): ToolSchema[] {
+    return this.tools;
+  }
+
+  /**
+   * Update permissions (recalculates available tools)
+   */
+  setPermissions(permissions: string[]): void {
+    this.config.permissions = permissions;
+    this.tools = getToolsForPermissions(permissions);
+    console.log(`  🔧 Updated to ${this.tools.length} tools based on new permissions`);
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a Claude executor with tools support
+ */
+export function createExecutorWithTools(config: ExecutorConfig): ClaudeExecutorWithTools {
+  return new ClaudeExecutorWithTools(config);
+}

package/src/index.ts

@@ -101,3 +101,37 @@ export {
   createContextFetcher,
   buildPromptWithContext,
 } from './context';
+
+// Executor with Tools - Types
+export type {
+  ExecutorConfig as ExecutorWithToolsConfig,
+} from './executor-with-tools';
+
+// Executor with Tools - Classes
+export {
+  ClaudeExecutorWithTools,
+  createExecutorWithTools,
+} from './executor-with-tools';
+
+// Tools Registry
+export {
+  getAllToolSchemas,
+  getToolSchema,
+  getToolsForPermissions,
+  isToolAllowed,
+  getRequiredPermission,
+  permissionToTools,
+  executeTool,
+  handlers as toolHandlers,
+  createApiClient,
+} from './tools';
+
+// Tools Types
+export type {
+  ToolSchema,
+  ToolResult,
+  ToolHandler,
+  ApiClient,
+  ToolCall,
+  ToolCallResult,
+} from './tools';

package/src/tools/api-client.ts

@@ -0,0 +1,68 @@
+/**
+ * API Client for Artyfacts Tools
+ * 
+ * Simple HTTP client that wraps the Artyfacts API.
+ */
+
+import { ApiClient } from './types';
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  apiKey: string;
+  agentId?: string;
+}
+
+/**
+ * Create an API client for Artyfacts
+ */
+export function createApiClient(config: ApiClientConfig): ApiClient {
+  const headers: Record<string, string> = {
+    'Authorization': `Bearer ${config.apiKey}`,
+    'Content-Type': 'application/json',
+  };
+  
+  if (config.agentId) {
+    headers['X-Agent-ID'] = config.agentId;
+  }
+  
+  const baseUrl = config.baseUrl.replace(/\/$/, '');
+  
+  async function request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    
+    const options: RequestInit = {
+      method,
+      headers,
+    };
+    
+    if (body && method !== 'GET') {
+      options.body = JSON.stringify(body);
+    }
+    
+    const response = await fetch(url, options);
+    
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: 'Request failed' })) as { error?: string };
+      throw new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    // Handle empty responses
+    const text = await response.text();
+    if (!text) {
+      return {} as T;
+    }
+    
+    return JSON.parse(text);
+  }
+  
+  return {
+    get: <T>(path: string) => request<T>('GET', path),
+    post: <T>(path: string, body?: unknown) => request<T>('POST', path, body),
+    patch: <T>(path: string, body?: unknown) => request<T>('PATCH', path, body),
+    delete: <T>(path: string) => request<T>('DELETE', path),
+  };
+}