Human-in-the-loop workflow orchestrator for TypeScript — chain steps, pause on approval gates, then continue when a human approves or rejects. Includes in-memory, SQLite (sql.js, file-backed), and PostgreSQL stores; optional Slack / HTTP webhook notifications; a small REST API; a CLI; and Vitest helpers.

• Node.js 20+ (ESM; global fetch in supported Node versions)
• Optional: Docker (see docker-compose.yml) for PostgreSQL

cd hitl-agent-ts
npm install
npm run build

npm run build produces dist/, which is required for npm start, npm run start:api, and for imports that resolve to dist/ (including the hitl-agent-ts/hitl export in package.json).

Copy .env.example to .env when running the API with Slack or Postgres (see comments inside).

Use generics on HITLWorkflow<InputType, OutputType> so ctx.input is typed in steps:

import { HITLWorkflow, approval, MemoryStore } from './hitl/index.js';

type In = { userId: string };
type Out = { status: string };

const store = new MemoryStore();

const wf = new HITLWorkflow<In, Out>({
  name: 'delete-user',
  store,
})
  .step('find-user', async (ctx) => ({
    user: { id: ctx.input.userId, name: 'Ada' },
  }))
  .step(
    'request-approval',
    approval({
      title: 'Delete user?',
      description: (c) =>
        `User ${(c.prevStep as { user: { name: string } }).user.name} will be deleted.`,
      requiredApprovers: 1,
    })
  )
  .step('execute', async (ctx) =>
    ctx.approval?.decision === 'reject'
      ? { status: 'cancelled' }
      : { status: 'deleted' }
  );

Orchestrator is exported as an alias for HITLWorkflow if you prefer that name.

import { startWorkflow, approveStep } from './hitl/index.js';

const run = await startWorkflow(wf, {
  input: { userId: 'user-123' },
  workflowId: 'delete-request-456',
});

console.log(run.status, run.currentStep); // paused at approval

await approveStep('delete-request-456', {
  stepId: 'request-approval',
  decision: 'approve',
  approvedBy: 'admin-1',
});

const result = await run.waitForCompletion();
console.log(result);

Same process: approveStep finds the active run in the same Node.js process that called startWorkflow. If the process restarts, load the same logical definition from code, then call await wf.resume(workflowId) to re-attach completion handling, then approve.

src/api/server.ts provides:

With DATABASE_URL set, the server uses PostgresStore; otherwise MemoryStore.

npm run dev:api
# http://127.0.0.1:3000

npm run cli

Example: start user-123, then approve <workflowId> request-approval approve OK (the bundled CLI uses the request-approval step from examples/delete-user.ts).

npm run dev

Runs src/index.ts (sample delete-user workflow, pauses at approval).

prepublishOnly runs npm run build automatically before npm publish so dist/ is always fresh.

From the repo root: npm test and npm run lint before pushing. Scripts dev, dev:api, and cli run TypeScript via tsx and do not require dist/. You need npm run build for npm start / npm run start:api, for anything that imports from dist/, and before publishing. The default main entry is the demo (src/index.ts → dist/index.js); library code lives under src/hitl/ and is exposed as hitl-agent-ts/hitl after build.

docker compose up --build

Builds the API image (Dockerfile) and starts PostgreSQL. The API process must still share the same workflow definitions and active runs as your worker if you use approveStep in-process; see “Same process” above.

hitl-agent-ts/
├── src/
│   ├── hitl/
│   │   ├── index.ts          # public API barrel
│   │   ├── HITLWorkflow.ts   # workflow builder + execution
│   │   ├── runtime.ts        # startWorkflow, approveStep, getPendingApprovals
│   │   ├── approval.ts
│   │   ├── config.ts
│   │   ├── types.ts
│   │   ├── store/            # memory, sqlite, postgres
│   │   ├── notifiers/
│   │   └── testing.ts        # TestOrchestrator
│   ├── examples/delete-user.ts
│   ├── api/server.ts
│   ├── cli/index.ts
│   └── index.ts
├── tests/
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── LICENSE
└── README.md

MIT — see LICENSE.