@loopstack/advanced-workflows-examples 0.1.1

package/src/workflows/agent-error-handling/agent-error-handling-failing-sub.workflow.ts

@@ -0,0 +1,13 @@
+import { BaseWorkflow, Transition, Workflow } from '@loopstack/common';
+
+/**
+ * A minimal sub-workflow that always fails on its initial transition.
+ * Used to verify that failed sub-workflow callbacks propagate errors to the parent.
+ */
+@Workflow({ title: 'Agent Error Handling - Failing Sub-Workflow' })
+export class AgentErrorHandlingFailingSubWorkflow extends BaseWorkflow {
+  @Transition({ to: 'done' })
+  start(_state: Record<string, unknown>) {
+    return Promise.reject(new Error('Simulated sub-workflow failure.'));
+  }
+}

package/src/workflows/agent-error-handling/agent-error-handling.ui.yaml

@@ -0,0 +1,6 @@
+widget: button
+showWhen:
+  - awaiting_tools
+options:
+  transition: cancelPendingTools
+  label: Cancel pending tools

package/src/workflows/agent-error-handling/agent-error-handling.workflow.ts

@@ -0,0 +1,130 @@
+import { Inject } from '@nestjs/common';
+import { join } from 'node:path';
+import { BaseWorkflow, Guard, MessageDocument, Transition, WORKFLOW_ORCHESTRATOR, Workflow } from '@loopstack/common';
+import type { RunContext, TransitionInput, WorkflowOrchestrator } from '@loopstack/common';
+import type { LlmDelegateResult, LlmGenerateTextResult } from '@loopstack/llm-provider-module';
+import {
+  LlmDelegateToolCallsTool,
+  LlmGenerateTextTool,
+  LlmMessageDocument,
+  LlmUpdateToolResultTool,
+} from '@loopstack/llm-provider-module';
+import { FailingSubWorkflowTool } from './tools/failing-sub-workflow.tool';
+import { RuntimeErrorTool } from './tools/runtime-error.tool';
+import { StrictSchemaTool } from './tools/strict-schema.tool';
+
+interface AgentErrorHandlingState {
+  llmResult?: LlmGenerateTextResult;
+  delegateResult?: LlmDelegateResult;
+  turnCount: number;
+}
+
+/**
+ * Demonstrates how tool errors (validation, runtime, and failed sub-workflows)
+ * are handled by DelegateToolCalls and fed back to the LLM for self-correction.
+ *
+ * The LLM is instructed to deliberately trigger errors first, then correct them.
+ * This verifies that all error types produce identical is_error tool results
+ * and that the LLM agent loop handles them correctly.
+ */
+@Workflow({
+  title: 'Advanced Workflows - Agent Error Handling Example',
+  description:
+    'Exercises every tool-error path in an agent loop — schema validation failures, runtime exceptions, failed sub-workflows — and verifies the LLM receives identical is_error tool_results and can self-correct.',
+  widget: './agent-error-handling.ui.yaml',
+})
+export class AgentErrorHandlingWorkflow extends BaseWorkflow {
+  constructor(
+    private readonly llmGenerateText: LlmGenerateTextTool,
+    private readonly llmDelegateToolCalls: LlmDelegateToolCallsTool,
+    private readonly llmUpdateToolResult: LlmUpdateToolResultTool,
+    private readonly strictSchema: StrictSchemaTool,
+    private readonly runtimeError: RuntimeErrorTool,
+    private readonly failingSubWorkflow: FailingSubWorkflowTool,
+    @Inject(WORKFLOW_ORCHESTRATOR) private readonly orchestrator: WorkflowOrchestrator,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'ready' })
+  async setup(_state: AgentErrorHandlingState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text:
+        '# Agent Error Handling Example\n\n' +
+        'This workflow tests how tool errors are handled and fed back to the LLM.\n\n' +
+        'The LLM will deliberately trigger errors, then self-correct.',
+    });
+
+    await this.documentStore.save(LlmMessageDocument, {
+      role: 'user',
+      text:
+        'Follow the instructions in your system prompt exactly. ' +
+        'Start with step 1: call strictSchema with no arguments.',
+    });
+    this.assignState({ turnCount: 0 });
+  }
+
+  @Transition({ from: 'ready', to: 'prompt_executed' })
+  async llmTurn(state: AgentErrorHandlingState) {
+    const result = await this.llmGenerateText.call(
+      {},
+      {
+        config: {
+          provider: 'claude',
+          model: 'claude-sonnet-4-6',
+          system: this.render(join(__dirname, 'templates', 'system.md')),
+          tools: ['strict_schema', 'runtime_error', 'failing_sub_workflow'],
+        },
+      },
+    );
+    this.assignState({
+      turnCount: state.turnCount + 1,
+      llmResult: result.data,
+    });
+  }
+
+  @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 })
+  @Guard('hasToolCalls')
+  async executeToolCalls(state: AgentErrorHandlingState) {
+    const result = await this.llmDelegateToolCalls.call({
+      message: state.llmResult!.message,
+      callback: { transition: 'toolResultReceived' },
+    });
+    this.assignState({ delegateResult: result.data });
+  }
+
+  @Transition({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true })
+  async toolResultReceived(state: AgentErrorHandlingState, input: TransitionInput) {
+    const result = await this.llmUpdateToolResult.call({
+      delegateResult: state.delegateResult!,
+      completedTool: input,
+    });
+    this.assignState({ delegateResult: result.data });
+  }
+
+  @Transition({ from: 'awaiting_tools', to: 'ready' })
+  @Guard('allToolsComplete')
+  toolsComplete(_state: AgentErrorHandlingState) {}
+
+  @Transition({ from: 'awaiting_tools', to: 'ready', wait: true })
+  async cancelPendingTools(state: AgentErrorHandlingState, ctx: RunContext) {
+    await this.orchestrator.cancelChildren(ctx.workflowId);
+  }
+
+  @Transition({ from: 'prompt_executed', to: 'end' })
+  @Guard('isEndTurn')
+  respond(_state: AgentErrorHandlingState) {}
+
+  private hasToolCalls(state: AgentErrorHandlingState): boolean {
+    return state.llmResult?.message.stopReason === 'tool_use';
+  }
+
+  private allToolsComplete(state: AgentErrorHandlingState): boolean {
+    return !!state.delegateResult?.allCompleted;
+  }
+
+  private isEndTurn(state: AgentErrorHandlingState): boolean {
+    return state.llmResult?.message.stopReason === 'end_turn';
+  }
+}

