API: @loopstack/hitl

Classes

AskClarificationTool

Tool that asks the user a clarification question and waits for their answer.

Runs the AskUserWorkflow as an inline sub-workflow in text, options, or confirm mode, pausing the agent loop until the user responds. Returns an AskClarificationResult.


import { AskClarificationTool } from '@loopstack/hitl';

Provided by: HitlModule


export class AskClarificationTool extends BaseTool<AskClarificationInput, object, AskClarificationResult> {
    constructor(askUserWorkflow: AskUserWorkflow);
    protected handle(args: AskClarificationInput, ctx: RunContext, options?: ToolCallOptions): Promise<ToolEnvelope<AskClarificationResult>>;
    complete(result: Record<string, unknown>): Promise<ToolEnvelope<AskClarificationResult>>;
}

AskForApprovalTool

Tool that presents a concept to the user for approval and waits for their decision.

Runs the ConfirmUserWorkflow as an inline sub-workflow, rendering the concept markdown with a confirm button and pausing the agent loop until the user approves or denies. Returns an AskForApprovalResult.


import { AskForApprovalTool } from '@loopstack/hitl';

Provided by: HitlModule


export class AskForApprovalTool extends BaseTool<AskForApprovalInput, object, AskForApprovalResult> {
    constructor(confirmUserWorkflow: ConfirmUserWorkflow);
    protected handle(args: AskForApprovalInput, ctx: RunContext, options?: ToolCallOptions): Promise<ToolEnvelope<AskForApprovalResult>>;
    complete(result: Record<string, unknown>): Promise<ToolEnvelope<AskForApprovalResult>>;
}

AskUserConfirmDocument

Document that presents a yes/no question to the user and captures their answer.


import { AskUserConfirmDocument } from '@loopstack/hitl';


export class AskUserConfirmDocument {
    question: string;
    answer?: string;
}

AskUserDocument

Document that presents a free-text question to the user and captures their answer.


import { AskUserDocument } from '@loopstack/hitl';


export class AskUserDocument {
    question: string;
    answer?: string;
}

AskUserOptionsDocument

Document that presents a question with a list of options for the user to pick from, optionally allowing a custom answer.


import { AskUserOptionsDocument } from '@loopstack/hitl';


export class AskUserOptionsDocument {
    question: string;
    options: string[];
    allowCustomAnswer?: boolean;
    answer?: string;
}

AskUserWorkflow

Workflow that presents a question to the user and waits for their answer.

Takes a question plus an optional mode of text (free-text, the default), options (pick from the supplied options, optionally allowing a custom answer), or confirm (yes/no). Renders the matching document, blocks on the user’s input, and publishes the result as { answer }.


import { AskUserWorkflow } from '@loopstack/hitl';

Provided by: HitlModule


export class AskUserWorkflow extends BaseWorkflow<AskUserArgs> {
    start(state: AskUserState, ctx: RunContext<AskUserArgs>): void;
    showQuestionOptions(state: AskUserState): Promise<void>;
    showQuestionConfirm(state: AskUserState): Promise<void>;
    showQuestionText(state: AskUserState): Promise<void>;
    userAnswered(state: AskUserState, input: TransitionInput<{
        answer: string;
    }>): Promise<void>;
}

ConfirmUserDocument

Document that presents markdown content to the user for an approve/deny decision.


import { ConfirmUserDocument } from '@loopstack/hitl';


export class ConfirmUserDocument {
    markdown: string;
}

ConfirmUserWorkflow

Workflow that presents markdown content to the user and waits for an approve/deny decision.

Renders the markdown argument as a confirmation document, then blocks until the user responds. Publishes the result as { confirmed, markdown }, where confirmed is true when approved and false when denied.


import { ConfirmUserWorkflow } from '@loopstack/hitl';

Provided by: HitlModule


export class ConfirmUserWorkflow extends BaseWorkflow<ConfirmUserArgs> {
    showContent(state: ConfirmUserState, ctx: RunContext<ConfirmUserArgs>): Promise<void>;
    userConfirmed(state: ConfirmUserState): void;
    userDenied(state: ConfirmUserState): void;
}

HitlModule

NestJS module that provides human-in-the-loop workflows and tools — the AskUserWorkflow and ConfirmUserWorkflow sub-workflows plus the AskClarificationTool and AskForApprovalTool — letting agents pause to gather user input or approval.

Registration:

HitlModule (bare import) — registers and exports the workflows and tools. There is no forRoot / forFeature; a plain import is all that is needed.

Requires: nothing beyond importing the module.


import { HitlModule } from '@loopstack/hitl';


export class HitlModule {
}

Type Aliases

AskUserArgs

Args for AskUserWorkflow (passed to run()).

Holds question, optional mode, options, and allowCustomAnswer.


import { AskUserArgs } from '@loopstack/hitl';


export type AskUserArgs = z.infer<typeof AskUserArgsSchema>;

ConfirmUserArgs

Args for ConfirmUserWorkflow (passed to run()).

Holds the markdown content presented for approval.


import { ConfirmUserArgs } from '@loopstack/hitl';


export type ConfirmUserArgs = z.infer<typeof ConfirmUserArgsSchema>;

Variables

AskUserAnswerSchema

Zod schema for the answer AskUserWorkflow waits on (the user’s reply).


import { AskUserAnswerSchema } from '@loopstack/hitl';


AskUserAnswerSchema: z.ZodObject<{
    answer: z.ZodString;
}, z.core.$strip>

AskUserArgsSchema

Zod schema for AskUserWorkflow args (what callers pass to run()).


import { AskUserArgsSchema } from '@loopstack/hitl';


AskUserArgsSchema: z.ZodObject<{
    question: z.ZodString;
    mode: z.ZodOptional<z.ZodEnum<{
        options: "options";
        text: "text";
        confirm: "confirm";
    }>>;
    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
    allowCustomAnswer: z.ZodOptional<z.ZodBoolean>;
}, z.core.$strip>

ConfirmUserArgsSchema

Zod schema for ConfirmUserWorkflow args (what callers pass to run()).


import { ConfirmUserArgsSchema } from '@loopstack/hitl';


ConfirmUserArgsSchema: z.ZodObject<{
    markdown: z.ZodString;
}, z.core.$strip>