@loopstack/hitl-examples 0.1.1 → 0.2.0

package/src/workflows/agent-ask-clarification/__tests__/agent-ask-clarification-example.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { AgentModule } from '@loopstack/agent';
+import { LlmGenerateTextTool, LlmProviderModule } from '@loopstack/llm-provider-module';
+import { replay, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AgentAskClarificationExampleWorkflow } from '../agent-ask-clarification-example.workflow';
+
+/**
+ * A scripted agent LLM turn 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 llmTurn = (message: { id: string; role: string; text: string; blocks: unknown[]; stopReason: string }) => ({
+  tool: 'llm_generate_text',
+  envelope: {
+    data: { message, response: {} },
+    metadata: { provider: 'claude', model: 'claude-sonnet-4-6' },
+    documents: [{ documentName: 'llm_message', content: message, options: { meta: { provider: 'claude' } } }],
+  },
+});
+
+const CLARIFICATION_TURN = llmTurn({
+  id: 'msg_1',
+  role: 'assistant',
+  text: '',
+  blocks: [
+    {
+      type: 'tool_call',
+      id: 'toolu_1',
+      name: 'ask_clarification',
+      args: { question: 'What is your budget, and do you prefer a warm or cold climate?' },
+    },
+  ],
+  stopReason: 'tool_use',
+});
+
+const RECOMMENDATION_TURN = llmTurn({
+  id: 'msg_2',
+  role: 'assistant',
+  text: 'With €2000 and a warm climate in mind, I recommend Lisbon, Portugal.',
+  blocks: [{ type: 'text', text: 'With €2000 and a warm climate in mind, I recommend Lisbon, Portugal.' }],
+  stopReason: 'end_turn',
+});
+
+describe('AgentAskClarificationExampleWorkflow', () => {
+  it('replays the LLM turns while the agent, clarification tool, and HITL child run live', async () => {
+    const run = await runWorkflow(AgentAskClarificationExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      replayTools: [LlmGenerateTextTool],
+      replay: replay({ version: 3, recordings: [CLARIFICATION_TURN, RECOMMENDATION_TURN] }),
+      answers: { userAnswered: { answer: 'Budget €2000, warm climate please' } },
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['start', 'agentComplete']);
+    expect(run.result).toEqual({ response: 'With €2000 and a warm climate in mind, I recommend Lisbon, Portugal.' });
+
+    // The agent child ran the loop to completion — assert its outcome, not its internals.
+    expect(run.children).toHaveLength(1);
+    const agent = run.children[0];
+    expect(agent.workflowName).toBe('agent');
+    expect(agent.status).toBe('completed');
+    expect(agent.result).toEqual({ response: 'With €2000 and a warm climate in mind, I recommend Lisbon, Portugal.' });
+  });
+
+  it('parks with the clarification question shown when no answer is scripted', async () => {
+    const run = await runWorkflow(AgentAskClarificationExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      replayTools: [LlmGenerateTextTool],
+      replay: replay({ version: 3, recordings: [CLARIFICATION_TURN] }),
+    });
+
+    expect(run.status).toBe('waiting');
+    // The clarification prompt lives on the AskUserWorkflow launched by the agent's tool call,
+    // several levels down. parkView() walks the tree and surfaces what the user would see —
+    // no manual traversal of the stateless carrier.
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      workflowName: 'ask_user',
+      widget: 'text-prompt',
+      content: { question: expect.stringContaining('budget') },
+      defaultTransition: 'userAnswered',
+    });
+  });
+});

package/src/workflows/agent-ask-clarification/agent-ask-clarification-example.workflow.ts

@@ -21,7 +21,7 @@ export class AgentAskClarificationExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'running' })
-  async start(_state: Record<string, unknown>) {
+  async start() {
     await this.agentWorkflow.run(
       {
         system: SYSTEM_PROMPT,

package/src/workflows/agent-ask-for-approval/__tests__/agent-ask-for-approval-example.live.spec.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { AgentModule } from '@loopstack/agent';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AgentAskForApprovalExampleWorkflow } from '../agent-ask-for-approval-example.workflow';
+
+/**
+ * Live-LLM check-up (`npm run test:live`, needs ANTHROPIC_API_KEY): the real model drafts
+ * release notes and requests approval; the scripted confirmation resumes it. Assertions are
+ * structural — completion and a non-empty markdown response.
+ */
+describe('AgentAskForApprovalExampleWorkflow — live', () => {
+  it('drafts release notes, gets approval, and responds with the markdown', async () => {
+    const run = await runWorkflow(AgentAskForApprovalExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      answers: { userConfirmed: {} },
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['start', 'agentComplete']);
+
+    const result = run.result as { response: string };
+    expect(result.response.length).toBeGreaterThan(0);
+  });
+});

