@loopstack/advanced-workflows-examples 0.1.1 → 0.1.3

package/src/workflows/error-retry/error-retry-example.workflow.ts

@@ -45,7 +45,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'step1_done' })
-  async setup(_state: ErrorRetryState) {
+  async setup() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: '# Error Retry Example\n\nThis workflow tests seven retry/error modes in sequence.',
@@ -81,7 +81,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 2 --
   @Transition({ from: 'step2_done', to: 'step2_ready' })
-  async step2Instructions(_state: ErrorRetryState) {
+  async step2Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -105,7 +105,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 3 --
   @Transition({ from: 'step3_done', to: 'step3_ready' })
-  async step3Instructions(_state: ErrorRetryState) {
+  async step3Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -117,12 +117,12 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Step 3: Custom error place --
   @Transition({ from: 'step3_ready', to: 'step4_done', errorPlace: 'error_custom' })
-  async customErrorStep(_state: ErrorRetryState) {
+  async customErrorStep() {
     await this.step2Tool.call({ shouldFail: true });
   }
 
   @Transition({ from: 'error_custom', to: 'step4_done', wait: true })
-  async handleCustomError(_state: ErrorRetryState) {
+  async handleCustomError() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Recovered via custom error handler!',
@@ -131,7 +131,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 4 --
   @Transition({ from: 'step4_done', to: 'step4_ready' })
-  async step4Instructions(_state: ErrorRetryState) {
+  async step4Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -156,7 +156,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 5 --
   @Transition({ from: 'step5_done', to: 'step5_ready' })
-  async step5Instructions(_state: ErrorRetryState) {
+  async step5Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -168,12 +168,12 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Step 5: Hybrid --
   @Transition({ from: 'step5_ready', to: 'step6_done', retryAttempts: 1, errorPlace: 'error_hybrid' })
-  async hybridStep(_state: ErrorRetryState) {
+  async hybridStep() {
     await this.step2Tool.call({ shouldFail: true });
   }
 
   @Transition({ from: 'error_hybrid', to: 'step6_done', wait: true })
-  async handleHybridError(_state: ErrorRetryState) {
+  async handleHybridError() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Recovered via hybrid error handler!',
@@ -182,7 +182,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 6 --
   @Transition({ from: 'step6_done', to: 'step6_ready' })
-  async step6Instructions(_state: ErrorRetryState) {
+  async step6Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text:
@@ -228,7 +228,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // Reached only if retryTargetStep keeps failing past its budget.
   @Transition({ from: 'error_retry_target', to: 'step7_done', wait: true })
-  async handleRetryTargetError(_state: ErrorRetryState) {
+  async handleRetryTargetError() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'retryTarget budget exhausted — recovered via error handler.',
@@ -237,7 +237,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Bridge: instructions for step 7 --
   @Transition({ from: 'step7_done', to: 'step7_ready' })
-  async step7Instructions(_state: ErrorRetryState) {
+  async step7Instructions() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: [
@@ -254,7 +254,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // -- Step 7: Sub-workflow + errorPlace --
   @Transition({ from: 'step7_ready', to: 'awaiting_child' })
-  async spawnFailingChild(_state: ErrorRetryState) {
+  async spawnFailingChild() {
     await this.failingChild.run({}, { callback: { transition: 'childCompleted' } });
   }
 
@@ -269,7 +269,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
 
   // Failure recovery transition for the failing child.
   @Transition({ from: 'sub_failed', to: 'done', wait: true })
-  async handleSubFailed(_state: ErrorRetryState) {
+  async handleSubFailed() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Recovered from sub-workflow failure via errorPlace routing.',
@@ -277,7 +277,7 @@ export class ErrorRetryWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'done', to: 'end' })
-  async showResult(_state: ErrorRetryState) {
+  async showResult() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'All seven retry modes completed successfully!',

package/src/workflows/error-retry/failing-child.workflow.ts

@@ -10,7 +10,7 @@ import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/
 })
 export class ErrorRetryFailingChildWorkflow extends BaseWorkflow {
   @Transition({ to: 'end' })
-  async fail(_state: Record<string, unknown>) {
+  async fail() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Failing child: about to throw.',

package/src/workflows/error-retry/tools/slow.tool.ts

@@ -1,10 +1,15 @@
+import { z } from 'zod';
 import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
 
 export type SlowToolResult = string;
 
+export const SlowToolResultSchema = z.string();
+
 @Tool({
   name: 'slow',
   description: 'A tool that takes a configurable amount of time to complete.',
+  resultSchema: SlowToolResultSchema,
+  effects: 'none',
 })
 export class SlowTool extends BaseTool<{ delayMs: number }, object, SlowToolResult> {
   protected async handle(args: { delayMs: number }): Promise<ToolEnvelope<SlowToolResult>> {

package/src/workflows/error-retry/tools/step1.tool.ts

@@ -1,10 +1,15 @@
+import { z } from 'zod';
 import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
 
 export type Step1ToolResult = string;
 
+export const Step1ToolResultSchema = z.string();
+
 @Tool({
   name: 'step1',
   description: 'A tool that always succeeds.',
+  resultSchema: Step1ToolResultSchema,
+  effects: 'none',
 })
 export class Step1Tool extends BaseTool<object, object, Step1ToolResult> {
   protected async handle(): Promise<ToolEnvelope<Step1ToolResult>> {

package/src/workflows/error-retry/tools/step2.tool.ts

@@ -1,10 +1,15 @@
+import { z } from 'zod';
 import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
 
 export type Step2ToolResult = string;
 
+export const Step2ToolResultSchema = z.string();
+
 @Tool({
   name: 'step2',
   description: 'A tool that fails when shouldFail is true.',
+  resultSchema: Step2ToolResultSchema,
+  effects: 'none',
 })
 export class Step2Tool extends BaseTool<{ shouldFail: boolean }, object, Step2ToolResult> {
   protected async handle(args: { shouldFail: boolean }): Promise<ToolEnvelope<Step2ToolResult>> {

package/src/workflows/fan-out/fan-out-example.workflow.ts

@@ -19,7 +19,7 @@ export class RunSubWorkflowExampleFanOutWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'awaiting' })
-  async launch(_state: Record<string, unknown>) {
+  async launch() {
     await this.fanOut.run(
       {
         items: {

package/src/workflows/module-config/consumers/default-greeting.workflow.ts

@@ -11,7 +11,7 @@ export class DefaultGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'done' })
-  async greet(_state: Record<string, unknown>) {
+  async greet() {
     const result = await this.greeter.call({ name: 'World' });
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
@@ -20,5 +20,5 @@ export class DefaultGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'done', to: 'end' })
-  finish(_state: Record<string, unknown>) {}
+  finish() {}
 }

package/src/workflows/module-config/consumers/french-greeting.workflow.ts

@@ -12,7 +12,7 @@ export class FrenchGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'done' })
-  async greet(_state: Record<string, unknown>) {
+  async greet() {
     const result = await this.greeter.call({ name: 'Monde' });
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
@@ -21,5 +21,5 @@ export class FrenchGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'done', to: 'end' })
-  finish(_state: Record<string, unknown>) {}
+  finish() {}
 }

package/src/workflows/module-config/consumers/german-greeting.workflow.ts

@@ -11,7 +11,7 @@ export class GermanGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'done' })
-  async greet(_state: Record<string, unknown>) {
+  async greet() {
     const result = await this.greeter.call({ name: 'Welt' });
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
@@ -20,5 +20,5 @@ export class GermanGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'done', to: 'end' })
-  finish(_state: Record<string, unknown>) {}
+  finish() {}
 }

package/src/workflows/module-config/consumers/nested-greeting.workflow.ts

@@ -12,7 +12,7 @@ export class NestedGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'done' })
-  async greet(_state: Record<string, unknown>) {
+  async greet() {
     const result = await this.greeter.call({ name: 'Mundo' });
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
@@ -21,5 +21,5 @@ export class NestedGreetingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'done', to: 'end' })
-  finish(_state: Record<string, unknown>) {}
+  finish() {}
 }

package/src/workflows/module-config/greeter/greeter.tool.ts

@@ -16,9 +16,17 @@ export interface GreetResult {
   greeting: string;
 }
 
+export const GreetResultSchema = z.strictObject({
+  message: z.string(),
+  language: z.string(),
+  greeting: z.string(),
+});
+
 @Tool({
   name: 'greeter',
   schema: GreeterArgsSchema,
+  resultSchema: GreetResultSchema,
+  effects: 'none',
 })
 export class GreeterTool extends BaseTool<GreeterArgs, object, GreetResult> {
   @Inject(GREETER_CONFIG) private readonly config: GreeterConfig;

package/src/workflows/sequence/sequence-example.workflow.ts

@@ -19,7 +19,7 @@ export class RunSubWorkflowExampleSequenceWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'awaiting' })
-  async launch(_state: Record<string, unknown>) {
+  async launch() {
     await this.sequence.run(
       {
         items: [

package/src/workflows/sub-workflow/__tests__/sub-workflow-stateless.spec.ts

@@ -0,0 +1,80 @@
+import { TestingModule } from '@nestjs/testing';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { executedTransitions } from '@loopstack/contracts/types';
+import { WorkflowProcessorService } from '@loopstack/core';
+import { createStatelessContext, createWorkflowTest, runWorkflow } from '@loopstack/testing';
+import { RunSubWorkflowExampleParentWorkflow } from '../sub-workflow-parent.workflow';
+import { RunSubWorkflowExampleSubWorkflow } from '../sub-workflow-sub.workflow';
+
+/**
+ * Advanced — the low-level processor API the facade wraps, shown for authors who need direct
+ * access to the stateless carrier (children, callbacks, trace). **Most workflow tests should
+ * use `runWorkflow` (second describe below)**, which exposes the same outcomes without the
+ * plumbing. Children run inline, callbacks are applied automatically, and the whole
+ * composition completes in a single `process()` call — no Redis, no Postgres.
+ */
+describe('RunSubWorkflowExampleParentWorkflow — stateless inline children (low-level API)', () => {
+  let module: TestingModule;
+  let workflow: RunSubWorkflowExampleParentWorkflow;
+  let processor: WorkflowProcessorService;
+
+  beforeEach(async () => {
+    module = await createWorkflowTest()
+      .forWorkflow(RunSubWorkflowExampleParentWorkflow)
+      .withProvider(RunSubWorkflowExampleSubWorkflow)
+      .compile();
+
+    workflow = module.get(RunSubWorkflowExampleParentWorkflow);
+    processor = module.get(WorkflowProcessorService);
+  });
+
+  afterEach(async () => {
+    await module.close();
+  });
+
+  it('runs both children inline and completes in a single call', async () => {
+    const result = await processor.process(workflow, {}, createStatelessContext());
+
+    expect(result.hasError).toBe(false);
+    expect(result.status).toBe('completed');
+    expect(result.place).toBe('end');
+    expect(executedTransitions(result.trace).map((e) => e.transitionId)).toEqual([
+      'runWorkflow',
+      'subWorkflowCallback',
+      'runWorkflow2',
+      'subWorkflow2Callback',
+    ]);
+
+    // Parent documents carry the child results delivered via the callbacks
+    const texts = result.documents.map((d) => (d.content as { text?: string }).text);
+    expect(texts).toEqual(
+      expect.arrayContaining(['A message from sub workflow 1: Hi mom!', 'A message from sub workflow 2: Hi mom!']),
+    );
+
+    // Both inline children are recorded with their own results and documents
+    const children = result.statelessState?.children ?? [];
+    expect(children).toHaveLength(2);
+    for (const child of children) {
+      expect(child.status).toBe('completed');
+      expect(child.result).toEqual({ message: 'Hi mom!' });
+      expect(child.documents.length).toBeGreaterThan(0);
+    }
+
+    // All callbacks were drained
+    expect(result.statelessState?.callbacks).toBeUndefined();
+  });
+});
+
+describe('RunSubWorkflowExampleParentWorkflow — runWorkflow facade', () => {
+  it('completes the whole composition through the facade', async () => {
+    const run = await runWorkflow(RunSubWorkflowExampleParentWorkflow, undefined, {
+      providers: [RunSubWorkflowExampleSubWorkflow],
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['runWorkflow', 'subWorkflowCallback', 'runWorkflow2', 'subWorkflow2Callback']);
+    expect(run.children).toHaveLength(2);
+    expect(run.children.every((c) => c.status === 'completed')).toBe(true);
+  });
+});

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

@@ -18,7 +18,7 @@ export class RunSubWorkflowExampleErrorHandlingWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'inline_awaiting' })
-  async launchInline(_state: Record<string, unknown>) {
+  async launchInline() {
     await this.failingSub.run(
       {},
       { callback: { transition: 'onInlineFinished' }, show: 'inline', label: 'Failing sub-workflow (inline)' },

package/src/workflows/sub-workflow/sub-workflow-failing-sub.workflow.ts

@@ -11,7 +11,7 @@ import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/
 })
 export class RunSubWorkflowExampleFailingSubWorkflow extends BaseWorkflow {
   @Transition({ to: 'end' })
-  async fail(_state: Record<string, unknown>) {
+  async fail() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'About to throw — this child always fails on purpose.',

package/src/workflows/sub-workflow/sub-workflow-parent.workflow.ts

@@ -15,7 +15,7 @@ export class RunSubWorkflowExampleParentWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'sub_workflow_started' })
-  async runWorkflow(_state: Record<string, unknown>) {
+  async runWorkflow() {
     await this.subWorkflow.run(
       {},
       { callback: { transition: 'subWorkflowCallback' }, show: 'link', label: 'Sub-Workflow' },
@@ -36,7 +36,7 @@ export class RunSubWorkflowExampleParentWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'sub_workflow_ended', to: 'sub_workflow2_started' })
-  async runWorkflow2(_state: Record<string, unknown>) {
+  async runWorkflow2() {
     await this.subWorkflow.run(
       {},
       { callback: { transition: 'subWorkflow2Callback' }, show: 'link', label: 'Sub-Workflow 2' },

package/src/workflows/sub-workflow/sub-workflow-show-modes.workflow.ts

@@ -23,7 +23,7 @@ export class RunSubWorkflowExampleShowModesWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'inline_started' })
-  async runInline(_state: Record<string, unknown>) {
+  async runInline() {
     await this.sub.run(
       {},
       { callback: { transition: 'onInlineDone' }, show: 'inline', label: 'Inline embed (iframe)' },

package/src/workflows/sub-workflow/sub-workflow-sub.workflow.ts

@@ -6,7 +6,7 @@ import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/
 })
 export class RunSubWorkflowExampleSubWorkflow extends BaseWorkflow {
   @Transition({ to: 'end' })
-  async message(_state: Record<string, unknown>) {
+  async message() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: 'Sub workflow completed.',

package/src/workflows/ui-documents/ui-documents-example.workflow.ts

@@ -15,7 +15,7 @@ import {
 })
 export class TestUiDocumentsWorkflow extends BaseWorkflow {
   @Transition({ to: 'rendered' })
-  async renderAll(_state: Record<string, unknown>) {
+  async renderAll() {
     // Message
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
@@ -39,5 +39,5 @@ export class TestUiDocumentsWorkflow extends BaseWorkflow {
   }
 
   @Transition({ from: 'rendered', to: 'end' })
-  done(_state: Record<string, unknown>) {}
+  done() {}
 }

package/src/workflows/workflow-state/tool-results-example.workflow.ts

@@ -10,7 +10,7 @@ interface ToolResultsState {
 })
 export class WorkflowToolResultsWorkflow extends BaseWorkflow {
   @Transition({ to: 'data_created' })
-  async createSomeData(_state: ToolResultsState) {
+  async createSomeData() {
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
       text: `Stored in initial transition: Hello World.`,

package/src/workflows/workflow-state/workflow-state-example.workflow.ts

@@ -10,7 +10,7 @@ interface WorkflowStateState {
 })
 export class WorkflowStateWorkflow extends BaseWorkflow {
   @Transition({ to: 'data_created' })
-  createSomeData(_state: WorkflowStateState) {
+  createSomeData() {
     this.assignState({ message: 'Hello :)' });
   }