@loopstack/claude-module 0.22.4 → 0.23.0

package/src/documents/claude-message-document.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { Document } from '@loopstack/common';
-
-export const ClaudeMessageDocumentSchema = z.object({
-  role: z.enum(['user', 'assistant']),
-  content: z.union([z.string(), z.array(z.any())]),
-  toolResults: z.array(z.any()).optional(),
-});
-
-export type ClaudeMessageDocumentContentType = z.infer<typeof ClaudeMessageDocumentSchema>;
-
-@Document({
-  schema: ClaudeMessageDocumentSchema,
-  uiConfig: __dirname + '/claude-message-document.yaml',
-})
-export class ClaudeMessageDocument {
-  role: 'user' | 'assistant';
-  content: string | any[];
-  toolResults?: any[];
-}

package/src/documents/claude-message-document.yaml

@@ -1,5 +0,0 @@
-tags:
-  - message
-ui:
-  widgets:
-    - widget: claude-message

package/src/documents/index.ts

@@ -1 +0,0 @@
-export * from './claude-message-document';

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from './claude.module';
-export * from './tools';
-export * from './documents';
-export * from './types';

package/src/schemas/claude-generate-tool-base.schema.ts

@@ -1,23 +0,0 @@
-import { z } from 'zod';
-
-export const ClaudeGenerateToolBaseSchema = z.object({
-  claude: z
-    .object({
-      model: z.string().optional(),
-      envApiKey: z.string().optional(),
-      maxTokens: z.number().optional(),
-      cache: z.boolean().optional(),
-    })
-    .optional(),
-  messages: z
-    .array(
-      z.object({
-        role: z.enum(['user', 'assistant']),
-        content: z.union([z.string(), z.array(z.any())]),
-      }),
-    )
-    .optional(),
-  system: z.string().optional(),
-  prompt: z.string().optional(),
-  messagesSearchTag: z.string().optional(),
-});

package/src/services/claude-client.service.ts

@@ -1,34 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Injectable } from '@nestjs/common';
-import { ClaudeModelConfig } from '../types';
-
-@Injectable()
-export class ClaudeClientService {
-  private getApiKey(envApiKey?: string): string {
-    const envVar = envApiKey ?? 'ANTHROPIC_API_KEY';
-    const apiKey = process.env[envVar];
-
-    if (!apiKey) {
-      throw new Error(`No API key found! Please make sure to provide "${envVar}" in your .env file.`);
-    }
-
-    return apiKey;
-  }
-
-  getClient(config?: ClaudeModelConfig): Anthropic {
-    const apiKey = this.getApiKey(config?.envApiKey);
-    return new Anthropic({ apiKey });
-  }
-
-  getModel(config?: ClaudeModelConfig): string {
-    const model = config?.model ?? process.env['CLAUDE_MODEL'];
-
-    if (!model) {
-      throw new Error(
-        'No model defined. Please provide CLAUDE_MODEL env var or set the claude.model parameter in the tool args.',
-      );
-    }
-
-    return model;
-  }
-}

package/src/services/claude-messages-helper.service.ts

@@ -1,41 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Injectable } from '@nestjs/common';
-import { DocumentEntity } from '@loopstack/common';
-
-@Injectable()
-export class ClaudeMessagesHelperService {
-  private searchMessages(documents: DocumentEntity[], tag: string): Anthropic.MessageParam[] {
-    return documents
-      .filter((document) => !document.isInvalidated && document.tags?.includes(tag))
-      .sort((a, b) => a.index - b.index)
-      .flatMap((document) => {
-        const content = document.content as {
-          role: 'user' | 'assistant';
-          content: string | Anthropic.ContentBlockParam[];
-          toolResults?: Anthropic.ToolResultBlockParam[];
-        };
-
-        // Combined document: expand into assistant message + user tool_result message
-        if (content.toolResults?.length) {
-          return [
-            { role: content.role, content: content.content } as Anthropic.MessageParam,
-            { role: 'user' as const, content: content.toolResults } as Anthropic.MessageParam,
-          ];
-        }
-
-        return [{ role: content.role, content: content.content } as Anthropic.MessageParam];
-      });
-  }
-
-  getMessages(
-    documents: DocumentEntity[],
-    args: { messages?: Anthropic.MessageParam[]; messagesSearchTag?: string },
-  ): Anthropic.MessageParam[] {
-    let messages: Anthropic.MessageParam[] | undefined = args.messages;
-    if (!messages?.length) {
-      messages = this.searchMessages(documents, args.messagesSearchTag ?? 'message');
-    }
-
-    return messages;
-  }
-}