package/src/workflows/agent-ask-for-approval/__tests__/agent-ask-for-approval-example.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { AgentModule } from '@loopstack/agent';
+import { LlmGenerateTextTool, LlmProviderModule } from '@loopstack/llm-provider-module';
+import { replay, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AgentAskForApprovalExampleWorkflow } from '../agent-ask-for-approval-example.workflow';
+
+const DRAFT = '## v1.2.3\n\n- Added webhook signature verification\n- Fixed a date-parsing bug in the importer';
+
+/**
+ * A scripted agent LLM turn 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 llmTurn = (message: { id: string; role: string; text: string; blocks: unknown[]; stopReason: string }) => ({
+  tool: 'llm_generate_text',
+  envelope: {
+    data: { message, response: {} },
+    metadata: { provider: 'claude', model: 'claude-sonnet-4-6' },
+    documents: [{ documentName: 'llm_message', content: message, options: { meta: { provider: 'claude' } } }],
+  },
+});
+
+const DRAFT_TURN = llmTurn({
+  id: 'msg_1',
+  role: 'assistant',
+  text: '',
+  blocks: [{ type: 'tool_call', id: 'toolu_1', name: 'ask_for_approval', args: { concept: DRAFT } }],
+  stopReason: 'tool_use',
+});
+
+const FINAL_TURN = llmTurn({
+  id: 'msg_2',
+  role: 'assistant',
+  text: DRAFT,
+  blocks: [{ type: 'text', text: DRAFT }],
+  stopReason: 'end_turn',
+});
+
+describe('AgentAskForApprovalExampleWorkflow', () => {
+  it('approves the drafted markdown and completes with it as the response', async () => {
+    const run = await runWorkflow(AgentAskForApprovalExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      replayTools: [LlmGenerateTextTool],
+      replay: replay({ version: 3, recordings: [DRAFT_TURN, FINAL_TURN] }),
+      answers: { userConfirmed: {} },
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['start', 'agentComplete']);
+    expect(run.result).toEqual({ response: DRAFT });
+    // The approved markdown was published as a document by the parent (an observable outcome).
+    expect(run.documents.some((d) => (d.content as { markdown?: string }).markdown === DRAFT)).toBe(true);
+  });
+
+  it('completes with the rejection response when the user denies', async () => {
+    const rejectionTurn = llmTurn({
+      id: 'msg_2',
+      role: 'assistant',
+      text: 'The draft was rejected by the user.',
+      blocks: [{ type: 'text', text: 'The draft was rejected by the user.' }],
+      stopReason: 'end_turn',
+    });
+
+    const run = await runWorkflow(AgentAskForApprovalExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      replayTools: [LlmGenerateTextTool],
+      replay: replay({ version: 3, recordings: [DRAFT_TURN, rejectionTurn] }),
+      answers: { userDenied: {} },
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.result).toEqual({ response: 'The draft was rejected by the user.' });
+  });
+
+  it('parks showing the approval form when no answer is scripted', async () => {
+    const run = await runWorkflow(AgentAskForApprovalExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, AgentModule, HitlExamplesModule],
+      replayTools: [LlmGenerateTextTool],
+      replay: replay({ version: 3, recordings: [DRAFT_TURN] }),
+    });
+
+    expect(run.status).toBe('waiting');
+    // The agent's ask_for_approval tool launched a ConfirmUserWorkflow presenting the draft;
+    // parkView() surfaces the review form the user would act on.
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      workflowName: 'confirm_user',
+      widget: 'form',
+      content: { markdown: DRAFT },
+      actions: ['Deny', 'Confirm'],
+    });
+  });
+});

package/src/workflows/agent-ask-for-approval/agent-ask-for-approval-example.workflow.ts

@@ -22,7 +22,7 @@ export class AgentAskForApprovalExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'running' })
-  async start(_state: Record<string, unknown>) {
+  async start() {
     await this.agentWorkflow.run(
       {
         system: SYSTEM_PROMPT,

package/src/workflows/ask-user-confirm/__tests__/ask-user-confirm-example.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { HitlModule } from '@loopstack/hitl';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AskUserConfirmExampleWorkflow } from '../ask-user-confirm-example.workflow';
+
+describe('AskUserConfirmExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+  const run = async (answer?: 'yes' | 'no') => {
+    const result = await runWorkflow(AskUserConfirmExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlModule, HitlExamplesModule],
+      ...(answer ? { answers: { userAnswered: { answer } } } : {}),
+    });
+    runs.push(result);
+    return result;
+  };
+
+  it('confirms with "yes"', async () => {
+    const result = await run('yes');
+
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ sent: true });
+  });
+
+  it('declines with "no"', async () => {
+    const result = await run('no');
+
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ sent: false });
+    const texts = result.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('Skipping — email was not sent.');
+  });
+
+  it('parks showing the yes/no prompt when no answer is scripted', async () => {
+    const result = await run();
+
+    expect(result.status).toBe('waiting');
+    // The prompt lives on the AskUserWorkflow child, three levels down — parkView() walks
+    // the tree and resolves the same widget the CLI and Studio render.
+    const view = result.parkView();
+    expect(view).toMatchObject({
+      workflowName: 'ask_user',
+      widget: 'confirm-prompt',
+      content: { question: 'Send the email now?' },
+      defaultTransition: 'userAnswered',
+    });
+  });
+
+  it('covers every transition and park (coverage gate)', () => {
+    const cov = coverage(runs, AskUserConfirmExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/ask-user-confirm/ask-user-confirm-example.workflow.ts

@@ -16,7 +16,7 @@ export class AskUserConfirmExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'waiting_for_yes_no' })
-  async askToSend(_state: Record<string, unknown>) {
+  async askToSend() {
     await this.askUserWorkflow.run(
       { question: 'Send the email now?', mode: 'confirm' },
       { callback: { transition: 'decisionReceived' }, show: 'inline', label: 'Waiting for yes/no...' },

package/src/workflows/ask-user-options/__tests__/ask-user-options-example.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { HitlModule } from '@loopstack/hitl';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AskUserOptionsExampleWorkflow } from '../ask-user-options-example.workflow';
+
+describe('AskUserOptionsExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+  const run = async (answer?: string) => {
+    const result = await runWorkflow(AskUserOptionsExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlModule, HitlExamplesModule],
+      ...(answer ? { answers: { userAnswered: { answer } } } : {}),
+    });
+    runs.push(result);
+    return result;
+  };
+
+  it('picks a listed option', async () => {
+    const result = await run('staging');
+
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ environment: 'staging', custom: false });
+  });
+
+  it('accepts a custom answer outside the option list', async () => {
+    const result = await run('local-docker');
+
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ environment: 'local-docker', custom: true });
+    const texts = result.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('Custom environment selected: local-docker');
+  });
+
+  it('parks showing the choices when no answer is scripted', async () => {
+    const result = await run();
+
+    expect(result.status).toBe('waiting');
+    // The options list and custom-answer affordance the user would see, resolved from the
+    // AskUserWorkflow child by the same canonical rules the CLI and Studio use.
+    const view = result.parkView();
+    expect(view).toMatchObject({
+      workflowName: 'ask_user',
+      widget: 'choices',
+      content: {
+        question: 'Which environment should we deploy to?',
+        options: ['staging', 'production'],
+        allowCustomAnswer: true,
+      },
+      defaultTransition: 'userAnswered',
+    });
+  });
+
+  it('covers every transition and park (coverage gate)', () => {
+    const cov = coverage(runs, AskUserOptionsExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/ask-user-options/ask-user-options-example.workflow.ts

@@ -18,7 +18,7 @@ export class AskUserOptionsExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'waiting_for_choice' })
-  async askEnvironment(_state: Record<string, unknown>) {
+  async askEnvironment() {
     await this.askUserWorkflow.run(
       {
         question: 'Which environment should we deploy to?',

package/src/workflows/ask-user-text/__tests__/ask-user-text-example.spec.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { HitlModule } from '@loopstack/hitl';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { AskUserTextExampleWorkflow } from '../ask-user-text-example.workflow';
+
+describe('AskUserTextExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+
+  it('answers the inline AskUserWorkflow child and completes', async () => {
+    const run = await runWorkflow(AskUserTextExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlModule, HitlExamplesModule],
+      answers: { userAnswered: { answer: 'Ada' } },
+    });
+    runs.push(run);
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['askName', 'answerReceived']);
+    expect(run.result).toEqual({ name: 'Ada' });
+
+    expect(run.children).toHaveLength(1);
+    expect(run.children[0].workflowName).toBe('ask_user');
+    expect(run.children[0].status).toBe('completed');
+
+    const texts = run.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('Hello, Ada!');
+
+    // A completed run shows the user nothing to answer.
+    expect(run.parkView()).toBeUndefined();
+  });
+
+  it('parks with the question shown when no answer is scripted', async () => {
+    const run = await runWorkflow(AskUserTextExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlModule, HitlExamplesModule],
+    });
+    runs.push(run);
+
+    expect(run.status).toBe('waiting');
+    expect(run.children[0].status).toBe('waiting');
+
+    // What the user would actually see: the text prompt of the ask_user sub-workflow —
+    // resolved by the same canonical rules the CLI and Studio use.
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      workflowId: run.children[0].workflowId,
+      workflowName: 'ask_user',
+      widget: 'text-prompt',
+      documentName: 'ask_user',
+      content: { question: 'What is your name?' },
+      transitions: ['userAnswered'],
+      defaultTransition: 'userAnswered',
+    });
+  });
+
+  it('covers every transition and park (coverage gate)', () => {
+    const cov = coverage(runs, AskUserTextExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/ask-user-text/ask-user-text-example.workflow.ts

@@ -16,7 +16,7 @@ export class AskUserTextExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'waiting_for_answer' })
-  async askName(_state: Record<string, unknown>) {
+  async askName() {
     await this.askUserWorkflow.run(
       { question: 'What is your name?' },
       { callback: { transition: 'answerReceived' }, show: 'inline', label: 'Waiting for answer...' },

package/src/workflows/confirm-content/__tests__/confirm-content-example.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { HitlModule } from '@loopstack/hitl';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { ConfirmContentExampleWorkflow } from '../confirm-content-example.workflow';
+
+describe('ConfirmContentExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+  const run = async (decision?: 'userConfirmed' | 'userDenied') => {
+    const result = await runWorkflow(ConfirmContentExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlModule, HitlExamplesModule],
+      ...(decision ? { answers: { [decision]: {} } } : {}),
+    });
+    runs.push(result);
+    return result;
+  };
+
+  it('user confirms the summary', async () => {
+    const result = await run('userConfirmed');
+
+    expect(result.error).toBeUndefined();
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ confirmed: true });
+  });
+
+  it('user denies the summary', async () => {
+    const result = await run('userDenied');
+
+    expect(result.status).toBe('completed');
+    expect(result.result).toEqual({ confirmed: false });
+    const texts = result.documents.map((d) => (d.content as { text?: string }).text ?? '');
+    expect(texts).toContain('User denied — aborting deploy.');
+  });
+
+  it('parks showing the review form with the deploy summary', async () => {
+    const result = await run();
+
+    expect(result.status).toBe('waiting');
+    // The whole point of this example: show the user a markdown blob and wait. parkView()
+    // asserts they would see the review form (with its Deny/Confirm actions) carrying the summary.
+    const view = result.parkView();
+    expect(view).toMatchObject({
+      workflowName: 'confirm_user',
+      widget: 'form',
+      content: { markdown: expect.stringContaining('Ready to deploy?') },
+      actions: ['Deny', 'Confirm'],
+    });
+  });
+
+  it('covers every transition and park (coverage gate)', () => {
+    const cov = coverage(runs, ConfirmContentExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/confirm-content/confirm-content-example.workflow.ts

@@ -26,7 +26,7 @@ export class ConfirmContentExampleWorkflow extends BaseWorkflow {
   }
 
   @Transition({ to: 'waiting_for_confirmation' })
-  async showSummary(_state: Record<string, unknown>) {
+  async showSummary() {
     await this.confirmUserWorkflow.run(
       { markdown: DEPLOY_SUMMARY },
       { callback: { transition: 'decisionReceived' }, show: 'inline', label: 'Waiting for confirmation...' },

package/src/workflows/inline-form/__tests__/inline-form-example.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { type TestRun, coverage, runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { InlineFormExampleWorkflow } from '../inline-form-example.workflow';
+
+describe('InlineFormExampleWorkflow', () => {
+  const runs: TestRun[] = [];
+
+  it('submits the form via a scripted answer and completes', async () => {
+    const feedback = { subject: 'Loopstack HITL forms', rating: 5, comment: 'Great!' };
+
+    const run = await runWorkflow(InlineFormExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+      answers: { submitFeedback: feedback },
+    });
+    runs.push(run);
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['showForm', 'submitFeedback']);
+    expect(run.result).toEqual({ feedback });
+    expect(run.document('feedback')).toEqual(feedback);
+  });
+
+  it('parks on the pre-filled form when no answer is scripted', async () => {
+    const run = await runWorkflow(InlineFormExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+    });
+    runs.push(run);
+
+    expect(run.status).toBe('waiting');
+    expect(run.place).toBe('waiting_for_feedback');
+
+    // The custom form widget the user would fill in — its Submit action binds to the
+    // workflow's own wait transition, pre-filled with the workflow-provided subject.
+    // (The `subject` field's `readonly` rule is enforced by the form widget / API layer,
+    // not the state machine, so it isn't exercised here.)
+    const view = run.parkView();
+    expect(view).toMatchObject({
+      widget: 'form',
+      documentName: 'feedback_form',
+      content: { subject: 'Loopstack HITL forms', rating: 3 },
+      actions: ['Submit Feedback'],
+      defaultTransition: 'submitFeedback',
+    });
+  });
+
+  it('covers every transition and park (coverage gate)', () => {
+    const cov = coverage(runs, InlineFormExampleWorkflow);
+    expect(cov.missingTransitions).toEqual([]);
+    expect(cov.missingParks).toEqual([]);
+  });
+});

package/src/workflows/inline-form/feedback-form-document.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { Document } from '@loopstack/common';
 
 export const FeedbackFormDocumentSchema = z.object({
+  subject: z.string(),
   rating: z.number().min(1).max(5),
   comment: z.string(),
 });
@@ -11,6 +12,7 @@ export const FeedbackFormDocumentSchema = z.object({
   widget: './feedback-form-document.yaml',
 })
 export class FeedbackFormDocument {
+  subject: string;
   rating: number;
   comment: string;
 }

package/src/workflows/inline-form/feedback-form-document.yaml

@@ -1,6 +1,9 @@
 widget: form
 options:
   properties:
+    subject:
+      title: Subject
+      readonly: true
     rating:
       title: Rating (1–5)
       widget: number

package/src/workflows/inline-form/inline-form-example.workflow.ts

@@ -13,8 +13,15 @@ type FeedbackPayload = z.infer<typeof FeedbackFormDocumentSchema>;
 })
 export class InlineFormExampleWorkflow extends BaseWorkflow {
   @Transition({ to: 'waiting_for_feedback' })
-  async showForm(_state: Record<string, unknown>) {
-    await this.documentStore.save(FeedbackFormDocument, { rating: 3, comment: '' }, { key: 'feedback' });
+  async showForm() {
+    // `subject` is workflow-provided and marked `readonly: true` in the
+    // widget config — rendered non-editable, and the backend rejects
+    // submissions that change it.
+    await this.documentStore.save(
+      FeedbackFormDocument,
+      { subject: 'Loopstack HITL forms', rating: 3, comment: '' },
+      { key: 'feedback' },
+    );
   }
 
   @Transition({
@@ -29,7 +36,7 @@ export class InlineFormExampleWorkflow extends BaseWorkflow {
 
     await this.documentStore.save(MessageDocument, {
       role: 'assistant',
-      text: `Thanks for your feedback! Rating: ${payload.rating}/5. Comment: ${payload.comment}`,
+      text: `Thanks for your feedback on "${payload.subject}"! Rating: ${payload.rating}/5. Comment: ${payload.comment}`,
     });
 
     this.setResult({ feedback: payload } as unknown as Record<string, unknown>);

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

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { LlmProviderModule } from '@loopstack/llm-provider-module';
+import { runWorkflow } from '@loopstack/testing';
+import { HitlExamplesModule } from '../../../hitl-examples.module';
+import { MeetingNotesExampleWorkflow } from '../meeting-notes-example.workflow';
+
+/**
+ * Live-LLM check-up (`npm run test:live`, needs ANTHROPIC_API_KEY): the extraction step runs
+ * against the real model. Assertions are structural — path taken, schema shape — never exact
+ * content.
+ */
+describe('MeetingNotesExampleWorkflow — live', () => {
+  it('extracts structured notes from the real model', async () => {
+    const confirmSubmission = {
+      date: '2025-01-01',
+      summary: 'Confirmed as submitted.',
+      participants: ['Sarah'],
+      decisions: ['Cut costs'],
+      actionItems: ['Anna follows up on vendor pricing'],
+    };
+
+    const run = await runWorkflow(MeetingNotesExampleWorkflow, undefined, {
+      imports: [LlmProviderModule, HitlExamplesModule],
+      answers: {
+        userResponse: { text: 'Budget meeting: Sarah said cut costs. Anna follows up on vendor pricing.' },
+        confirm: confirmSubmission,
+      },
+    });
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    expect(run.path).toEqual(['createForm', 'userResponse', 'optimizeNotes', 'confirm']);
+
+    // The live extraction produced a schema-valid document before the user confirmed
+    const optimizedDocs = run.documents.filter((d) => Array.isArray((d.content as { decisions?: unknown }).decisions));
+    expect(optimizedDocs.length).toBeGreaterThan(0);
+  });
+});