agents-library 1.1.0

package/dist/producer-tool-utils.d.ts

@@ -0,0 +1,474 @@
+/**
+ * Producer Tool Utilities
+ * ========================
+ *
+ * Shared utilities for agent-producer to invoke shrimp-task-manager tools
+ * via KĀDI broker protocol with consistent error handling and retry logic.
+ *
+ * Includes Option C orchestration pattern (Claude API streaming with tool invocation)
+ * for agent-producer workflow orchestration.
+ *
+ * Design Principles:
+ * - Standardized error classification for retry logic
+ * - Configurable timeout with sensible defaults
+ * - Type-safe result handling with discriminated unions
+ * - Graceful degradation on failure
+ * - Streaming-first architecture with tool interruption support
+ *
+ * @module producer-tool-utils
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { KadiClient } from '@kadi.build/core';
+import { ErrorType } from './types/tool-schemas.js';
+/**
+ * Options for invokeShrimTool
+ *
+ * @property timeout - Timeout in milliseconds (default: 30000)
+ * @property targetAgent - Target agent ID (default: 'mcp-server-shrimp-agent-playground')
+ */
+export interface InvokeOptions {
+    /**
+     * Timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Target agent ID that provides the shrimp tools
+     * @default 'mcp-server-shrimp-agent-playground'
+     */
+    targetAgent?: string;
+    /**
+     * KadiClient instance for async response handling (optional)
+     * Required if the tool returns {status: "pending"} and you want to wait for the async result
+     */
+    client?: KadiClient;
+}
+/**
+ * Structured result from shrimp tool invocation
+ *
+ * Uses discriminated union pattern for type-safe error handling.
+ * Different from types/tool-schemas.ts ToolInvocationResult which is for KĀDI protocol.
+ */
+export interface ShrimpToolResult {
+    /**
+     * Success flag - use for type narrowing
+     */
+    success: boolean;
+    /**
+     * Result data (present when success=true)
+     */
+    data?: any;
+    /**
+     * Error details (present when success=false)
+     */
+    error?: {
+        /**
+         * Error classification for retry logic
+         */
+        type: ErrorType;
+        /**
+         * Human-readable error message
+         */
+        message: string;
+        /**
+         * Original error object (if available)
+         */
+        original?: Error;
+    };
+}
+/**
+ * Invoke shrimp-task-manager tool via KĀDI broker protocol
+ *
+ * Provides consistent error handling, timeout management, and error classification
+ * for tools exposed by shrimp-task-manager MCP server. Uses KĀDI protocol.invokeTool()
+ * with standardized response handling.
+ *
+ * Error Classification:
+ * - **Transient errors** (retry recommended):
+ *   - Network errors (ECONNREFUSED, ENOTFOUND)
+ *   - Timeout errors
+ *   - Rate limiting (429)
+ *   - Service unavailable (503)
+ *
+ * - **Permanent errors** (fail-fast):
+ *   - Validation errors (400)
+ *   - Authentication errors (401, 403)
+ *   - Not found errors (404)
+ *   - Invalid input errors
+ *
+ * Response Handling:
+ * - Success (200-299): Returns { success: true, data: responseData }
+ * - Client error (400-499): Returns { success: false, error: { type: 'permanent', message } }
+ * - Server error (500-599): Returns { success: false, error: { type: 'transient', message } }
+ * - Network error: Returns { success: false, error: { type: 'transient', message } }
+ *
+ * @param protocol - KĀDI broker protocol instance (from client.getBrokerProtocol())
+ * @param toolName - Name of shrimp tool to invoke (e.g., 'shrimp_plan_task')
+ * @param params - Tool input parameters (validated by tool's input schema)
+ * @param options - Optional configuration (timeout, targetAgent)
+ * @returns Structured result with success flag and data/error
+ *
+ * @example
+ * ```typescript
+ * // Success case
+ * const result = await invokeShrimTool(
+ *   protocol,
+ *   'shrimp_plan_task',
+ *   { description: 'Implement feature X', requirements: 'Must be async' }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Task planned:', result.data);
+ * } else {
+ *   if (result.error.type === ErrorType.Transient) {
+ *     // Retry with exponential backoff
+ *     await retryWithBackoff(() => invokeShrimTool(...));
+ *   } else {
+ *     // Fail-fast on permanent errors
+ *     console.error('Permanent error:', result.error.message);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom timeout
+ * const result = await invokeShrimTool(
+ *   protocol,
+ *   'shrimp_execute_task',
+ *   { taskId: '123' },
+ *   { timeout: 60000 } // 60 seconds
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom target agent
+ * const result = await invokeShrimTool(
+ *   protocol,
+ *   'shrimp_split_tasks',
+ *   { tasksRaw: JSON.stringify([...]), updateMode: 'append' },
+ *   { targetAgent: 'mcp-server-shrimp-custom' }
+ * );
+ * ```
+ */
+export declare function invokeShrimTool(protocol: any, toolName: string, params: any, options?: InvokeOptions): Promise<ShrimpToolResult>;
+/**
+ * Type guard to check if result is a success
+ *
+ * @param result - Tool invocation result
+ * @returns True if result is success
+ *
+ * @example
+ * ```typescript
+ * if (isToolSuccess(result)) {
+ *   console.log('Success:', result.data);
+ * }
+ * ```
+ */
+export declare function isToolSuccess(result: ShrimpToolResult): result is ShrimpToolResult & {
+    success: true;
+    data: any;
+};
+/**
+ * Type guard to check if result is a failure
+ *
+ * @param result - Tool invocation result
+ * @returns True if result is failure
+ *
+ * @example
+ * ```typescript
+ * if (isToolFailure(result)) {
+ *   console.error('Failure:', result.error.message);
+ * }
+ * ```
+ */
+export declare function isToolFailure(result: ShrimpToolResult): result is ShrimpToolResult & {
+    success: false;
+    error: {
+        type: ErrorType;
+        message: string;
+    };
+};
+/**
+ * Tool definition for Claude API
+ *
+ * Matches Anthropic SDK tool definition structure.
+ */
+export interface ToolDefinition {
+    /**
+     * Tool name (must be unique)
+     */
+    name: string;
+    /**
+     * Human-readable tool description for Claude
+     */
+    description: string;
+    /**
+     * Input schema using JSON Schema format
+     */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+/**
+ * Record of a tool invocation during orchestration
+ *
+ * Used for debugging and analysis of tool usage patterns.
+ */
+export interface ToolInvocation {
+    /**
+     * Tool name that was invoked
+     */
+    toolName: string;
+    /**
+     * Input parameters passed to tool
+     */
+    input: any;
+    /**
+     * Result returned from tool (success or error)
+     */
+    result: ShrimpToolResult;
+    /**
+     * Timestamp when tool was invoked
+     */
+    timestamp: string;
+    /**
+     * Duration of tool invocation in milliseconds
+     */
+    durationMs: number;
+}
+/**
+ * Options for orchestrateWithClaude
+ */
+export interface OrchestrationOptions {
+    /**
+     * Maximum tokens for Claude response
+     * @default 8000
+     */
+    max_tokens?: number;
+    /**
+     * Temperature for Claude response (0-1)
+     * @default 1.0
+     */
+    temperature?: number;
+    /**
+     * System prompts for Claude
+     * @default []
+     */
+    system?: string[];
+    /**
+     * Claude model to use
+     * @default 'claude-sonnet-4-5-20250929'
+     */
+    model?: string;
+    /**
+     * Timeout for tool invocations in milliseconds
+     * @default 30000
+     */
+    toolTimeout?: number;
+    /**
+     * Target agent for tool invocations
+     * @default 'mcp-server-shrimp-agent-playground'
+     */
+    targetAgent?: string;
+    /**
+     * KadiClient instance for async response handling (optional)
+     * Required if tools return {status: "pending"} and you want to wait for async results
+     */
+    client?: KadiClient;
+}
+/**
+ * Result from orchestrateWithClaude
+ */
+export interface OrchestrationResult {
+    /**
+     * Accumulated text response from Claude
+     */
+    text: string;
+    /**
+     * Log of all tool invocations during orchestration
+     */
+    toolInvocations: ToolInvocation[];
+    /**
+     * Whether orchestration completed successfully
+     */
+    success: boolean;
+    /**
+     * Error message if orchestration failed
+     */
+    error?: string;
+}
+/**
+ * Orchestrate workflow using Claude API streaming with tool invocation (Option C pattern)
+ *
+ * Implements agent-producer Option C orchestration flow:
+ * 1. Stream Claude API response with tool definitions
+ * 2. When Claude requests tool use, pause stream
+ * 3. Invoke tool via invokeShrimTool() with KĀDI protocol
+ * 4. Resume stream with tool_result
+ * 5. Accumulate text blocks for final response
+ * 6. Log all tool invocations for debugging
+ *
+ * Streaming Architecture:
+ * - Uses Anthropic SDK streaming API for low-latency responses
+ * - Handles streaming interruptions gracefully (tool_use blocks)
+ * - Accumulates partial text blocks into final response
+ * - Maintains tool invocation log for analysis
+ *
+ * Error Handling:
+ * - Tool invocation failures are passed back to Claude as error tool_result
+ * - Stream errors are caught and returned in OrchestrationResult
+ * - Graceful degradation if tool invocation fails
+ *
+ * @param anthropic - Anthropic SDK client instance
+ * @param protocol - KĀDI broker protocol instance (from client.getBrokerProtocol())
+ * @param prompt - User prompt to send to Claude
+ * @param availableTools - Array of tool definitions Claude can use
+ * @param options - Optional configuration (max_tokens, temperature, system prompts, etc.)
+ * @returns Orchestration result with accumulated text and tool invocation log
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await orchestrateWithClaude(
+ *   anthropic,
+ *   protocol,
+ *   'Plan a task to implement feature X',
+ *   [
+ *     {
+ *       name: 'shrimp_plan_task',
+ *       description: 'Create task plan with requirements',
+ *       input_schema: {
+ *         type: 'object',
+ *         properties: {
+ *           description: { type: 'string' },
+ *           requirements: { type: 'string' }
+ *         },
+ *         required: ['description']
+ *       }
+ *     }
+ *   ]
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Claude response:', result.text);
+ *   console.log('Tools invoked:', result.toolInvocations.length);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const result = await orchestrateWithClaude(
+ *   anthropic,
+ *   protocol,
+ *   'Split tasks for feature implementation',
+ *   tools,
+ *   {
+ *     max_tokens: 16000,
+ *     temperature: 0.7,
+ *     system: ['You are a task planning assistant'],
+ *     toolTimeout: 60000
+ *   }
+ * );
+ * ```
+ */
+export declare function orchestrateWithClaude(anthropic: Anthropic, protocol: any, prompt: string, availableTools: ToolDefinition[], options?: OrchestrationOptions): Promise<OrchestrationResult>;
+/**
+ * Metadata for tool event publication
+ *
+ * Required fields for standardized tool event structure across agent-producer.
+ */
+export interface EventMetadata {
+    /**
+     * Tool name that triggered the event
+     */
+    toolName: string;
+    /**
+     * Optional task ID associated with the tool invocation
+     */
+    taskId?: string;
+    /**
+     * Agent name publishing the event
+     * @default 'producer'
+     */
+    agentName?: string;
+}
+/**
+ * Publish standardized tool event to KĀDI broker
+ *
+ * Creates consistent event structure across all agent-producer tools with
+ * required metadata fields (timestamp, agentName, toolName, taskId).
+ *
+ * Topic Pattern: producer.tool.{eventType}
+ * - producer.tool.invoked - Tool invocation started
+ * - producer.tool.completed - Tool completed successfully
+ * - producer.tool.failed - Tool invocation failed
+ *
+ * Event Structure:
+ * ```typescript
+ * {
+ *   timestamp: string;      // ISO 8601 timestamp
+ *   agentName: string;      // 'producer' (default)
+ *   toolName: string;       // Tool that was invoked
+ *   taskId?: string;        // Optional task ID
+ *   ...data                 // Additional event data
+ * }
+ * ```
+ *
+ * Validation:
+ * - Topic pattern validated using validateTopicPattern()
+ * - Ensures backward compatibility with existing event conventions
+ *
+ * Error Handling:
+ * - Invalid topic patterns logged as warnings
+ * - Publishing failures logged but do not throw
+ * - Graceful degradation if broker unavailable
+ *
+ * @param client - KĀDI client instance (from KadiClient)
+ * @param eventType - Event type suffix (e.g., 'invoked', 'completed', 'failed')
+ * @param data - Event data payload (will be merged with metadata)
+ * @param metadata - Required metadata (toolName, optional taskId, agentName)
+ *
+ * @example
+ * ```typescript
+ * // Publish tool invocation event
+ * await publishToolEvent(
+ *   client,
+ *   'invoked',
+ *   { input: { description: 'Plan feature X' } },
+ *   { toolName: 'shrimp_plan_task', taskId: 'task-123' }
+ * );
+ * // Topic: producer.tool.invoked
+ * // Payload: { timestamp, agentName: 'producer', toolName, taskId, input: {...} }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Publish tool completion event
+ * await publishToolEvent(
+ *   client,
+ *   'completed',
+ *   { result: { success: true, data: {...} }, durationMs: 1500 },
+ *   { toolName: 'shrimp_execute_task', taskId: 'task-456' }
+ * );
+ * // Topic: producer.tool.completed
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Publish tool failure event
+ * await publishToolEvent(
+ *   client,
+ *   'failed',
+ *   { error: 'Validation failed', errorType: 'permanent' },
+ *   { toolName: 'shrimp_split_tasks', taskId: 'task-789' }
+ * );
+ * // Topic: producer.tool.failed
+ * ```
+ */
+export declare function publishToolEvent(client: KadiClient, eventType: string, data: any, metadata: EventMetadata): Promise<void>;
+//# sourceMappingURL=producer-tool-utils.d.ts.map

package/dist/producer-tool-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer-tool-utils.d.ts","sourceRoot":"","sources":["../src/producer-tool-utils.ts"],"names":[],"mappings":"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"}