package/src/services/claude-tools-helper.service.ts

@@ -1,36 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Injectable } from '@nestjs/common';
-import { toJSONSchema } from 'zod';
-import { ToolInterface, WorkflowInterface, getBlockArgsSchema, getBlockConfig } from '@loopstack/common';
-import { getBlockTool } from '@loopstack/common';
-import { WorkflowType } from '@loopstack/contracts/dist/types';
-
-@Injectable()
-export class ClaudeToolsHelperService {
-  getTools(tools: string[], parent: WorkflowInterface): Anthropic.Tool[] | undefined {
-    const toolDefinitions: Anthropic.Tool[] = [];
-
-    for (const toolName of tools) {
-      const tool = getBlockTool<ToolInterface>(parent, toolName);
-      if (!tool) {
-        throw new Error(`Tool with name ${toolName} not available in Workflow context.`);
-      }
-
-      const inputSchema = getBlockArgsSchema(tool);
-      const config = getBlockConfig<WorkflowType>(tool);
-      if (!config) {
-        throw new Error(`Block ${tool.constructor.name} is missing @BlockConfig decorator`);
-      }
-
-      const jsonSchema = inputSchema ? toJSONSchema(inputSchema) : { type: 'object' };
-
-      toolDefinitions.push({
-        name: toolName,
-        description: config.description ?? '',
-        input_schema: jsonSchema as Anthropic.Tool['input_schema'],
-      });
-    }
-
-    return toolDefinitions.length ? toolDefinitions : undefined;
-  }
-}

package/src/services/index.ts

@@ -1,3 +0,0 @@
-export * from './claude-client.service';
-export * from './claude-messages-helper.service';
-export * from './claude-tools-helper.service';

package/src/tools/claude-generate-document.tool.ts

@@ -1,29 +0,0 @@
-import { BaseTool, InjectTool, Tool, ToolResult } from '@loopstack/common';
-import {
-  ClaudeGenerateObject,
-  ClaudeGenerateObjectArgsType,
-  ClaudeGenerateObjectSchema,
-} from './claude-generate-object.tool';
-
-@Tool({
-  uiConfig: {
-    description: 'Generates a structured object using the Anthropic Claude API and creates it as a document',
-  },
-  schema: ClaudeGenerateObjectSchema,
-})
-export class ClaudeGenerateDocument extends BaseTool {
-  @InjectTool() private claudeGenerateObject!: ClaudeGenerateObject;
-
-  async call(args: ClaudeGenerateObjectArgsType): Promise<ToolResult> {
-    const generateResult = await this.claudeGenerateObject.call(args);
-    const entity = await this.repository.save(args.response.document, generateResult.data as Record<string, unknown>, {
-      id: args.response.id,
-      validate: 'skip',
-    });
-
-    return {
-      data: entity,
-      metadata: generateResult.metadata,
-    };
-  }
-}

package/src/tools/claude-generate-object.tool.ts

