@loopstack/hitl-examples 0.1.1

package/dist/workflows/prompt-input-chat/prompt-input-chat-example.workflow.js

@@ -0,0 +1,56 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptInputChatExampleWorkflow = void 0;
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+let PromptInputChatExampleWorkflow = class PromptInputChatExampleWorkflow extends common_1.BaseWorkflow {
+    async greet(_state) {
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: 'Hi! Send me a message and I will echo it back.',
+        });
+    }
+    async userMessage(state, input) {
+        const payload = input.data;
+        await this.documentStore.save(common_1.MessageDocument, { role: 'user', text: payload });
+        await this.documentStore.save(common_1.MessageDocument, { role: 'assistant', text: `You said: ${payload}` });
+    }
+    loop(_state) { }
+};
+exports.PromptInputChatExampleWorkflow = PromptInputChatExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'waiting_for_user' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], PromptInputChatExampleWorkflow.prototype, "greet", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'waiting_for_user', to: 'reply_sent', wait: true, schema: zod_1.z.string() }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], PromptInputChatExampleWorkflow.prototype, "userMessage", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'reply_sent', to: 'waiting_for_user' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], PromptInputChatExampleWorkflow.prototype, "loop", null);
+exports.PromptInputChatExampleWorkflow = PromptInputChatExampleWorkflow = __decorate([
+    (0, common_1.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.',
+        widget: './prompt-input-chat-example.workflow.yaml',
+    })
+], PromptInputChatExampleWorkflow);
+//# sourceMappingURL=prompt-input-chat-example.workflow.js.map

package/dist/workflows/prompt-input-chat/prompt-input-chat-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-input-chat-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/prompt-input-chat/prompt-input-chat-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAwF;AAUjF,IAAM,8BAA8B,GAApC,MAAM,8BAA+B,SAAQ,qBAAY;IAExD,AAAN,KAAK,CAAC,KAAK,CAAC,MAA+B;QACzC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,gDAAgD;SACvD,CAAC,CAAC;IACL,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,KAA8B,EAAE,KAA8B;QAC9E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC;QAC3B,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChF,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,OAAO,EAAE,EAAE,CAAC,CAAC;IACtG,CAAC;IAGD,IAAI,CAAC,MAA+B,IAAG,CAAC;CACzC,CAAA;AAlBY,wEAA8B;AAEnC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC;;;;2DAMtC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;;;;iEAK1F;AAGD;IADC,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC;;;;0DACnB;yCAjB7B,8BAA8B;IAP1C,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,kCAAkC;QACzC,WAAW,EACT,gGAAgG;YAChG,qGAAqG;QACvG,MAAM,EAAE,2CAA2C;KACpD,CAAC;GACW,8BAA8B,CAkB1C"}

package/dist/workflows/prompt-input-chat/prompt-input-chat-example.workflow.yaml

@@ -0,0 +1,6 @@
+widget: prompt-input
+enabledWhen:
+  - waiting_for_user
+options:
+  transition: userMessage
+  label: Send

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@loopstack/hitl-examples",
+  "displayName": "Loopstack HITL Examples",
+  "description": "Workflow examples for Human-in-the-Loop patterns in Loopstack — custom Document with widget, AskUserWorkflow / ConfirmUserWorkflow sub-workflow shortcuts, LLM agent loops with ask_clarification / ask_for_approval, and a meeting-notes review flow.",
+  "keywords": [
+    "loopstack",
+    "example",
+    "hitl",
+    "human-in-the-loop",
+    "ask-user",
+    "confirm",
+    "agent",
+    "form",
+    "prompt-input",
+    "workflow"
+  ],
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/agent": "*",
+    "@loopstack/claude-module": "*",
+    "@loopstack/common": "*",
+    "@loopstack/hitl": "*",
+    "@loopstack/llm-provider-module": "*",
+    "@nestjs/common": "^11.1.19",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.6",
+    "@swc/core": "^1.15.33",
+    "unplugin-swc": "^1.5.9"
+  }
+}

package/src/hitl-examples.module.ts