package/src/workflows/agent-error-handling/templates/system.md

@@ -0,0 +1,12 @@
+You are a test assistant that follows instructions precisely. You are fully autonomous — do NOT ask the user for input or confirmation. Just proceed through each step on your own.
+
+Complete these steps IN ORDER. Do exactly one step per turn:
+
+1. Call the `strictSchema` tool with NO arguments (empty object {}). This will fail — that is expected.
+2. After seeing the validation error, call `strictSchema` correctly with { "name": "World" }.
+3. Call the `runtimeError` tool with { "shouldFail": true }. This will fail — that is expected.
+4. After seeing the runtime error, call `runtimeError` with { "shouldFail": false }.
+5. Call the `failingSubWorkflow` tool with {}. This launches a sub-workflow that will fail — that is expected.
+6. After seeing the sub-workflow error, respond with a brief summary of what happened (do NOT call any tools).
+
+IMPORTANT: Only perform ONE step per turn. Do NOT skip steps. Do NOT wait for user input between steps.

package/src/workflows/agent-error-handling/tools/failing-sub-workflow.tool.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolCallOptions, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { AgentErrorHandlingFailingSubWorkflow } from '../agent-error-handling-failing-sub.workflow';
+
+export type FailingSubWorkflowToolResult = { workflowId: string };
+
+@Tool({
+  name: 'failing_sub_workflow',
+  description:
+    'Launch an async sub-workflow that always fails. ' +
+    'Used to test that failed sub-workflow errors propagate back to the parent.',
+  schema: z.object({}),
+})
+export class FailingSubWorkflowTool extends BaseTool<object, object, FailingSubWorkflowToolResult> {
+  constructor(private readonly failingWorkflow: AgentErrorHandlingFailingSubWorkflow) {
+    super();
+  }
+
+  protected async handle(
+    _args: object,
+    _ctx: RunContext,
+    options?: ToolCallOptions,
+  ): Promise<ToolEnvelope<FailingSubWorkflowToolResult>> {
+    const result = await this.failingWorkflow.run({}, { callback: options?.callback });
+
+    return {
+      data: { workflowId: result.workflowId },
+      pending: { workflowId: result.workflowId },
+    };
+  }
+}