@@ -1,135 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Inject } from '@nestjs/common';
-import { toJSONSchema, z } from 'zod';
-import {
-  BaseTool,
-  DocumentClass,
-  Tool,
-  ToolResult,
-  getBlockTypeFromMetadata,
-  getDocumentSchema,
-} from '@loopstack/common';
-import { ClaudeGenerateToolBaseSchema } from '../schemas/claude-generate-tool-base.schema';
-import { ClaudeClientService } from '../services';
-import { ClaudeMessagesHelperService } from '../services';
-import { applyCacheBreakpoints } from '../utils/cache.utils';
-
-export const ClaudeGenerateObjectSchema = ClaudeGenerateToolBaseSchema.extend({
-  response: z.object({
-    id: z.string().optional(),
-    document: z.custom<DocumentClass>(
-      (val) => typeof val === 'function' && getBlockTypeFromMetadata(val as object) === 'document',
-    ),
-  }),
-}).strict();
-
-export type ClaudeGenerateObjectArgsType = z.infer<typeof ClaudeGenerateObjectSchema>;
-
-const STRUCTURED_OUTPUT_TOOL_NAME = 'structured_output';
-
-@Tool({
-  uiConfig: {
-    description: 'Generates a structured object using the Anthropic Claude API',
-  },
-  schema: ClaudeGenerateObjectSchema,
-})
-export class ClaudeGenerateObject extends BaseTool {
-  @Inject()
-  private readonly claudeClientService: ClaudeClientService;
-  @Inject()
-  private readonly claudeMessagesHelperService: ClaudeMessagesHelperService;
-
-  async call(args: ClaudeGenerateObjectArgsType): Promise<ToolResult> {
-    const client = this.claudeClientService.getClient(args.claude);
-    const model = this.claudeClientService.getModel(args.claude);
-
-    const messages: Anthropic.MessageParam[] = [];
-
-    if (args.prompt) {
-      messages.push({ role: 'user', content: args.prompt });
-    } else {
-      const resolved = this.claudeMessagesHelperService.getMessages(this.ctx.runtime.documents, {
-        messages: args.messages as Anthropic.MessageParam[],
-        messagesSearchTag: args.messagesSearchTag,
-      });
-      messages.push(...resolved);
-    }
-
-    const responseSchema = getDocumentSchema(args.response.document);
-    if (!responseSchema) {
-      throw new Error('Claude object generation source document must have a schema.');
-    }
-
-    const jsonSchema = toJSONSchema(responseSchema);
-
-    const response = await this.handleGenerateObject(client, {
-      model,
-      messages,
-      system: args.system,
-      maxTokens: args.claude?.maxTokens,
-      inputSchema: jsonSchema as Anthropic.Tool['input_schema'],
-      cache: args.claude?.cache,
-    });
-
-    return {
-      data: response.data,
-      metadata: {
-        usage: {
-          inputTokens: response.usage.input_tokens,
-          outputTokens: response.usage.output_tokens,
-          cacheCreationInputTokens: response.usage.cache_creation_input_tokens ?? 0,
-          cacheReadInputTokens: response.usage.cache_read_input_tokens ?? 0,
-        },
-      },
-    };
-  }
-
-  private async handleGenerateObject(
-    client: Anthropic,
-    options: {
-      model: string;
-      messages: Anthropic.MessageParam[];
-      system?: string;
-      maxTokens?: number;
-      inputSchema: Anthropic.Tool['input_schema'];
-      cache?: boolean;
-    },
-  ): Promise<{ data: unknown; usage: Anthropic.Usage }> {
-    const baseTool: Anthropic.Tool = {
-      name: STRUCTURED_OUTPUT_TOOL_NAME,
-      description: 'Return the structured output matching the schema.',
-      input_schema: options.inputSchema,
-    };
-
-    const { system, tools, messages } = options.cache
-      ? applyCacheBreakpoints({ system: options.system, tools: [baseTool], messages: options.messages })
-      : { system: options.system, tools: [baseTool], messages: options.messages };
-
-    const startTime = performance.now();
-    try {
-      const response = await client.messages.create({
-        model: options.model,
-        messages,
-        max_tokens: options.maxTokens ?? 4096,
-        ...(system ? { system } : {}),
-        tools: tools!,
-        tool_choice: { type: 'tool', name: STRUCTURED_OUTPUT_TOOL_NAME },
-      });
-
-      const toolUseBlock = response.content.find((block): block is Anthropic.ToolUseBlock => block.type === 'tool_use');
-
-      if (!toolUseBlock) {
-        throw new Error('Claude did not return a tool_use block for structured output.');
-      }
-
-      return {
-        data: toolUseBlock.input,
-        usage: response.usage,
-      };
-    } catch (error) {
-      const errorResponseTime = performance.now() - startTime;
-      console.error(`Request failed after ${errorResponseTime}ms:`, error);
-      throw error;
-    }
-  }
-}

package/src/tools/claude-generate-text.tool.ts