@@ -0,0 +1,40 @@
+import { Module } from '@nestjs/common';
+import { AgentModule } from '@loopstack/agent';
+import { ClaudeModule } from '@loopstack/claude-module';
+import { StudioApp } from '@loopstack/common';
+import { HitlModule } from '@loopstack/hitl';
+import { AgentAskClarificationExampleWorkflow } from './workflows/agent-ask-clarification/agent-ask-clarification-example.workflow';
+import { AgentAskForApprovalExampleWorkflow } from './workflows/agent-ask-for-approval/agent-ask-for-approval-example.workflow';
+import { AskUserConfirmExampleWorkflow } from './workflows/ask-user-confirm/ask-user-confirm-example.workflow';
+import { AskUserOptionsExampleWorkflow } from './workflows/ask-user-options/ask-user-options-example.workflow';
+import { AskUserTextExampleWorkflow } from './workflows/ask-user-text/ask-user-text-example.workflow';
+import { ConfirmContentExampleWorkflow } from './workflows/confirm-content/confirm-content-example.workflow';
+import { FeedbackFormDocument } from './workflows/inline-form/feedback-form-document';
+import { InlineFormExampleWorkflow } from './workflows/inline-form/inline-form-example.workflow';
+import { MeetingNotesDocument } from './workflows/meeting-notes/documents/meeting-notes-document';
+import { OptimizedNotesDocument } from './workflows/meeting-notes/documents/optimized-notes-document';
+import { MeetingNotesExampleWorkflow } from './workflows/meeting-notes/meeting-notes-example.workflow';
+import { PromptInputChatExampleWorkflow } from './workflows/prompt-input-chat/prompt-input-chat-example.workflow';
+
+const WORKFLOWS = [
+  InlineFormExampleWorkflow,
+  PromptInputChatExampleWorkflow,
+  AskUserTextExampleWorkflow,
+  AskUserOptionsExampleWorkflow,
+  AskUserConfirmExampleWorkflow,
+  ConfirmContentExampleWorkflow,
+  AgentAskClarificationExampleWorkflow,
+  AgentAskForApprovalExampleWorkflow,
+  MeetingNotesExampleWorkflow,
+];
+
+@StudioApp({
+  title: 'HITL Examples',
+  workflows: WORKFLOWS,
+})
+@Module({
+  imports: [HitlModule, AgentModule, ClaudeModule],
+  providers: [FeedbackFormDocument, MeetingNotesDocument, OptimizedNotesDocument, ...WORKFLOWS],
+  exports: WORKFLOWS,
+})
+export class HitlExamplesModule {}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './hitl-examples.module';
+
+export * from './workflows/inline-form/inline-form-example.workflow';
+export * from './workflows/inline-form/feedback-form-document';
+
+export * from './workflows/prompt-input-chat/prompt-input-chat-example.workflow';
+
+export * from './workflows/ask-user-text/ask-user-text-example.workflow';
+export * from './workflows/ask-user-options/ask-user-options-example.workflow';
+export * from './workflows/ask-user-confirm/ask-user-confirm-example.workflow';
+export * from './workflows/confirm-content/confirm-content-example.workflow';
+
+export * from './workflows/agent-ask-clarification/agent-ask-clarification-example.workflow';
+export * from './workflows/agent-ask-for-approval/agent-ask-for-approval-example.workflow';
+
+export * from './workflows/meeting-notes/meeting-notes-example.workflow';

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