package/src/workflows/agent-error-handling/tools/runtime-error.tool.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+
+export type RuntimeErrorToolResult = string;
+
+@Tool({
+  name: 'runtime_error',
+  description:
+    'Perform an action that may fail at runtime. ' +
+    'Pass shouldFail: true to simulate a runtime error, or false to succeed.',
+  schema: z.object({
+    shouldFail: z.boolean().describe('Whether the tool should simulate a runtime failure.'),
+  }),
+})
+export class RuntimeErrorTool extends BaseTool<{ shouldFail: boolean }, object, RuntimeErrorToolResult> {
+  protected async handle(
+    args: { shouldFail: boolean },
+    _ctx: RunContext,
+  ): Promise<ToolEnvelope<RuntimeErrorToolResult>> {
+    if (args.shouldFail) {
+      throw new Error('Simulated runtime error: external service unavailable.');
+    }
+
+    return Promise.resolve({
+      data: 'Action completed successfully.',
+    });
+  }
+}

package/src/workflows/agent-error-handling/tools/strict-schema.tool.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+
+export type StrictSchemaToolResult = string;
+
+@Tool({
+  name: 'strict_schema',
+  description: 'Greet a person by name. Requires a name argument. ' + 'Returns a greeting message.',
+  schema: z
+    .object({
+      name: z.string().describe('The name of the person to greet.'),
+    })
+    .strict(),
+})
+export class StrictSchemaTool extends BaseTool<{ name: string }, object, StrictSchemaToolResult> {
+  protected async handle(args: { name: string }): Promise<ToolEnvelope<StrictSchemaToolResult>> {
+    return Promise.resolve({
+      data: `Hello, ${args.name}! Nice to meet you.`,
+    });
+  }
+}

package/src/workflows/batch-processing/batch-processing-example.workflow.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { BaseWorkflow, Guard, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+
+interface BatchProcessingState {
+  items: string[];
+  processed: Array<{ item: string; result: string }>;
+  batchIndex: number;
+}
+
+const BatchProcessingArgsSchema = z.object({
+  totalItems: z.number().int().min(1).default(25),
+  batchSize: z.number().int().min(1).default(5),
+});
+
+type BatchProcessingArgs = z.infer<typeof BatchProcessingArgsSchema>;
+
+@Workflow({
+  title: 'Advanced - Batch Processing Example',
+  description:
+    'Processes a list of items in fixed-size batches with a state-machine loop. Different from FanOutWorkflow — batches run sequentially, items within a batch can run concurrently. Useful for rate-limited APIs, memory-bounded processing, or quota-constrained operations.',
+  schema: BatchProcessingArgsSchema,
+})
+export class BatchProcessingExampleWorkflow extends BaseWorkflow<BatchProcessingArgs> {
+  @Transition({ to: 'batch_ready' })
+  setup(_state: BatchProcessingState, ctx: RunContext<BatchProcessingArgs>) {
+    const items = Array.from({ length: ctx.args.totalItems }, (_, i) => `item-${i + 1}`);
+    this.assignState({ items, processed: [], batchIndex: 0 });
+  }
+
+  @Transition({ from: 'batch_ready', to: 'batch_done' })
+  async processBatch(state: BatchProcessingState, ctx: RunContext<BatchProcessingArgs>) {
+    const start = state.batchIndex * ctx.args.batchSize;
+    const batch = state.items.slice(start, start + ctx.args.batchSize);
+
+    const results = await Promise.all(
+      batch.map(async (item) => ({
+        item,
+        result: await this.processItem(item),
+      })),
+    );
+
+    this.assignState({ processed: [...state.processed, ...results] });
+  }
+
+  @Transition({ from: 'batch_done', to: 'batch_ready' })
+  @Guard('hasMoreItems')
+  nextBatch(state: BatchProcessingState) {
+    this.assignState({ batchIndex: state.batchIndex + 1 });
+  }
+
+  hasMoreItems(state: BatchProcessingState): boolean {
+    return state.processed.length < state.items.length;
+  }
+
+  @Transition({ from: 'batch_done', to: 'end', priority: 10 })
+  @Guard('allItemsProcessed')
+  async finish(state: BatchProcessingState, ctx: RunContext<BatchProcessingArgs>) {
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        `# Batch Processing Complete`,
+        ``,
+        `Processed ${state.processed.length} items in batches of ${ctx.args.batchSize}.`,
+        ``,
+        ...state.processed.slice(0, 10).map((r) => `- ${r.item} → ${r.result}`),
+        state.processed.length > 10 ? `\n_(${state.processed.length - 10} more omitted)_` : '',
+      ].join('\n'),
+    });
+  }
+
+  allItemsProcessed(state: BatchProcessingState): boolean {
+    return state.processed.length >= state.items.length;
+  }
+
+  private async processItem(item: string): Promise<string> {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    return `processed:${item}`;
+  }
+}