@@ -1,128 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Inject } from '@nestjs/common';
-import { z } from 'zod';
-import { BaseTool, Tool, ToolCallEntry, ToolCallsMap, ToolResult } from '@loopstack/common';
-import { ClaudeGenerateToolBaseSchema } from '../schemas/claude-generate-tool-base.schema';
-import { ClaudeClientService } from '../services';
-import { ClaudeMessagesHelperService } from '../services';
-import { ClaudeToolsHelperService } from '../services';
-import { ClaudeGenerateTextResult } from '../types';
-import { applyCacheBreakpoints } from '../utils/cache.utils';
-
-export const ClaudeGenerateTextSchema = ClaudeGenerateToolBaseSchema.extend({
-  tools: z.array(z.string()).optional(),
-}).strict();
-
-type ClaudeGenerateTextArgsType = z.infer<typeof ClaudeGenerateTextSchema>;
-
-@Tool({
-  uiConfig: {
-    description: 'Generates text using the Anthropic Claude API',
-  },
-  schema: ClaudeGenerateTextSchema,
-})
-export class ClaudeGenerateText extends BaseTool {
-  @Inject()
-  private readonly claudeClientService: ClaudeClientService;
-  @Inject()
-  private readonly claudeMessagesHelperService: ClaudeMessagesHelperService;
-  @Inject()
-  private readonly claudeToolsHelperService: ClaudeToolsHelperService;
-
-  async call(args: ClaudeGenerateTextArgsType): Promise<ToolResult<ClaudeGenerateTextResult>> {
-    const client = this.claudeClientService.getClient(args.claude);
-    const model = this.claudeClientService.getModel(args.claude);
-
-    const messages: Anthropic.MessageParam[] = [];
-
-    if (args.prompt) {
-      messages.push({ role: 'user', content: args.prompt });
-    } else {
-      const resolved = this.claudeMessagesHelperService.getMessages(this.ctx.runtime.documents, {
-        messages: args.messages as Anthropic.MessageParam[],
-        messagesSearchTag: args.messagesSearchTag,
-      });
-      messages.push(...resolved);
-    }
-
-    const tools = args.tools ? this.claudeToolsHelperService.getTools(args.tools, this.ctx.parent) : undefined;
-
-    const response = await this.handleGenerateText(client, {
-      model,
-      messages,
-      system: args.system,
-      maxTokens: args.claude?.maxTokens,
-      tools,
-      cache: args.claude?.cache,
-    });
-
-    const toolCalls = this.extractToolCalls(response);
-
-    return {
-      data: {
-        ...response,
-        ...(toolCalls ? { toolCalls } : {}),
-      },
-      metadata: {
-        usage: {
-          inputTokens: response.usage.input_tokens,
-          outputTokens: response.usage.output_tokens,
-          cacheCreationInputTokens: response.usage.cache_creation_input_tokens ?? 0,
-          cacheReadInputTokens: response.usage.cache_read_input_tokens ?? 0,
-        },
-      },
-    };
-  }
-
-  private extractToolCalls(response: Anthropic.Message): ToolCallsMap | null {
-    if (response.stop_reason !== 'tool_use') {
-      return null;
-    }
-
-    const toolCalls: ToolCallsMap = {};
-    for (const block of response.content) {
-      if (block.type === 'tool_use') {
-        toolCalls[block.name] = {
-          id: block.id,
-          name: block.name,
-          input: block.input,
-        } satisfies ToolCallEntry;
-      }
-    }
-
-    return Object.keys(toolCalls).length > 0 ? toolCalls : null;
-  }
-
-  private async handleGenerateText(
-    client: Anthropic,
-    options: {
-      model: string;
-      messages: Anthropic.MessageParam[];
-      system?: string;
-      maxTokens?: number;
-      tools?: Anthropic.Tool[];
-      cache?: boolean;
-    },
-  ): Promise<Anthropic.Message> {
-    const { system, tools, messages } = options.cache
-      ? applyCacheBreakpoints({ system: options.system, tools: options.tools, messages: options.messages })
-      : { system: options.system, tools: options.tools, messages: options.messages };
-
-    const startTime = performance.now();
-    try {
-      const stream = client.messages.stream({
-        model: options.model,
-        messages,
-        max_tokens: options.maxTokens ?? 4096,
-        ...(system ? { system } : {}),
-        ...(tools ? { tools } : {}),
-      });
-
-      return await stream.finalMessage();
-    } catch (error) {
-      const errorResponseTime = performance.now() - startTime;
-      console.error(`Request failed after ${errorResponseTime}ms:`, error);
-      throw error;
-    }
-  }
-}

package/src/tools/delegate-tool-calls.tool.ts

