resonate-human-in-the-loop-pattern-typescript

Resonate Human-in-the-Loop Pattern (TypeScript)

SDK version: This skill reflects @resonatehq/sdk v0.11.4 (current on npm).

Overview

The Human-in-the-Loop (HITL) pattern enables workflows to pause execution and wait for human input—decisions, approvals, reviews, or interventions. The workflow suspends (not blocks resources) and resumes exactly where it left off when the human responds, whether that's seconds, hours, or days later.

Core mechanism: Create a durable promise, read the ID the SDK generates for it, communicate that ID to a human (via email, UI, webhook), and yield* await the promise until it's externally resolved.

Mental Model

Workflow                          Human
   │                                │
   ├─ Create promise, read its ID  │
   ├─ Send email with links        │
   │  (accept_link, reject_link)   │
   │                                │
   ├─ yield* promise               │
   │  [SUSPENDED - not consuming    │
   │   resources, durable state]    │
   │                                │
   │                                ├─ Click "Approve"
   │                                ├─ HTTP POST resolves promise
   │  [RESUMES from checkpoint]    │
   │                                │
   ├─ Process approval decision
   └─ Complete workflow

Core Pattern

Step 1: Create the Durable Promise

function* approvalWorkflow(ctx: Context, orderId: string) {
  // ctx.promise() generates the ID itself — you don't choose one
  const approvalPromise = yield* ctx.promise<Decision>({
    timeout: 24 * 60 * 60 * 1000  // 24 hours
  });

  // Continue...
}

Why read the ID back? The human (or webhook) needs to know which promise to resolve, and the SDK's auto-generated ID is the only ID there is. It's deterministic across replay — the sequence advances in call order — so approvalPromise.id is safe to hand to anything outside the workflow.

Step 2: Communicate Promise ID

function* approvalWorkflow(ctx: Context, orderId: string) {
  const approvalPromise = yield* ctx.promise<Decision>();

  // Send email with accept/reject links containing promise ID
  yield* ctx.run(sendApprovalEmail, orderId, approvalPromise.id);

  // Continue...
}

async function sendApprovalEmail(_ctx: Context, orderId: string, promiseId: string) {
  const acceptLink = `https://example.com/approve/${promiseId}?action=accept`;
  const rejectLink = `https://example.com/approve/${promiseId}?action=reject`;

  await emailService.send({
    to: "[email protected]",
    subject: `Approval needed for order ${orderId}`,
    body: `Accept: ${acceptLink}\nReject: ${rejectLink}`
  });
}