@loopstack/claude-module 0.21.1 → 0.22.0

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

@@ -2,16 +2,12 @@ import Anthropic from '@anthropic-ai/sdk';
 import { Inject } from '@nestjs/common';
 import { toJSONSchema, z } from 'zod';
 import {
-  DocumentInterface,
-  Input,
-  RunContext,
+  BaseTool,
+  DocumentClass,
   Tool,
-  ToolInterface,
   ToolResult,
-  WorkflowInterface,
-  WorkflowMetadataInterface,
-  getBlockArgsSchema,
-  getBlockDocument,
+  getBlockTypeFromMetadata,
+  getDocumentSchema,
 } from '@loopstack/common';
 import { ClaudeGenerateToolBaseSchema } from '../schemas/claude-generate-tool-base.schema';
 import { ClaudeClientService } from '../services';
@@ -21,7 +17,9 @@ import { applyCacheBreakpoints } from '../utils/cache.utils';
 export const ClaudeGenerateObjectSchema = ClaudeGenerateToolBaseSchema.extend({
   response: z.object({
     id: z.string().optional(),
-    document: z.string(),
+    document: z.custom<DocumentClass>(
+      (val) => typeof val === 'function' && getBlockTypeFromMetadata(val as object) === 'document',
+    ),
   }),
 }).strict();
 