package/src/workflows/custom-tool/custom-tool-example.ui.yaml

@@ -0,0 +1,6 @@
+widget: button
+enabledWhen:
+  - waiting_for_user
+options:
+  transition: userContinue
+  label: Continue

package/src/workflows/custom-tool/custom-tool-example.workflow.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { CounterTool, MathSumTool } from './tools';
+
+interface CustomToolExampleState {
+  total?: number;
+}
+
+const CustomToolExampleArgsSchema = z
+  .object({
+    a: z.number().default(1),
+    b: z.number().default(2),
+  })
+  .strict();
+
+type CustomToolExampleArgs = z.infer<typeof CustomToolExampleArgsSchema>;
+
+@Workflow({
+  title: 'Advanced - Custom Tool Example',
+  description:
+    'Authoring custom tools — stateless and stateful, with @Tool() decorator, Zod schemas, and NestJS injection.',
+  widget: './custom-tool-example.ui.yaml',
+  schema: CustomToolExampleArgsSchema,
+})
+export class CustomToolExampleWorkflow extends BaseWorkflow<CustomToolExampleArgs> {
+  constructor(
+    private readonly counterTool: CounterTool,
+    private readonly mathTool: MathSumTool,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_user' })
+  async calculate(state: CustomToolExampleState, ctx: RunContext<CustomToolExampleArgs>) {
+    // Use a custom tool
+    const calcResult = await this.mathTool.call({ a: ctx.args.a, b: ctx.args.b });
+    const total = calcResult.data as number;
+
+    // Display the result
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Tool calculation result:\n${ctx.args.a} + ${ctx.args.b} = ${total}`,
+    });
+
+    // Alternatively, use a custom workflow method
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Alternatively, using workflow method:\n${ctx.args.a} + ${ctx.args.b} = ${this.sum(ctx.args.a, ctx.args.b)}`,
+    });
+
+    // Count before pause — should be 1, 2, 3
+    const c1 = await this.counterTool.call();
+    const c2 = await this.counterTool.call();
+    const c3 = await this.counterTool.call();
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Counter before pause: ${c1.data}, ${c2.data}, ${c3.data}\n\nPress Next to continue...`,
+    });
+    this.assignState({ total });
+  }
+
+  @Transition({ from: 'waiting_for_user', to: 'resumed', wait: true })
+  userContinue(_state: CustomToolExampleState) {
+    // User pressed Next — counter state should persist from checkpoint
+  }
+
+  @Transition({ from: 'resumed', to: 'end' })
+  async continueCount(state: CustomToolExampleState) {
+    // Count after resume — should continue: 4, 5, 6
+    const c4 = await this.counterTool.call();
+    const c5 = await this.counterTool.call();
+    const c6 = await this.counterTool.call();
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Counter after resume: ${c4.data}, ${c5.data}, ${c6.data}\n\nIf state persisted, this should be 4, 5, 6.`,
+    });
+
+    this.setResult({ total: state.total } as unknown as Record<string, unknown>);
+  }
+
+  private sum(a: number, b: number) {
+    return a + b;
+  }
+}

package/src/workflows/custom-tool/index.ts

@@ -0,0 +1 @@
+export * from './custom-tool-example.workflow';

package/src/workflows/custom-tool/services/math.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class MathService {
+  public sum(a: number, b: number) {
+    return a + b;
+  }
+}

package/src/workflows/custom-tool/tools/counter.tool.ts

@@ -0,0 +1,16 @@
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+
+export type CounterToolResult = number;
+
+@Tool({
+  name: 'counter',
+  description: 'Counter tool.',
+})
+export class CounterTool extends BaseTool<object, object, CounterToolResult> {
+  count: number = 0;
+
+  protected async handle(): Promise<ToolEnvelope<CounterToolResult>> {
+    this.count++;
+    return Promise.resolve({ data: this.count });
+  }
+}

package/src/workflows/custom-tool/tools/index.ts

