@loopstack/advanced-workflows-examples 0.1.1

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

@@ -0,0 +1,38 @@
+import { Inject } from '@nestjs/common';
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+import { GREETER_CONFIG } from './greeter.constants.js';
+import type { GreeterConfig } from './greeter.constants.js';
+
+export const GreeterArgsSchema = z.object({
+  name: z.string().describe('Name to greet'),
+});
+
+type GreeterArgs = z.infer<typeof GreeterArgsSchema>;
+
+export interface GreetResult {
+  message: string;
+  language: string;
+  greeting: string;
+}
+
+@Tool({
+  name: 'greeter',
+  schema: GreeterArgsSchema,
+})
+export class GreeterTool extends BaseTool<GreeterArgs, object, GreetResult> {
+  @Inject(GREETER_CONFIG) private readonly config: GreeterConfig;
+
+  protected async handle(args: GreeterArgs): Promise<ToolEnvelope<GreetResult>> {
+    const language = this.config.language ?? 'en';
+    const greeting = this.config.greeting ?? 'Hello';
+
+    return {
+      data: {
+        message: `${greeting}, ${args.name}! [language=${language}]`,
+        language,
+        greeting,
+      },
+    };
+  }
+}

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

@@ -0,0 +1,3 @@
+export * from './greeter.constants.js';
+export * from './greeter.module.js';
+export * from './greeter.tool.js';

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

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { SequenceResultSchema, SequenceWorkflow } from '@loopstack/core';
+
+type SequenceResultData = z.infer<typeof SequenceResultSchema>;
+
+/**
+ * Demonstrates `SequenceWorkflow` — runs three sub-workflows one at a time and
+ * receives a single aggregated callback after the last one completes.
+ */
+@Workflow({
+  title: 'Advanced - Sequence Example',
+  description:
+    'Runs multiple sub-workflows sequentially via SequenceWorkflow and aggregates results in a single callback.',
+})
+export class RunSubWorkflowExampleSequenceWorkflow extends BaseWorkflow {
+  constructor(private readonly sequence: SequenceWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'awaiting' })
+  async launch(_state: Record<string, unknown>) {
+    await this.sequence.run(
+      {
+        items: [
+          { workflow: 'run_sub_workflow_example_sub', label: 'step-1' },
+          { workflow: 'run_sub_workflow_example_sub', label: 'step-2' },
+          { workflow: 'run_sub_workflow_example_sub', label: 'step-3' },
+        ],
+      },
+      { callback: { transition: 'onComplete' }, label: 'Sequence children', show: 'link' },
+    );
+  }
+
+  @Transition({
+    from: 'awaiting',
+    to: 'end',
+    wait: true,
+    schema: SequenceResultSchema,
+  })
+  async onComplete(state: Record<string, unknown>, input: TransitionInput<SequenceResultData>) {
+    const results = input.data.results as Array<{ key: string; data?: unknown }>;
+
+    for (const entry of results) {
+      const data = (entry.data ?? {}) as { message?: string };
+      await this.documentStore.save(MessageDocument, {
+        role: 'assistant',
+        text: `Sequence ${entry.key}: ${data.message ?? '(no message)'}`,
+      });
+    }
+
+    this.setResult({ hasErrors: input.data.hasErrors, errorCount: input.data.errorCount } as unknown as Record<
+      string,
+      unknown
+    >);
+  }
+}

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

@@ -0,0 +1,63 @@
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { RunSubWorkflowExampleFailingSubWorkflow } from './sub-workflow-failing-sub.workflow';
+
+/**
+ * Launches the failing sub-workflow in both `show: 'inline'` and `show: 'link'` modes so the
+ * error UI can be inspected in each. The parent branches on `input.hasError` and surfaces
+ * `input.errorMessage` to demonstrate that the envelope carries the failure context — no
+ * need to query the child entity separately.
+ */
+@Workflow({
+  title: 'Advanced - Sub-Workflow Error Handling Example',
+  description:
+    'Demonstrates handling failed child workflows via input.hasError and input.errorMessage on the callback envelope.',
+})
+export class RunSubWorkflowExampleErrorHandlingWorkflow extends BaseWorkflow {
+  constructor(private readonly failingSub: RunSubWorkflowExampleFailingSubWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'inline_awaiting' })
+  async launchInline(_state: Record<string, unknown>) {
+    await this.failingSub.run(
+      {},
+      { callback: { transition: 'onInlineFinished' }, show: 'inline', label: 'Failing sub-workflow (inline)' },
+    );
+  }
+
+  @Transition({
+    from: 'inline_awaiting',
+    to: 'link_awaiting',
+    wait: true,
+  })
+  async onInlineFinished(state: Record<string, unknown>, input: TransitionInput) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: input.hasError
+        ? `Inline child failed (status="${input.status}"): ${input.errorMessage ?? 'unknown error'}. Trying the same failing child with show: 'link' next.`
+        : `Inline child finished normally (status="${input.status}").`,
+    });
+    await this.failingSub.run(
+      {},
+      { callback: { transition: 'onLinkFinished' }, show: 'link', label: 'Failing sub-workflow (link)' },
+    );
+  }
+
+  @Transition({
+    from: 'link_awaiting',
+    to: 'end',
+    wait: true,
+  })
+  async onLinkFinished(_state: Record<string, unknown>, input: TransitionInput) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: input.hasError
+        ? `Link child failed (status="${input.status}"): ${input.errorMessage ?? 'unknown error'}. The parent recovered gracefully.`
+        : `Link child finished normally (status="${input.status}").`,
+    });
+    this.setResult({ childStatus: input.status, childErrorMessage: input.errorMessage } as unknown as Record<
+      string,
+      unknown
+    >);
+  }
+}

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

