@loopstack/hitl-examples 0.1.1 → 0.2.1

package/src/workflows/meeting-notes/__tests__/meeting-notes-example.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, replay, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { MeetingNotesExampleWorkflow } from '../meeting-notes-example.workflow';
+
+const OPTIMIZED = {
+  date: '2025-01-01',
+  summary: 'Budget review and hiring decision.',
+  participants: ['Sarah', 'Anna'],
+  decisions: ['Cut costs', 'Hire for marketing'],
+  actionItems: ['Anna follows up on vendor pricing'],
+};
+
+/** The scripted extraction turn in the shape `llm_generate_object` returns. */
+const extraction = () =>
+  replay({
+    version: 3,
+    recordings: [
+      {
+        tool: 'llm_generate_object',
+        envelope: {
+          data: { data: OPTIMIZED, response: {} },
+          metadata: { provider: 'claude', model: 'claude-sonnet-4-6' },
+        },
+      },
+    ],
+  });
+
+describe('MeetingNotesExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+
+  it('runs the full review flow: edit notes → scripted LLM extraction → confirm', async () => {
+    const run = await runWorkflow(
+      MeetingNotesExampleWorkflow,
+      { inputText: 'budget: cut costs; anna follows up on vendor pricing' },
+      {
+        imports: [LlmProviderModule, HitlExamplesModule],
+        answers: {
+          userResponse: { text: 'Reviewed notes: cut costs, Anna follows up on vendor pricing.' },
+          confirm: OPTIMIZED,
+        },
+        replay: extraction(),
+      },
+    );
+    runs.push(run);
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['createForm', 'userResponse', 'optimizeNotes', 'confirm']);
+    expect(run.result).toEqual({ optimizedNotes: OPTIMIZED });
+    expect(run.document('final')).toEqual(OPTIMIZED);
+  });
+
+  it('parks on the notes review form (first park)', async () => {
+    const run = await runWorkflow(MeetingNotesExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+    });
+    runs.push(run);
+
+    expect(run.status).toBe('waiting');
+    expect(run.place).toBe('waiting_for_response');
+
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      widget: 'form',
+      documentName: 'meeting_notes',
+      content: { text: expect.stringContaining('Unstructured Notes:') },
+      actions: ['Optimize Notes'],
+      defaultTransition: 'userResponse',
+    });
+  });
+
+  it('parks on the optimized-notes confirm form (second park)', async () => {
+    const run = await runWorkflow(
+      MeetingNotesExampleWorkflow,
+      { inputText: 'budget: cut costs' },
+      {
+        imports: [LlmProviderModule, HitlExamplesModule],
+        // Answer the first park but not the second — the run advances through the LLM
+        // extraction and parks again on the confirmation form.
+        answers: { userResponse: { text: 'Reviewed notes.' } },
+        replay: extraction(),
+      },
+    );
+    runs.push(run);
+
+    expect(run.status).toBe('waiting');
+    expect(run.place).toBe('notes_optimized');
+
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      widget: 'form',
+      documentName: 'optimized_notes',
+      actions: ['Confirm'],
+      defaultTransition: 'confirm',
+    });
+  });
+
+  it('covers every transition and both parks (coverage gate)', () => {
+    const cov = coverage(runs, MeetingNotesExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/prompt-input-chat/__tests__/prompt-input-chat-example.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { queue, replay, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { PromptInputChatExampleWorkflow } from '../prompt-input-chat-example.workflow';
+
+/**
+ * A scripted assistant reply in the shape `llm_generate_text` returns — including the
+ * `documents` declaration the live tool emits, so replay materializes the assistant
+ * message as a conversation document exactly like a real call would.
+ */
+const assistantReply = (text: string) => {
+  const message = {
+    id: `msg_${text.length}`,
+    role: 'assistant',
+    text,
+    blocks: [{ type: 'text', text }],
+    stopReason: 'end_turn',
+  };
+  return {
+    tool: 'llm_generate_text',
+    envelope: {
+      data: { message, response: {} },
+      metadata: { provider: 'claude', model: 'claude-sonnet-4-6' },
+      documents: [
+        {
+          documentName: 'llm_message',
+          content: message,
+          options: { meta: { response: {}, provider: 'claude' } },
+        },
+      ],
+    },
+  };
+};
+
+describe('PromptInputChatExampleWorkflow', () => {
+  it('drives two chat turns with queued messages and scripted LLM replies, then parks again', async () => {
+    const run = await runWorkflow(PromptInputChatExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+      answers: { userMessage: queue('What is Loopstack?', 'And what about pricing?') },
+      replay: replay({
+        version: 3,
+        recordings: [assistantReply('Loopstack is a workflow framework.'), assistantReply('It is open source.')],
+      }),
+    });
+
+    expect(run.error).toBeUndefined();
+    // The chat loops back to waiting after each reply — two scripted turns, then parked again.
+    // Storing the message (userMessage) and generating the reply (generateReply) are separate
+    // transitions so the user's message is committed — and visible — before the LLM turn runs.
+    expect(run.status).toBe('waiting');
+    expect(run.place).toBe('waiting_for_user');
+    expect(run.path).toEqual(['greet', 'userMessage', 'generateReply', 'userMessage', 'generateReply']);
+
+    // Both sides of the conversation are documents: user messages from the workflow,
+    // assistant replies from the replayed envelopes' document declarations.
+    const texts = run.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('What is Loopstack?');
+    expect(texts).toContain('Loopstack is a workflow framework.');
+    expect(texts).toContain('And what about pricing?');
+    expect(texts).toContain('It is open source.');
+  });
+
+  it('parks on the greeting when no message is scripted', async () => {
+    const run = await runWorkflow(PromptInputChatExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+    });
+
+    expect(run.status).toBe('waiting');
+    expect(run.path).toEqual(['greet']);
+    const texts = run.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('Hi! Ask me anything.');
+
+    // The chat input the user would type into — a workflow-level `prompt-input` widget
+    // (from the workflow's own `widget:` config), active at the waiting_for_user place.
+    // The greeting message above is display content, not a prompt, so it isn't surfaced here.
+    expect(run.parkView()).toMatchObject({
+      widget: 'prompt-input',
+      options: { label: 'Send' },
+      defaultTransition: 'userMessage',
+    });
+  });
+});

package/src/workflows/prompt-input-chat/prompt-input-chat-example.workflow.ts

@@ -1,30 +1,52 @@
 import { z } from 'zod';
-import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import { BaseWorkflow, Transition, Workflow } from '@loopstack/common';
 import type { TransitionInput } from '@loopstack/common';
+import { LlmGenerateTextTool, LlmMessageDocument } from '@loopstack/llm-provider-module';
 
 @Workflow({
   title: 'HITL - Prompt Input Chat Example',
   description:
-    'Predefined-workflow HITL via the prompt-input widget. The workflow loops: it waits for a user ' +
-    'message, echoes back a reply, and re-enters the waiting state. No LLM and no sub-workflow involved.',
+    'Predefined-workflow HITL chat via the prompt-input widget. The workflow loops: it waits for a user ' +
+    'message, generates an LLM reply from the full conversation history, and re-enters the waiting state.',
   widget: './prompt-input-chat-example.workflow.yaml',
 })
 export class PromptInputChatExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly llmGenerateText: LlmGenerateTextTool) {
+    super();
+  }
+
   @Transition({ to: 'waiting_for_user' })
-  async greet(_state: Record<string, unknown>) {
-    await this.documentStore.save(MessageDocument, {
+  async greet() {
+    // Same document type as every other chat turn: renders like one and, being tagged
+    // 'message', joins the conversation history the provider builds below.
+    await this.documentStore.save(LlmMessageDocument, {
       role: 'assistant',
-      text: 'Hi! Send me a message and I will echo it back.',
+      text: 'Hi! Ask me anything.',
     });
   }
 
-  @Transition({ from: 'waiting_for_user', to: 'reply_sent', wait: true, schema: z.string() })
+  // Storing the message and generating the reply are separate transitions on purpose:
+  // each transition commits its own transaction, so the user's message becomes visible
+  // in the UI immediately — before the (slow) LLM turn even starts.
+  @Transition({ from: 'waiting_for_user', to: 'generating_reply', wait: true, schema: z.string() })
   async userMessage(state: Record<string, unknown>, input: TransitionInput<string>) {
-    const payload = input.data;
-    await this.documentStore.save(MessageDocument, { role: 'user', text: payload });
-    await this.documentStore.save(MessageDocument, { role: 'assistant', text: `You said: ${payload}` });
+    // Tagged 'message', so it becomes part of the conversation history below
+    await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data });
   }
 
-  @Transition({ from: 'reply_sent', to: 'waiting_for_user' })
-  loop(_state: Record<string, unknown>) {}
+  @Transition({ from: 'generating_reply', to: 'waiting_for_user' })
+  async generateReply() {
+    // No prompt/messages args: the provider builds the conversation from all
+    // documents tagged 'message' and saves the assistant reply automatically
+    await this.llmGenerateText.call(
+      {},
+      {
+        config: {
+          provider: 'claude',
+          model: 'claude-sonnet-4-6',
+          system: 'You are a friendly, concise chat assistant.',
+        },
+      },
+    );
+  }
 }