@@ -0,0 +1,48 @@
+import { type AgentResult, AgentResultSchema, AgentWorkflow } from '@loopstack/agent';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+
+const SYSTEM_PROMPT = `You are a trip-planning assistant.
+
+CRITICAL RULES — your response MUST follow these:
+- Before recommending a destination, you MUST know BOTH the user's budget AND their preferred climate.
+- If EITHER is missing from the conversation, your response MUST be exactly ONE tool call to "ask_clarification".
+- Do NOT guess. Do NOT recommend a destination based on partial info.
+- Only after you have received BOTH pieces of information, recommend a single destination as a short paragraph.`;
+
+@Workflow({
+  title: 'HITL - Agent Ask Clarification Example',
+  description:
+    'Agent HITL: an LLM agent runs with the ask_clarification tool. When it lacks information, ' +
+    'it pauses the loop and prompts the user; the answer flows back into the agent context.',
+})
+export class AgentAskClarificationExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly agentWorkflow: AgentWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'running' })
+  async start(_state: Record<string, unknown>) {
+    await this.agentWorkflow.run(
+      {
+        system: SYSTEM_PROMPT,
+        tools: ['ask_clarification'],
+        userMessage: 'Where should I go on holiday next month?',
+      },
+      { callback: { transition: 'agentComplete' }, show: 'inline', label: 'Trip planner working...' },
+    );
+  }
+
+  @Transition({
+    from: 'running',
+    to: 'end',
+    wait: true,
+    schema: AgentResultSchema,
+  })
+  async agentComplete(_state: Record<string, unknown>, input: TransitionInput<AgentResult>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: input.data.response,
+    });
+    this.setResult(input.data);
+  }
+}

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

