@loopstack/hitl 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,110 @@
+# @loopstack/hitl
+
+> A module for the [Loopstack AI](https://loopstack.ai) automation framework.
+
+Human-in-the-loop (HITL) building blocks for Loopstack workflows. Pause a running workflow, ask the user a question, and resume once they answer.
+
+## Overview
+
+Most non-trivial workflows need a human decision at some point — "is this the right file?", "do you want to proceed?", "pick one of these options". This module provides two ready-to-use workflows that handle the wait-for-user pattern, along with the document types that render the prompts in the UI.
+
+By using this module you'll get:
+
+- **`AskUserWorkflow`** — asks a free-text question, a yes/no confirmation, or a multiple-choice question (mode is a runtime arg)
+- **`ConfirmUserWorkflow`** — shows markdown content and waits for a confirm / deny response
+- **4 document types** that render the prompts: `AskUserDocument`, `AskUserConfirmDocument`, `AskUserOptionsDocument`, `ConfirmUserDocument`
+
+## Installation
+
+```sh
+npm install @loopstack/hitl
+```
+
+Register the module:
+
+```ts
+import { HitlModule } from '@loopstack/hitl';
+
+@Module({
+  imports: [HitlModule /* ... */],
+})
+export class AppModule {}
+```
+
+## How It Works
+
+### Asking a text question as a sub-workflow
+
+Use `@InjectWorkflow()` to launch `AskUserWorkflow` from a parent workflow. The call resolves with the user's answer once they respond in the UI:
+
+```ts
+import { BaseWorkflow, InjectWorkflow, Transition, Workflow } from '@loopstack/common';
+import { AskUserWorkflow } from '@loopstack/hitl';
+
+@Workflow({ uiConfig: __dirname + '/my.ui.yaml' })
+export class MyWorkflow extends BaseWorkflow {
+  @InjectWorkflow() askUser: AskUserWorkflow;
+
+  @Transition({ from: 'ready', to: 'done' })
+  async collectName() {
+    const { answer } = await this.askUser.run({ question: 'What is your name?' }, { alias: 'askName' });
+    // use `answer`
+  }
+}
+```
+
+### Multiple-choice and confirmation modes
+
+`AskUserWorkflow` takes an optional `mode`:
+
+```ts
+await this.askUser.run({
+  question: 'Which environment?',
+  mode: 'options',
+  options: ['staging', 'production'],
+  allowCustomAnswer: false,
+});
+
+await this.askUser.run({
+  question: 'Proceed with deletion?',
+  mode: 'confirm',
+});
+```
+
+### Showing long-form content for confirmation
+
+`ConfirmUserWorkflow` is for "review and confirm" flows where you want to render markdown (e.g. a summary) and get a confirm / deny response:
+
+```ts
+import { ConfirmUserWorkflow } from '@loopstack/hitl';
+
+const { confirmed } = await this.confirmUser.run({
+  markdown: '## About to commit\n\n- 3 files changed',
+});
+```
+
+### Documents
+
+Each workflow saves one of the document types on the workflow repository — the Studio UI picks up those documents and renders the corresponding input widget. You generally don't need to interact with the document classes directly, but they're exported if you want to query or post-process answers.
+
+## Public API
+
+- **Module:** `HitlModule`
+- **Workflows:** `AskUserWorkflow`, `ConfirmUserWorkflow`
+- **Documents:** `AskUserDocument`, `AskUserConfirmDocument`, `AskUserOptionsDocument`, `ConfirmUserDocument`
+
+## Dependencies
+
+- `@loopstack/common` — `BaseWorkflow`, decorators
+- `@loopstack/core` — `LoopCoreModule`
+
+## About
+
+Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
+
+License: MIT
+
+### Additional Resources
+
+- [Loopstack Documentation](https://loopstack.ai/docs)
+- Find more Loopstack modules in the [Loopstack Registry](https://loopstack.ai/registry)

package/package.json

@@ -9,7 +9,7 @@
     "workflow",
     "user-input"
   ],
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "author": {
     "name": "Jakob Klippel",
@@ -18,8 +18,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./src/*": "./src/*"
+    ".": "./dist/index.js"
   },
   "scripts": {
     "build": "nest build",
@@ -30,14 +29,13 @@
     "watch": "nest build --watch"
   },
   "dependencies": {
-    "@loopstack/common": "^0.27.0",
-    "@loopstack/core": "^0.27.0",
+    "@loopstack/common": "^0.28.0",
+    "@loopstack/core": "^0.28.0",
     "@nestjs/common": "^11.1.19",
     "zod": "^4.3.6"
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "jest": {
     "moduleFileExtensions": [
@@ -65,7 +63,6 @@
       }
     ],
     "installModes": [
-      "add",
       "install"
     ]
   }

package/src/documents/ask-user-confirm-document.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { Document } from '@loopstack/common';
-
-export const AskUserConfirmDocumentSchema = z
-  .object({
-    question: z.string(),
-    answer: z.string().optional(),
-  })
-  .strict();
-
-export type AskUserConfirmDocumentType = z.infer<typeof AskUserConfirmDocumentSchema>;
-
-@Document({
-  uiConfig: __dirname + '/ask-user-confirm-document.yaml',
-  schema: AskUserConfirmDocumentSchema,
-})
-export class AskUserConfirmDocument {
-  question: string;
-  answer?: string;
-}

package/src/documents/ask-user-confirm-document.yaml

@@ -1,6 +0,0 @@
-type: document
-ui:
-  widgets:
-    - widget: confirm-prompt
-      options:
-        transition: userAnswered

package/src/documents/ask-user-document.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { Document } from '@loopstack/common';
-
-export const AskUserDocumentSchema = z
-  .object({
-    question: z.string(),
-    answer: z.string().optional(),
-  })
-  .strict();
-
-export type AskUserDocumentType = z.infer<typeof AskUserDocumentSchema>;
-
-@Document({
-  uiConfig: __dirname + '/ask-user-document.yaml',
-  schema: AskUserDocumentSchema,
-})
-export class AskUserDocument {
-  question: string;
-  answer?: string;
-}

package/src/documents/ask-user-document.yaml

@@ -1,6 +0,0 @@
-type: document
-ui:
-  widgets:
-    - widget: text-prompt
-      options:
-        transition: userAnswered

package/src/documents/ask-user-options-document.ts

@@ -1,24 +0,0 @@
-import { z } from 'zod';
-import { Document } from '@loopstack/common';
-
-export const AskUserOptionsDocumentSchema = z
-  .object({
-    question: z.string(),
-    options: z.array(z.string()),
-    allowCustomAnswer: z.boolean().optional(),
-    answer: z.string().optional(),
-  })
-  .strict();
-
-export type AskUserOptionsDocumentType = z.infer<typeof AskUserOptionsDocumentSchema>;
-
-@Document({
-  uiConfig: __dirname + '/ask-user-options-document.yaml',
-  schema: AskUserOptionsDocumentSchema,
-})
-export class AskUserOptionsDocument {
-  question: string;
-  options: string[];
-  allowCustomAnswer?: boolean;
-  answer?: string;
-}

package/src/documents/ask-user-options-document.yaml

@@ -1,6 +0,0 @@
-type: document
-ui:
-  widgets:
-    - widget: choices
-      options:
-        transition: userAnswered

package/src/documents/confirm-user-document.ts

@@ -1,18 +0,0 @@
-import { z } from 'zod';
-import { Document } from '@loopstack/common';
-
-export const ConfirmUserDocumentSchema = z
-  .object({
-    markdown: z.string(),
-  })
-  .strict();
-
-export type ConfirmUserDocumentType = z.infer<typeof ConfirmUserDocumentSchema>;
-
-@Document({
-  uiConfig: __dirname + '/confirm-user-document.yaml',
-  schema: ConfirmUserDocumentSchema,
-})
-export class ConfirmUserDocument {
-  markdown: string;
-}

package/src/documents/confirm-user-document.yaml

@@ -1,16 +0,0 @@
-type: document
-ui:
-  widgets:
-    - widget: form
-      options:
-        properties:
-          markdown:
-            widget: markdown-view
-        actions:
-          - type: button
-            transition: userDenied
-            label: 'Deny'
-            variant: outline
-          - type: button
-            transition: userConfirmed
-            label: 'Confirm'

package/src/documents/index.ts

@@ -1,12 +0,0 @@
-export { AskUserDocument, AskUserDocumentSchema, AskUserDocumentType } from './ask-user-document';
-export {
-  AskUserConfirmDocument,
-  AskUserConfirmDocumentSchema,
-  AskUserConfirmDocumentType,
-} from './ask-user-confirm-document';
-export {
-  AskUserOptionsDocument,
-  AskUserOptionsDocumentSchema,
-  AskUserOptionsDocumentType,
-} from './ask-user-options-document';
-export { ConfirmUserDocument, ConfirmUserDocumentSchema, ConfirmUserDocumentType } from './confirm-user-document';

package/src/hitl.module.ts

@@ -1,11 +0,0 @@
-import { Module } from '@nestjs/common';
-import { LoopCoreModule } from '@loopstack/core';
-import { AskUserWorkflow } from './workflows/ask-user/ask-user.workflow';
-import { ConfirmUserWorkflow } from './workflows/confirm-user/confirm-user.workflow';
-
-@Module({
-  imports: [LoopCoreModule],
-  providers: [AskUserWorkflow, ConfirmUserWorkflow],
-  exports: [AskUserWorkflow, ConfirmUserWorkflow],
-})
-export class HitlModule {}

package/src/index.ts

@@ -1,3 +0,0 @@
-export * from './documents';
-export * from './workflows';
-export * from './hitl.module';

package/src/workflows/ask-user/ask-user.ui.yaml

@@ -1,6 +0,0 @@
-title: 'Ask User'
-
-description: |
-  Generic sub-workflow that presents a question to the user and waits for their answer.
-  Used by async tool calls (e.g. askClarification) to interrupt an agent loop for user input.
-  Supports three modes: text (default), options (pick from a list), and confirm (yes/no).

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

@@ -1,83 +0,0 @@
-import { z } from 'zod';
-import { BaseWorkflow, Final, Guard, Initial, Transition, Workflow } from '@loopstack/common';
-import { AskUserConfirmDocument } from '../../documents/ask-user-confirm-document';
-import { AskUserDocument } from '../../documents/ask-user-document';
-import { AskUserOptionsDocument } from '../../documents/ask-user-options-document';
-
-const AskUserAnswerSchema = z.object({
-  answer: z.string(),
-});
-
-@Workflow({
-  uiConfig: __dirname + '/ask-user.ui.yaml',
-  schema: z.object({
-    question: z.string(),
-    mode: z.enum(['text', 'options', 'confirm']).optional(),
-    options: z.array(z.string()).optional(),
-    allowCustomAnswer: z.boolean().optional(),
-  }),
-})
-export class AskUserWorkflow extends BaseWorkflow {
-  @Initial({ to: 'show_question' })
-  start() {}
-
-  @Transition({ from: 'show_question', to: 'waiting_for_user', priority: 10 })
-  @Guard('isOptionsMode')
-  async showQuestionOptions() {
-    const { question, options, allowCustomAnswer } = this.ctx.args as {
-      question: string;
-      options?: string[];
-      allowCustomAnswer?: boolean;
-    };
-    await this.repository.save(
-      AskUserOptionsDocument,
-      { question, options: options ?? [], allowCustomAnswer },
-      { id: 'question' },
-    );
-  }
-
-  @Transition({ from: 'show_question', to: 'waiting_for_user', priority: 10 })
-  @Guard('isConfirmMode')
-  async showQuestionConfirm() {
-    const { question } = this.ctx.args as { question: string };
-    await this.repository.save(AskUserConfirmDocument, { question }, { id: 'question' });
-  }
-
-  @Transition({ from: 'show_question', to: 'waiting_for_user' })
-  async showQuestionText() {
-    const { question } = this.ctx.args as { question: string };
-    await this.repository.save(AskUserDocument, { question }, { id: 'question' });
-  }
-
-  @Final({ from: 'waiting_for_user', wait: true, schema: AskUserAnswerSchema })
-  async userAnswered(payload: { answer: string }): Promise<{ answer: string }> {
-    const { question, mode, options, allowCustomAnswer } = this.ctx.args as {
-      question: string;
-      mode?: string;
-      options?: string[];
-      allowCustomAnswer?: boolean;
-    };
-
-    if (mode === 'options') {
-      await this.repository.save(
-        AskUserOptionsDocument,
-        { question, options: options ?? [], allowCustomAnswer, answer: payload.answer },
-        { id: 'question' },
-      );
-    } else if (mode === 'confirm') {
-      await this.repository.save(AskUserConfirmDocument, { question, answer: payload.answer }, { id: 'question' });
-    } else {
-      await this.repository.save(AskUserDocument, { question, answer: payload.answer }, { id: 'question' });
-    }
-
-    return { answer: payload.answer };
-  }
-
-  private isOptionsMode(): boolean {
-    return (this.ctx.args as { mode?: string })?.mode === 'options';
-  }
-
-  private isConfirmMode(): boolean {
-    return (this.ctx.args as { mode?: string })?.mode === 'confirm';
-  }
-}

package/src/workflows/confirm-user/confirm-user.ui.yaml

@@ -1,5 +0,0 @@
-title: 'Confirm User'
-
-description: |
-  Generic sub-workflow that presents markdown content to the user and waits for confirmation.
-  Used by async tool calls (e.g. askForApproval) to get explicit user confirmation.

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

@@ -1,29 +0,0 @@
-import { z } from 'zod';
-import { BaseWorkflow, Final, Initial, Workflow } from '@loopstack/common';
-import { ConfirmUserDocument } from '../../documents/confirm-user-document';
-
-@Workflow({
-  uiConfig: __dirname + '/confirm-user.ui.yaml',
-  schema: z.object({
-    markdown: z.string(),
-  }),
-})
-export class ConfirmUserWorkflow extends BaseWorkflow {
-  markdown?: string;
-
-  @Initial({ to: 'waiting_for_confirmation' })
-  async showContent(args: { markdown: string }) {
-    this.markdown = args.markdown;
-    await this.repository.save(ConfirmUserDocument, { markdown: args.markdown }, { id: 'content' });
-  }
-
-  @Final({ from: 'waiting_for_confirmation', wait: true })
-  async userConfirmed(): Promise<{ confirmed: boolean; markdown: string }> {
-    return Promise.resolve({ confirmed: true, markdown: this.markdown! });
-  }
-
-  @Final({ from: 'waiting_for_confirmation', wait: true })
-  async userDenied(): Promise<{ confirmed: boolean; markdown: string }> {
-    return Promise.resolve({ confirmed: false, markdown: this.markdown! });
-  }
-}

package/src/workflows/index.ts

@@ -1,2 +0,0 @@
-export { AskUserWorkflow } from './ask-user/ask-user.workflow';
-export { ConfirmUserWorkflow } from './confirm-user/confirm-user.workflow';