@@ -0,0 +1,2 @@
+export * from './counter.tool';
+export * from './math-sum.tool';

package/src/workflows/custom-tool/tools/math-sum.tool.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+import { MathService } from '../services/math.service';
+
+const MathSumSchema = z
+  .object({
+    a: z.number(),
+    b: z.number(),
+  })
+  .strict();
+
+type MathSumArgs = z.infer<typeof MathSumSchema>;
+
+export type MathSumToolResult = number;
+
+@Tool({
+  name: 'math_sum',
+  description: 'Math tool calculating the sum of two arguments by using an injected service.',
+  schema: MathSumSchema,
+})
+export class MathSumTool extends BaseTool<MathSumArgs, object, MathSumToolResult> {
+  constructor(private readonly mathService: MathService) {
+    super();
+  }
+
+  protected async handle(args: MathSumArgs): Promise<ToolEnvelope<MathSumToolResult>> {
+    const sum = this.mathService.sum(args.a, args.b);
+    return Promise.resolve({ data: sum });
+  }
+}

package/src/workflows/dynamic-routing/dynamic-routing-example.workflow.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { BaseWorkflow, Guard, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+
+interface DynamicRoutingState {
+  value: number;
+}
+
+const DynamicRoutingArgsSchema = z
+  .object({
+    value: z.number().default(150),
+  })
+  .strict();
+
+type DynamicRoutingArgs = z.infer<typeof DynamicRoutingArgsSchema>;
+
+@Workflow({
+  title: 'Advanced - Dynamic Routing Example',
+  description:
+    'Conditional routing using @Guard decorators and transition priorities — branching on runtime values without explicit state machines.',
+  schema: DynamicRoutingArgsSchema,
+})
+export class DynamicRoutingExampleWorkflow extends BaseWorkflow<DynamicRoutingArgs> {
+  // --- Initial transition ---
+
+  @Transition({ to: 'prepared' })
+  async createMockData(state: DynamicRoutingState, ctx: RunContext<DynamicRoutingArgs>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Analysing value = ${ctx.args.value}`,
+    });
+    this.assignState({ value: ctx.args.value });
+  }
+
+  // --- First routing fork (from 'prepared') ---
+
+  @Transition({ from: 'prepared', to: 'placeA', priority: 10 })
+  @Guard('isAbove100')
+  routeToPlaceA(_state: DynamicRoutingState) {}
+
+  isAbove100(state: DynamicRoutingState): boolean {
+    return state.value > 100;
+  }
+
+  @Transition({ from: 'prepared', to: 'placeB' })
+  routeToPlaceB(_state: DynamicRoutingState) {} // no priority -> evaluated last, acts as fallback
+
+  // --- Second routing fork (from 'placeA') ---
+
+  @Transition({ from: 'placeA', to: 'placeC', priority: 10 })
+  @Guard('isAbove200')
+  routeToPlaceC(_state: DynamicRoutingState) {}
+
+  isAbove200(state: DynamicRoutingState): boolean {
+    return state.value > 200;
+  }
+
+  @Transition({ from: 'placeA', to: 'placeD' })
+  routeToPlaceD(_state: DynamicRoutingState) {} // no priority -> evaluated last, acts as fallback
+
+  // --- Terminal transitions ---
+
+  @Transition({ from: 'placeB', to: 'end' })
+  async showMessagePlaceB(_state: DynamicRoutingState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'Value is less or equal 100',
+    });
+  }
+
+  @Transition({ from: 'placeC', to: 'end' })
+  async showMessagePlaceC(_state: DynamicRoutingState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'Value is greater than 200',
+    });
+  }
+
+  @Transition({ from: 'placeD', to: 'end' })
+  async showMessagePlaceD(_state: DynamicRoutingState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'Value is less or equal 200, but greater than 100',
+    });
+  }
+}

package/src/workflows/error-retry/error-retry-example.ui.yaml

@@ -0,0 +1,25 @@
+widgets:
+  - widget: button
+    showWhen:
+      - error_custom
+    options:
+      transition: handleCustomError
+      label: Recover
+  - widget: button
+    showWhen:
+      - error_hybrid
+    options:
+      transition: handleHybridError
+      label: Recover
+  - widget: button
+    showWhen:
+      - error_retry_target
+    options:
+      transition: handleRetryTargetError
+      label: Recover
+  - widget: button
+    showWhen:
+      - sub_failed
+    options:
+      transition: handleSubFailed
+      label: Recover