@@ -0,0 +1,47 @@
+import { type AgentResult, AgentResultSchema, AgentWorkflow } from '@loopstack/agent';
+import { BaseWorkflow, MarkdownDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+
+const SYSTEM_PROMPT = `You are a release-notes drafting assistant.
+
+Your task: produce a concise release-notes markdown draft, get explicit user approval via the "ask_for_approval" tool, then output the approved markdown as your final response.
+
+CRITICAL RULES — your response MUST follow these:
+- First turn: respond with exactly ONE tool call to "ask_for_approval". The "concept" argument IS the markdown draft. Do NOT write the draft as plain text in this turn.
+- After approval: your final text response MUST be the approved markdown verbatim, with no preamble, commentary, or trailing text.
+- After denial: respond with a brief one-line note that the draft was rejected.`;
+
+@Workflow({
+  title: 'HITL - Agent Ask For Approval Example',
+  description:
+    'Agent HITL: an LLM agent drafts content, then calls the ask_for_approval tool to show the markdown ' +
+    'to the user and pause until they confirm or deny.',
+})
+export class AgentAskForApprovalExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly agentWorkflow: AgentWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'running' })
+  async start(_state: Record<string, unknown>) {
+    await this.agentWorkflow.run(
+      {
+        system: SYSTEM_PROMPT,
+        tools: ['ask_for_approval'],
+        userMessage:
+          'Draft release notes for v1.2.3: added webhook signature verification; fixed a date-parsing bug in the importer.',
+      },
+      { callback: { transition: 'agentComplete' }, show: 'inline', label: 'Drafting release notes...' },
+    );
+  }
+
+  @Transition({
+    from: 'running',
+    to: 'end',
+    wait: true,
+    schema: AgentResultSchema,
+  })
+  async agentComplete(_state: Record<string, unknown>, input: TransitionInput<AgentResult>) {
+    await this.documentStore.save(MarkdownDocument, { markdown: input.data.response });
+    this.setResult(input.data);
+  }
+}

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { AskUserWorkflow } from '@loopstack/hitl';
+
+const AnswerSchema = z.object({ answer: z.string() });
+
+@Workflow({
+  title: 'HITL - Ask User Confirm Example',
+  description:
+    'Shortcut HITL: delegate a yes/no decision to AskUserWorkflow with mode "confirm". ' +
+    'The answer comes back as the literal string "yes" or "no".',
+})
+export class AskUserConfirmExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly askUserWorkflow: AskUserWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_yes_no' })
+  async askToSend(_state: Record<string, unknown>) {
+    await this.askUserWorkflow.run(
+      { question: 'Send the email now?', mode: 'confirm' },
+      { callback: { transition: 'decisionReceived' }, show: 'inline', label: 'Waiting for yes/no...' },
+    );
+  }
+
+  @Transition({
+    from: 'waiting_for_yes_no',
+    to: 'end',
+    wait: true,
+    schema: AnswerSchema,
+  })
+  async decisionReceived(state: Record<string, unknown>, input: TransitionInput<{ answer: string }>) {
+    const accepted = input.data.answer === 'yes';
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: accepted ? 'Sending the email now.' : 'Skipping — email was not sent.',
+    });
+    this.setResult({ sent: accepted } as unknown as Record<string, unknown>);
+  }
+}

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { AskUserWorkflow } from '@loopstack/hitl';
+
+const AnswerSchema = z.object({ answer: z.string() });
+
+const ENV_OPTIONS = ['staging', 'production'];
+
+@Workflow({
+  title: 'HITL - Ask User Options Example',
+  description:
+    'Shortcut HITL: delegate a generic "pick from a list" ask to AskUserWorkflow with mode "options". ' +
+    'allowCustomAnswer adds a free-text field next to the choices.',
+})
+export class AskUserOptionsExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly askUserWorkflow: AskUserWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_choice' })
+  async askEnvironment(_state: Record<string, unknown>) {
+    await this.askUserWorkflow.run(
+      {
+        question: 'Which environment should we deploy to?',
+        mode: 'options',
+        options: ENV_OPTIONS,
+        allowCustomAnswer: true,
+      },
+      { callback: { transition: 'choiceReceived' }, show: 'inline', label: 'Waiting for choice...' },
+    );
+  }
+
+  @Transition({
+    from: 'waiting_for_choice',
+    to: 'end',
+    wait: true,
+    schema: AnswerSchema,
+  })
+  async choiceReceived(state: Record<string, unknown>, input: TransitionInput<{ answer: string }>) {
+    const choice = input.data.answer;
+    const isCustom = !ENV_OPTIONS.includes(choice);
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: isCustom ? `Custom environment selected: ${choice}` : `Deploying to ${choice}.`,
+    });
+    this.setResult({ environment: choice, custom: isCustom } as unknown as Record<string, unknown>);
+  }
+}

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

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { AskUserWorkflow } from '@loopstack/hitl';
+
+const AnswerSchema = z.object({ answer: z.string() });
+
+@Workflow({
+  title: 'HITL - Ask User Text Example',
+  description:
+    'Shortcut HITL: delegate a generic free-text ask to AskUserWorkflow. The parent only owns the ' +
+    'callback transition. Use the inline-form pattern instead when you need a structured form.',
+})
+export class AskUserTextExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly askUserWorkflow: AskUserWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_answer' })
+  async askName(_state: Record<string, unknown>) {
+    await this.askUserWorkflow.run(
+      { question: 'What is your name?' },
+      { callback: { transition: 'answerReceived' }, show: 'inline', label: 'Waiting for answer...' },
+    );
+  }
+
+  @Transition({
+    from: 'waiting_for_answer',
+    to: 'end',
+    wait: true,
+    schema: AnswerSchema,
+  })
+  async answerReceived(state: Record<string, unknown>, input: TransitionInput<{ answer: string }>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Hello, ${input.data.answer}!`,
+    });
+    this.setResult({ name: input.data.answer } as unknown as Record<string, unknown>);
+  }
+}

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

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, type TransitionInput, Workflow } from '@loopstack/common';
+import { ConfirmUserWorkflow } from '@loopstack/hitl';
+
+const ConfirmSchema = z.object({ confirmed: z.boolean(), markdown: z.string() });
+type ConfirmData = z.infer<typeof ConfirmSchema>;
+
+const DEPLOY_SUMMARY = `## Ready to deploy?
+
+We're about to deploy **v1.2.3** to production.
+
+- 3 commits since last release
+- Smoke tests passing
+
+Proceed?`;
+
+@Workflow({
+  title: 'HITL - Confirm Content Example',
+  description:
+    'Shortcut HITL: hand a pre-rendered markdown blob to ConfirmUserWorkflow for a user-facing review/confirm. ' +
+    'Useful for showing a release plan, a summary, or a code-diff for explicit approval.',
+})
+export class ConfirmContentExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly confirmUserWorkflow: ConfirmUserWorkflow) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_confirmation' })
+  async showSummary(_state: Record<string, unknown>) {
+    await this.confirmUserWorkflow.run(
+      { markdown: DEPLOY_SUMMARY },
+      { callback: { transition: 'decisionReceived' }, show: 'inline', label: 'Waiting for confirmation...' },
+    );
+  }
+
+  @Transition({
+    from: 'waiting_for_confirmation',
+    to: 'end',
+    wait: true,
+    schema: ConfirmSchema,
+  })
+  async decisionReceived(state: Record<string, unknown>, input: TransitionInput<ConfirmData>) {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: input.data.confirmed ? 'User confirmed — proceeding with deploy.' : 'User denied — aborting deploy.',
+    });
+    this.setResult({ confirmed: input.data.confirmed } as unknown as Record<string, unknown>);
+  }
+}

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

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

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

@@ -0,0 +1,13 @@
+widget: form
+options:
+  properties:
+    rating:
+      title: Rating (1–5)
+      widget: number
+    comment:
+      title: Comment
+      widget: textarea
+  actions:
+    - type: button
+      transition: submitFeedback
+      label: Submit Feedback

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { TransitionInput } from '@loopstack/common';
+import { FeedbackFormDocument, FeedbackFormDocumentSchema } from './feedback-form-document.js';
+
+type FeedbackPayload = z.infer<typeof FeedbackFormDocumentSchema>;
+
+@Workflow({
+  title: 'HITL - Inline Form Example',
+  description:
+    'Predefined-workflow HITL: the workflow owns a custom Document with a form widget. ' +
+    'The form button triggers a wait:true transition on the same workflow with the form payload as its schema.',
+})
+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' });
+  }
+
+  @Transition({
+    from: 'waiting_for_feedback',
+    to: 'end',
+    wait: true,
+    schema: FeedbackFormDocumentSchema,
+  })
+  async submitFeedback(state: Record<string, unknown>, input: TransitionInput<FeedbackPayload>) {
+    const payload = input.data;
+    await this.documentStore.save(FeedbackFormDocument, payload, { key: 'feedback' });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Thanks for your feedback! Rating: ${payload.rating}/5. Comment: ${payload.comment}`,
+    });
+
+    this.setResult({ feedback: payload } as unknown as Record<string, unknown>);
+  }
+}