@@ -0,0 +1,21 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+
+/**
+ * A sub-workflow that always throws — useful for exercising the parent-side error UI
+ * (red link card, inline error message) and for verifying that callbacks still fire
+ * with `status: 'failed'` when a child crashes.
+ */
+@Workflow({
+  name: 'run_sub_workflow_example_failing_sub',
+  title: 'Advanced - Failing Sub-Workflow (child)',
+})
+export class RunSubWorkflowExampleFailingSubWorkflow extends BaseWorkflow {
+  @Transition({ to: 'end' })
+  async fail(_state: Record<string, unknown>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'About to throw — this child always fails on purpose.',
+    });
+    throw new Error('Demo failure: this sub-workflow is wired to always throw.');
+  }
+}

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

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { RunSubWorkflowExampleSubWorkflow } from './sub-workflow-sub.workflow';
+
+const SubWorkflowMessageSchema = z.object({ message: z.string() });
+
+@Workflow({
+  title: 'Advanced - Sub-Workflow Example',
+  description:
+    'Launches a child workflow via .run() and resumes when it completes — basic parent/child composition pattern.',
+})
+export class RunSubWorkflowExampleParentWorkflow extends BaseWorkflow {
+  constructor(private readonly subWorkflow: RunSubWorkflowExampleSubWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'sub_workflow_started' })
+  async runWorkflow(_state: Record<string, unknown>) {
+    await this.subWorkflow.run(
+      {},
+      { callback: { transition: 'subWorkflowCallback' }, show: 'link', label: 'Sub-Workflow' },
+    );
+  }
+
+  @Transition({
+    from: 'sub_workflow_started',
+    to: 'sub_workflow_ended',
+    wait: true,
+    schema: SubWorkflowMessageSchema,
+  })
+  async subWorkflowCallback(state: Record<string, unknown>, input: TransitionInput<{ message: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `A message from sub workflow 1: ${input.data.message}`,
+    });
+  }
+
+  @Transition({ from: 'sub_workflow_ended', to: 'sub_workflow2_started' })
+  async runWorkflow2(_state: Record<string, unknown>) {
+    await this.subWorkflow.run(
+      {},
+      { callback: { transition: 'subWorkflow2Callback' }, show: 'link', label: 'Sub-Workflow 2' },
+    );
+  }
+
+  @Transition({
+    from: 'sub_workflow2_started',
+    to: 'end',
+    wait: true,
+    schema: SubWorkflowMessageSchema,
+  })
+  async subWorkflow2Callback(state: Record<string, unknown>, input: TransitionInput<{ message: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `A message from sub workflow 2: ${input.data.message}`,
+    });
+  }
+}

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

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { RunSubWorkflowExampleSubWorkflow } from './sub-workflow-sub.workflow';
+
+const ShowMessageSchema = z.object({ message: z.string() });
+
+/**
+ * Demonstrates every `RunOptions.show` mode in one chained flow:
+ *
+ * 1. `show: 'inline'` — the child renders as an embedded iframe inside the parent's stream
+ *    and auto-collapses once it reaches a terminal state.
+ * 2. `show: 'link'` — the child renders as a status link card; clicking opens the child
+ *    in a separate window.
+ * 3. `show: 'hidden'` — the child runs without any UI in the parent's stream; the callback
+ *    still fires normally.
+ */
+@Workflow({
+  title: 'Advanced - Sub-Workflow Show Modes Example',
+})
+export class RunSubWorkflowExampleShowModesWorkflow extends BaseWorkflow {
+  constructor(private readonly sub: RunSubWorkflowExampleSubWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'inline_started' })
+  async runInline(_state: Record<string, unknown>) {
+    await this.sub.run(
+      {},
+      { callback: { transition: 'onInlineDone' }, show: 'inline', label: 'Inline embed (iframe)' },
+    );
+  }
+
+  @Transition({
+    from: 'inline_started',
+    to: 'link_started',
+    wait: true,
+    schema: ShowMessageSchema,
+  })
+  async onInlineDone(state: Record<string, unknown>, input: TransitionInput<{ message: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Inline child returned: ${input.data.message}`,
+    });
+    await this.sub.run({}, { callback: { transition: 'onLinkDone' }, show: 'link', label: 'Status link card' });
+  }
+
+  @Transition({
+    from: 'link_started',
+    to: 'hidden_started',
+    wait: true,
+    schema: ShowMessageSchema,
+  })
+  async onLinkDone(state: Record<string, unknown>, input: TransitionInput<{ message: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Link child returned: ${input.data.message}`,
+    });
+    await this.sub.run({}, { callback: { transition: 'onHiddenDone' }, show: 'hidden', label: 'Background child' });
+  }
+
+  @Transition({
+    from: 'hidden_started',
+    to: 'end',
+    wait: true,
+    schema: ShowMessageSchema,
+  })
+  async onHiddenDone(_state: Record<string, unknown>, input: TransitionInput<{ message: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Hidden child returned: ${input.data.message} — no LinkCard was rendered for it.`,
+    });
+  }
+}

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

@@ -0,0 +1,17 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+
+@Workflow({
+  name: 'run_sub_workflow_example_sub',
+  title: 'Advanced - Sub-Workflow (child)',
+})
+export class RunSubWorkflowExampleSubWorkflow extends BaseWorkflow {
+  @Transition({ to: 'end' })
+  async message(_state: Record<string, unknown>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'Sub workflow completed.',
+    });
+
+    this.setResult({ message: 'Hi mom!' } as unknown as Record<string, unknown>);
+  }
+}

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

@@ -0,0 +1,43 @@
+import {
+  BaseWorkflow,
+  ErrorDocument,
+  MarkdownDocument,
+  MessageDocument,
+  PlainDocument,
+  Transition,
+  Workflow,
+} from '@loopstack/common';
+
+@Workflow({
+  title: 'Advanced - UI Documents Example',
+  description:
+    'Smoke test for the built-in document types — MessageDocument, ErrorDocument, MarkdownDocument, PlainDocument.',
+})
+export class TestUiDocumentsWorkflow extends BaseWorkflow {
+  @Transition({ to: 'rendered' })
+  async renderAll(_state: Record<string, unknown>) {
+    // Message
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'This is the default message',
+    });
+
+    // Error
+    await this.documentStore.save(ErrorDocument, {
+      error: 'This is an error message',
+    });
+
+    // Markdown
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: '# Markdown\n\nThis is `markdown`\n',
+    });
+
+    // Plain Text
+    await this.documentStore.save(PlainDocument, {
+      text: 'This is plain text',
+    });
+  }
+
+  @Transition({ from: 'rendered', to: 'end' })
+  done(_state: Record<string, unknown>) {}
+}

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

@@ -0,0 +1,28 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+
+interface ToolResultsState {
+  storedMessage?: string;
+}
+
+@Workflow({
+  title: 'Advanced - Workflow Tool Result Example',
+  description: 'Storing tool results in workflow state and accessing them in later transitions.',
+})
+export class WorkflowToolResultsWorkflow extends BaseWorkflow {
+  @Transition({ to: 'data_created' })
+  async createSomeData(_state: ToolResultsState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Stored in initial transition: Hello World.`,
+    });
+    this.assignState({ storedMessage: 'Hello World.' });
+  }
+
+  @Transition({ from: 'data_created', to: 'end' })
+  async accessData(state: ToolResultsState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Accessed from previous transition: ${state.storedMessage}`,
+    });
+  }
+}

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

@@ -0,0 +1,33 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+
+interface WorkflowStateState {
+  message?: string;
+}
+
+@Workflow({
+  title: 'Advanced - Workflow State Example',
+  description: 'Persisting typed state across transitions with assignState() and reading it in later steps.',
+})
+export class WorkflowStateWorkflow extends BaseWorkflow {
+  @Transition({ to: 'data_created' })
+  createSomeData(_state: WorkflowStateState) {
+    this.assignState({ message: 'Hello :)' });
+  }
+
+  @Transition({ from: 'data_created', to: 'end' })
+  async showResults(state: WorkflowStateState) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Data from state: ${state.message}`,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Use workflow helper method: ${this.messageInUpperCase(state.message!)}`,
+    });
+  }
+
+  private messageInUpperCase(message: string): string {
+    return message?.toUpperCase();
+  }
+}