@@ -30,27 +28,18 @@ export type ClaudeGenerateObjectArgsType = z.infer<typeof ClaudeGenerateObjectSc
 const STRUCTURED_OUTPUT_TOOL_NAME = 'structured_output';
 
 @Tool({
-  config: {
+  uiConfig: {
     description: 'Generates a structured object using the Anthropic Claude API',
   },
+  schema: ClaudeGenerateObjectSchema,
 })
-export class ClaudeGenerateObject implements ToolInterface<ClaudeGenerateObjectArgsType> {
+export class ClaudeGenerateObject extends BaseTool {
   @Inject()
   private readonly claudeClientService: ClaudeClientService;
   @Inject()
   private readonly claudeMessagesHelperService: ClaudeMessagesHelperService;
 
-  @Input({
-    schema: ClaudeGenerateObjectSchema,
-  })
-  args: ClaudeGenerateObjectArgsType;
-
-  async execute(
-    args: ClaudeGenerateObjectArgsType,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    metadata: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
+  async call(args: ClaudeGenerateObjectArgsType): Promise<ToolResult> {
     const client = this.claudeClientService.getClient(args.claude);
     const model = this.claudeClientService.getModel(args.claude);
 
@@ -59,19 +48,14 @@ export class ClaudeGenerateObject implements ToolInterface<ClaudeGenerateObjectA
     if (args.prompt) {
       messages.push({ role: 'user', content: args.prompt });
     } else {
-      const resolved = this.claudeMessagesHelperService.getMessages(metadata.documents, {
+      const resolved = this.claudeMessagesHelperService.getMessages(this.ctx.runtime.documents, {
         messages: args.messages as Anthropic.MessageParam[],
         messagesSearchTag: args.messagesSearchTag,
       });
       messages.push(...resolved);
     }
 
-    const document = getBlockDocument<DocumentInterface>(parent, args.response.document);
-    if (!document) {
-      throw new Error(`Document with name "${args.response.document}" not found in tool execution context.`);
-    }
-
-    const responseSchema = getBlockArgsSchema(document);
+    const responseSchema = getDocumentSchema(args.response.document);
     if (!responseSchema) {
       throw new Error('Claude object generation source document must have a schema.');
     }

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

@@ -1,38 +1,27 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { Inject } from '@nestjs/common';
 import { z } from 'zod';
-import {
-  Input,
-  RunContext,
-  Tool,
-  ToolCallEntry,
-  ToolCallsMap,
-  ToolInterface,
-  ToolResult,
-  ToolSideEffects,
-  WorkflowInterface,
-  WorkflowMetadataInterface,
-  getBlockTool,
-} from '@loopstack/common';
+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(),
-  document: z.string().optional(),
 }).strict();
 
 type ClaudeGenerateTextArgsType = z.infer<typeof ClaudeGenerateTextSchema>;
 
 @Tool({
-  config: {
+  uiConfig: {
     description: 'Generates text using the Anthropic Claude API',
   },
+  schema: ClaudeGenerateTextSchema,
 })
-export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsType> {
+export class ClaudeGenerateText extends BaseTool {
   @Inject()
   private readonly claudeClientService: ClaudeClientService;
   @Inject()
@@ -40,17 +29,7 @@ export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsT
   @Inject()
   private readonly claudeToolsHelperService: ClaudeToolsHelperService;
 
-  @Input({
-    schema: ClaudeGenerateTextSchema,
-  })
-  args: ClaudeGenerateTextArgsType;
-
-  async execute(
-    args: ClaudeGenerateTextArgsType,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    runtime: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
+  async call(args: ClaudeGenerateTextArgsType): Promise<ToolResult<ClaudeGenerateTextResult>> {
     const client = this.claudeClientService.getClient(args.claude);
     const model = this.claudeClientService.getModel(args.claude);
 
@@ -59,14 +38,14 @@ export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsT
     if (args.prompt) {
       messages.push({ role: 'user', content: args.prompt });
     } else {
-      const resolved = this.claudeMessagesHelperService.getMessages(runtime.documents, {
+      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, parent) : undefined;
+    const tools = args.tools ? this.claudeToolsHelperService.getTools(args.tools, this.ctx.parent) : undefined;
 
     const response = await this.handleGenerateText(client, {
       model,
@@ -79,21 +58,11 @@ export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsT
 
     const toolCalls = this.extractToolCalls(response);
 
-    let effects: ToolSideEffects[] = [];
-
-    if (args.document) {
-      const docResult = await this.createResponseMessage(args.document, response, ctx, parent, runtime);
-      if (docResult.effects) {
-        effects = [...docResult.effects];
-      }
-    }
-
     return {
       data: {
         ...response,
         ...(toolCalls ? { toolCalls } : {}),
       },
-      ...(effects.length > 0 ? { effects } : {}),
       metadata: {
         usage: {
           inputTokens: response.usage.input_tokens,
@@ -105,32 +74,6 @@ export class ClaudeGenerateText implements ToolInterface<ClaudeGenerateTextArgsT
     };
   }
 
-  private async createResponseMessage(
-    document: string,
-    response: Anthropic.Message,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    runtime: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
-    const createDocumentTool = getBlockTool<ToolInterface>(parent, 'createDocument');
-    if (!createDocumentTool) {
-      throw new Error('createDocument tool not found in parent context.');
-    }
-
-    return createDocumentTool.execute(
-      {
-        id: response.id,
-        document,
-        update: {
-          content: response,
-        },
-      },
-      ctx,
-      parent,
-      runtime,
-    );
-  }
-
   private extractToolCalls(response: Anthropic.Message): ToolCallsMap | null {
     if (response.stop_reason !== 'tool_use') {
       return null;

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

@@ -2,24 +2,24 @@ import Anthropic from '@anthropic-ai/sdk';
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
 import {
-  InjectTool,
-  Input,
-  RunContext,
+  BaseTool,
+  DocumentClass,
   Tool,
-  ToolInterface,
+  ToolCallOptions,
   ToolResult,
-  ToolSideEffects,
-  WorkflowInterface,
-  WorkflowMetadataInterface,
+  getBlockTool,
+  getBlockTypeFromMetadata,
 } from '@loopstack/common';
-import { CreateDocument, EventSubscriberService, StateMachineToolCallProcessorService } from '@loopstack/core';
+import type { DelegateToolCallsResult, DelegateToolResultEntry } from '../types';
 
 const DelegateToolCallsSchema = z.object({
   message: z.object({
     id: z.string().optional(),
     content: z.array(z.any()),
   }),
-  document: z.string().optional(),
+  document: z
+    .custom<DocumentClass>((val) => typeof val === 'function' && getBlockTypeFromMetadata(val as object) === 'document')
+    .optional(),
   skipResponseMessage: z.boolean().optional(),
   callback: z
     .object({
@@ -30,88 +30,53 @@ const DelegateToolCallsSchema = z.object({
 
 type DelegateToolCallsArgs = z.infer<typeof DelegateToolCallsSchema>;
 
-interface ToolResultEntry {
-  type: 'tool_result';
-  tool_use_id: string;
-  content?: string;
-  is_error?: boolean;
-}
-
 @Injectable()
 @Tool({
-  config: {
+  uiConfig: {
     description: 'Delegate tool calls from an LLM response. Handles both sync tools and async task tools.',
   },
+  schema: DelegateToolCallsSchema,
 })
-export class DelegateToolCalls implements ToolInterface<DelegateToolCallsArgs> {
+export class DelegateToolCalls extends BaseTool {
   private readonly logger = new Logger(DelegateToolCalls.name);
 
-  @InjectTool() private createDocument: CreateDocument;
-
-  constructor(
-    private readonly toolCallProcessor: StateMachineToolCallProcessorService,
-    private readonly eventSubscriberService: EventSubscriberService,
-  ) {}
-
-  @Input({
-    schema: DelegateToolCallsSchema,
-  })
-  args: DelegateToolCallsArgs;
-
-  async execute(
-    args: DelegateToolCallsArgs,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    metadata: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
+  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, pendingCount: 0 },
+        data: {
+          allCompleted: true,
+          toolResults: [],
+          message: args.message as DelegateToolCallsResult['message'],
+          pendingCount: 0,
+        },
       };
     }
 
-    // 1. Execute ALL tools in parallel
-    const results = await Promise.all(toolUseBlocks.map((block) => this.executeTool(block, ctx, parent, metadata)));
+    // 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. Register subscribers for async results + build toolResults array
+    // 2. Build toolResults array — async tools signal via result.pending
     let pendingCount = 0;
-    const toolResults: ToolResultEntry[] = [];
-    const toolEffects: ToolSideEffects[] = [];
+    const toolResults: DelegateToolResultEntry[] = [];
 
     for (let i = 0; i < toolUseBlocks.length; i++) {
       const block = toolUseBlocks[i];
       const result = results[i];
 
-      // Collect effects from tool execution (e.g. link documents)
-      if (result.effects) {
-        toolEffects.push(...result.effects);
-      }
-
-      const resultData = result.data as Record<string, unknown> | undefined;
-      if (resultData?.mode === 'async') {
-        // Validate callback is provided
-        if (!args.callback?.transition) {
-          throw new Error(
-            `Tool "${block.name}" returned an async result but no callback.transition was provided. ` +
-              `Add a callback configuration to the delegateToolCalls args.`,
-          );
-        }
-
-        // Register event subscriber
-        await this.eventSubscriberService.registerSubscriber(
-          ctx.pipelineId,
-          ctx.workflowId!,
-          args.callback.transition,
-          resultData.correlationId as string,
-          resultData.eventName as string,
-          ctx.userId,
-          ctx.workspaceId,
-          { toolUseId: block.id, toolName: block.name },
-        );
-
+      if (result.pending) {
         pendingCount++;
       } else {
         toolResults.push({
@@ -123,43 +88,29 @@ export class DelegateToolCalls implements ToolInterface<DelegateToolCallsArgs> {
       }
     }
 
-    // 3. Create response document first (tool call message), then append
-    //    tool execution effects (e.g. link documents) so they appear after.
-    const effects: ToolSideEffects[] = [];
+    // 3. Create response document (tool call message)
     if (args.document && !args.skipResponseMessage) {
-      const docResult = await this.createResponseDocument(args, toolResults, ctx, parent, metadata);
-      if (docResult.effects) {
-        effects.push(...docResult.effects);
-      }
+      await this.createResponseDocument(args.document, args, toolResults);
     }
-    effects.push(...toolEffects);
 
     return {
       data: {
         allCompleted: pendingCount === 0,
         toolResults,
-        message: args.message,
+        message: args.message as DelegateToolCallsResult['message'],
         pendingCount,
       },
-      effects,
     };
   }
 
-  private async executeTool(
-    block: Anthropic.ToolUseBlock,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    metadata: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
-    const tool = this.toolCallProcessor.getTool(parent, block.name);
-    const parsedArgs = this.toolCallProcessor.parseArgs(
-      tool,
-      block.input as Record<string, unknown> | undefined,
-      metadata.transition!,
-    );
-
+  private async executeTool(block: Anthropic.ToolUseBlock, options?: ToolCallOptions): Promise<ToolResult> {
     try {
-      return await this.toolCallProcessor.executeToolCall(tool, parsedArgs, ctx, parent, metadata);
+      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}`);
@@ -171,28 +122,18 @@ export class DelegateToolCalls implements ToolInterface<DelegateToolCallsArgs> {
   }
 
   private async createResponseDocument(
+    document: DocumentClass,
     args: DelegateToolCallsArgs,
-    toolResults: ToolResultEntry[],
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    metadata: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
-    return this.createDocument.execute(
+    toolResults: DelegateToolResultEntry[],
+  ): Promise<void> {
+    await this.repository.save(
+      document,
       {
-        id: args.message.id,
-        document: args.document!,
-        validate: 'skip' as const,
-        update: {
-          content: {
-            role: 'assistant',
-            content: args.message.content,
-            toolResults,
-          },
-        },
+        role: 'assistant',
+        content: args.message.content,
+        toolResults,
       },
-      ctx,
-      parent,
-      metadata,
+      { id: args.message.id, validate: 'skip' },
     );
   }
 }

package/src/tools/update-tool-result.tool.ts

@@ -1,17 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
-import {
-  InjectTool,
-  Input,
-  RunContext,
-  Tool,
-  ToolInterface,
-  ToolResult,
-  ToolSideEffects,
-  WorkflowInterface,
-  WorkflowMetadataInterface,
-} from '@loopstack/common';
-import { CreateDocument, StateMachineToolCallProcessorService } from '@loopstack/core';
+import { BaseTool, DocumentClass, Tool, ToolResult, getBlockTool, getBlockTypeFromMetadata } from '@loopstack/common';
 
 const UpdateToolResultSchema = z.object({
   delegateResult: z.object({
@@ -21,35 +10,24 @@ const UpdateToolResultSchema = z.object({
     pendingCount: z.number(),
   }),
   completedTool: z.any(),
-  document: z.string().optional(),
+  document: z
+    .custom<DocumentClass>((val) => typeof val === 'function' && getBlockTypeFromMetadata(val as object) === 'document')
+    .optional(),
 });
 
 type UpdateToolResultArgs = z.infer<typeof UpdateToolResultSchema>;
 
 @Injectable()
 @Tool({
-  config: {
+  uiConfig: {
     description: 'Handle async tool completion callback. Updates the response document and tracks completion state.',
   },
+  schema: UpdateToolResultSchema,
 })
-export class UpdateToolResult implements ToolInterface<UpdateToolResultArgs> {
+export class UpdateToolResult extends BaseTool {
   private readonly logger = new Logger(UpdateToolResult.name);
 
-  @InjectTool() private createDocument: CreateDocument;
-
-  constructor(private readonly toolCallProcessor: StateMachineToolCallProcessorService) {}
-
-  @Input({
-    schema: UpdateToolResultSchema,
-  })
-  args: UpdateToolResultArgs;
-
-  async execute(
-    args: UpdateToolResultArgs,
-    ctx: RunContext,
-    parent: WorkflowInterface,
-    metadata: WorkflowMetadataInterface,
-  ): Promise<ToolResult> {
+  async call(args: UpdateToolResultArgs): Promise<ToolResult> {
     const { delegateResult } = args;
     const completedToolRecord = args.completedTool as Record<string, unknown>;
 
@@ -66,15 +44,14 @@ export class UpdateToolResult implements ToolInterface<UpdateToolResultArgs> {
 
     const { toolUseId, toolName } = subscriberMetadata;
 
-    // 2. Resolve tool and call complete() if it exists
-    const tool = this.toolCallProcessor.getTool(parent, toolName);
+    // 2. Resolve tool and call complete()
+    const tool = getBlockTool<BaseTool>(this.ctx.parent, toolName);
+    if (!tool) {
+      throw new Error(`Tool with name ${toolName} not found.`);
+    }
     let toolResult: ToolResult;
     try {
-      if (tool.complete) {
-        toolResult = await tool.complete(completedToolRecord, ctx, parent, metadata);
-      } else {
-        toolResult = { data: completedToolRecord.result ?? completedToolRecord };
-      }
+      toolResult = await tool.complete(completedToolRecord);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.logger.error(`Tool "${toolName}" complete() failed: ${errorMessage}`);
@@ -97,33 +74,17 @@ export class UpdateToolResult implements ToolInterface<UpdateToolResultArgs> {
     const pendingCount = delegateResult.pendingCount - 1;
     const allCompleted = pendingCount === 0;
 
-    // 5. Create updated response document (invalidates previous)
-    const allEffects: ToolSideEffects[] = [];
-    if (toolResult.effects) {
-      allEffects.push(...toolResult.effects);
-    }
-
+    // 5. Update response document (invalidates previous)
     if (args.document) {
-      const docResult = await this.createDocument.execute(
+      await this.repository.save(
+        args.document,
         {
-          id: (delegateResult.message as Record<string, unknown>).id as string,
-          document: args.document,
-          validate: 'skip' as const,
-          update: {
-            content: {
-              role: 'assistant',
-              content: (delegateResult.message as Record<string, unknown>).content,
-              toolResults: updatedResults,
-            },
-          },
+          role: 'assistant',
+          content: (delegateResult.message as Record<string, unknown>).content,
+          toolResults: updatedResults,
         },
-        ctx,
-        parent,
-        metadata,
+        { id: (delegateResult.message as Record<string, unknown>).id as string, validate: 'skip' },
       );
-      if (docResult.effects) {
-        allEffects.push(...docResult.effects);
-      }
     }
 
     return {
@@ -133,7 +94,6 @@ export class UpdateToolResult implements ToolInterface<UpdateToolResultArgs> {
         allCompleted,
         pendingCount,
       },
-      effects: allEffects.length > 0 ? allEffects : undefined,
     };
   }
 }

package/src/types/claude.types.ts

@@ -1,4 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
+import type { ToolCallsMap } from '@loopstack/common';
 
 /**
  * Configuration for creating a Claude client and selecting a model.
@@ -30,5 +31,30 @@ export interface ClaudeToolDefinition {
   input_schema: Anthropic.Tool['input_schema'];
 }
 
+/**
+ * Result data from ClaudeGenerateText tool.
+ * Extends the Anthropic Message with optional tool call metadata.
+ */
+export interface ClaudeGenerateTextResult extends Anthropic.Message {
+  toolCalls?: ToolCallsMap;
+}
+
+/**
+ * Result data from DelegateToolCalls tool.
+ */
+export interface DelegateToolCallsResult {
+  allCompleted: boolean;
+  toolResults: DelegateToolResultEntry[];
+  message: { id?: string; content: Anthropic.ContentBlock[] };
+  pendingCount: number;
+}
+
+export interface DelegateToolResultEntry {
+  type: 'tool_result';
+  tool_use_id: string;
+  content?: string;
+  is_error?: boolean;
+}
+
 // Re-export Anthropic namespace for consumer convenience
 export { default as Anthropic } from '@anthropic-ai/sdk';