package/src/workflows/meeting-notes/documents/meeting-notes-document.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { Document } from '@loopstack/common';
+
+export const MeetingNotesDocumentSchema = z.object({
+  text: z.string(),
+});
+
+@Document({
+  schema: MeetingNotesDocumentSchema,
+  widget: './meeting-notes-document.yaml',
+})
+export class MeetingNotesDocument {
+  text: string;
+}

package/src/workflows/meeting-notes/documents/meeting-notes-document.yaml

@@ -0,0 +1,10 @@
+widget: form
+options:
+  properties:
+    text:
+      title: Text
+      widget: textarea
+  actions:
+    - type: button
+      transition: userResponse
+      label: 'Optimize Notes'

package/src/workflows/meeting-notes/documents/optimized-notes-document.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { Document } from '@loopstack/common';
+
+export const OptimizedMeetingNotesDocumentSchema = z.object({
+  date: z.string(),
+  summary: z.string(),
+  participants: z.array(z.string()),
+  decisions: z.array(z.string()),
+  actionItems: z.array(z.string()),
+});
+
+@Document({
+  schema: OptimizedMeetingNotesDocumentSchema,
+  widget: './optimized-notes-document.yaml',
+})
+export class OptimizedNotesDocument {
+  date: string;
+  summary: string;
+  participants: string[];
+  decisions: string[];
+  actionItems: string[];
+}

package/src/workflows/meeting-notes/documents/optimized-notes-document.yaml

@@ -0,0 +1,33 @@
+widget: form
+options:
+  order:
+    - date
+    - summary
+    - participants
+    - decisions
+    - actionItems
+  properties:
+    date:
+      title: Date
+    summary:
+      title: Summary
+      widget: textarea
+    participants:
+      title: Participants
+      collapsed: true
+      items:
+        title: Participant
+    decisions:
+      title: Decisions
+      collapsed: true
+      items:
+        title: Decision
+    actionItems:
+      title: Action Items
+      collapsed: true
+      items:
+        title: Action Item
+  actions:
+    - type: button
+      transition: confirm
+      label: 'Confirm'