@@ -1,139 +0,0 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { Injectable, Logger } from '@nestjs/common';
-import { z } from 'zod';
-import {
-  BaseTool,
-  DocumentClass,
-  Tool,
-  ToolCallOptions,
-  ToolResult,
-  getBlockTool,
-  getBlockTypeFromMetadata,
-} from '@loopstack/common';
-import type { DelegateToolCallsResult, DelegateToolResultEntry } from '../types';
-
-const DelegateToolCallsSchema = z.object({
-  message: z.object({
-    id: z.string().optional(),
-    content: z.array(z.any()),
-  }),
-  document: z
-    .custom<DocumentClass>((val) => typeof val === 'function' && getBlockTypeFromMetadata(val as object) === 'document')
-    .optional(),
-  skipResponseMessage: z.boolean().optional(),
-  callback: z
-    .object({
-      transition: z.string(),
-    })
-    .optional(),
-});
-
-type DelegateToolCallsArgs = z.infer<typeof DelegateToolCallsSchema>;
-
-@Injectable()
-@Tool({
-  uiConfig: {
-    description: 'Delegate tool calls from an LLM response. Handles both sync tools and async task tools.',
-  },
-  schema: DelegateToolCallsSchema,
-})
-export class DelegateToolCalls extends BaseTool {
-  private readonly logger = new Logger(DelegateToolCalls.name);
-
-  async call(args: DelegateToolCallsArgs): Promise<ToolResult<DelegateToolCallsResult>> {
-    const contentBlocks = args.message.content as Anthropic.ContentBlock[];
-    const toolUseBlocks = contentBlocks.filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use');
-
-    if (toolUseBlocks.length === 0) {
-      return {
-        data: {
-          allCompleted: true,
-          toolResults: [],
-          message: args.message as DelegateToolCallsResult['message'],
-          pendingCount: 0,
-        },
-      };
-    }
-
-    // 1. Execute ALL tools in parallel, passing callback via options (not args)
-    const results = await Promise.all(
-      toolUseBlocks.map((block) => {
-        const toolCallback = args.callback
-          ? {
-              transition: args.callback.transition,
-              metadata: { toolUseId: block.id, toolName: block.name },
-            }
-          : undefined;
-        return this.executeTool(block, toolCallback ? { callback: toolCallback } : undefined);
-      }),
-    );
-
-    // 2. Build toolResults array — async tools signal via result.pending
-    let pendingCount = 0;
-    const toolResults: DelegateToolResultEntry[] = [];
-
-    for (let i = 0; i < toolUseBlocks.length; i++) {
-      const block = toolUseBlocks[i];
-      const result = results[i];
-
-      if (result.pending) {
-        pendingCount++;
-      } else {
-        toolResults.push({
-          type: 'tool_result',
-          tool_use_id: block.id,
-          content: result.data ? JSON.stringify(result.data, null, 2) : '',
-          is_error: !!result.error,
-        });
-      }
-    }
-
-    // 3. Create response document (tool call message)
-    if (args.document && !args.skipResponseMessage) {
-      await this.createResponseDocument(args.document, args, toolResults);
-    }
-
-    return {
-      data: {
-        allCompleted: pendingCount === 0,
-        toolResults,
-        message: args.message as DelegateToolCallsResult['message'],
-        pendingCount,
-      },
-    };
-  }
-
-  private async executeTool(block: Anthropic.ToolUseBlock, options?: ToolCallOptions): Promise<ToolResult> {
-    try {
-      const tool = getBlockTool<BaseTool>(this.ctx.parent, block.name);
-      if (!tool) {
-        throw new Error(`Tool with name ${block.name} not found.`);
-      }
-
-      return await tool.call(block.input as Record<string, unknown>, options);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      this.logger.error(`Tool "${block.name}" failed: ${errorMessage}`);
-      return {
-        data: errorMessage,
-        error: errorMessage,
-      };
-    }
-  }
-
-  private async createResponseDocument(
-    document: DocumentClass,
-    args: DelegateToolCallsArgs,
-    toolResults: DelegateToolResultEntry[],
-  ): Promise<void> {
-    await this.repository.save(
-      document,
-      {
-        role: 'assistant',
-        content: args.message.content,
-        toolResults,
-      },
-      { id: args.message.id, validate: 'skip' },
-    );
-  }
-}

package/src/tools/index.ts

@@ -1,5 +0,0 @@
-export * from './claude-generate-text.tool';
-export * from './claude-generate-object.tool';
-export * from './claude-generate-document.tool';
-export * from './delegate-tool-calls.tool';
-export * from './update-tool-result.tool';