Human-in-the-loop and approval flows

import Anthropic from '@anthropic-ai/sdk';
import { createInterface } from 'node:readline/promises';
import { z } from 'zod';

const client = new Anthropic();
const terminal = createInterface({ input: process.stdin, output: process.stdout });

// Hard limit enforced in code: no prompt, model output or approval can exceed it.
const MAX_REFUND_USD = 200;

const tools: Anthropic.Tool[] = [
  {
    name: 'lookup_order',
    description: 'Look up an order by its ID. Read-only.',
    strict: true,
    input_schema: {
      type: 'object',
      properties: { orderId: { type: 'string' } },
      required: ['orderId'],
      additionalProperties: false,
    },
  },
  {
    name: 'issue_refund',
    description: 'Refund part or all of an order to the original payment method. A human must approve each refund.',
    strict: true,
    input_schema: {
      type: 'object',
      properties: { orderId: { type: 'string' }, amountUsd: { type: 'number' }, reason: { type: 'string' } },
      required: ['orderId', 'amountUsd', 'reason'],
      additionalProperties: false,
    },
  },
];

// Validate every tool input in code, even with strict schemas: never trust its shape.
const LookupInput = z.object({ orderId: z.string().min(1) });
const RefundInput = z.object({ orderId: z.string().min(1), amountUsd: z.number().positive(), reason: z.string().min(1) });

// Stand-ins for your real systems.
async function lookupOrder(orderId: string) {
  return { orderId, totalUsd: 49, status: 'delivered', deliveredDaysAgo: 3 };
}
async function issueRefund(orderId: string, amountUsd: number) {
  return { refundId: `rf_${orderId}`, amountUsd };
}

async function runTool(block: Anthropic.ToolUseBlock): Promise<Anthropic.ToolResultBlockParam> {
  const ok = (content: unknown): Anthropic.ToolResultBlockParam => ({
    type: 'tool_result',
    tool_use_id: block.id,
    content: JSON.stringify(content),
  });
  const fail = (content: string): Anthropic.ToolResultBlockParam => ({
    type: 'tool_result',
    tool_use_id: block.id,
    content,
    is_error: true,
  });

  switch (block.name) {
    case 'lookup_order': {
      const input = LookupInput.safeParse(block.input);
      return input.success ? ok(await lookupOrder(input.data.orderId)) : fail('Invalid input for lookup_order.');
    }
    case 'issue_refund': {
      const input = RefundInput.safeParse(block.input);
      if (!input.success) return fail('Invalid input for issue_refund.');
      const { orderId, amountUsd, reason } = input.data;
      if (amountUsd > MAX_REFUND_USD) {
        return fail(`Refunds above $${MAX_REFUND_USD} need a manager. Tell the customer it has been escalated.`);
      }
      // Show exactly what will happen, then require an explicit yes. Anything else is a no.
      const answer = await terminal.question(
        `\nRefund $${amountUsd.toFixed(2)} for order ${orderId}?\nReason given: ${reason}\nApprove? [y/N] `,
      );
      if (answer.trim().toLowerCase() !== 'y') {
        return fail('A human declined this refund. Do not retry it; explain the outcome to the customer.');
      }
      return ok(await issueRefund(orderId, amountUsd));
    }
    default:
      return fail(`Unknown tool: ${block.name}`);
  }
}

const textOf = (message: Anthropic.Message) =>
  message.content.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join('');

async function handle(customerMessage: string): Promise<void> {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: customerMessage }];

  // A turn limit stops a confused loop from running (and costing) forever.
  for (let turn = 0; turn < 10; turn++) {
    const response = await client.messages.create({
      model: 'claude-opus-5-5',
      max_tokens: 4096,
      output_config: { effort: 'medium' },
      system: 'You are a support agent. Look up orders before acting. Propose refunds only when the policy clearly allows.',
      tools,
      messages,
    });
    messages.push({ role: 'assistant', content: response.content });

    switch (response.stop_reason) {
      case 'end_turn':
      case 'stop_sequence':
        console.log(`\n${textOf(response)}`);
        return;
      case 'tool_use': {
        // Run tools one by one so approvals appear in order, then return all results in one message.
        const results: Anthropic.ToolResultBlockParam[] = [];
        for (const block of response.content) {
          if (block.type === 'tool_use') results.push(await runTool(block));
        }
        messages.push({ role: 'user', content: results });
        break;
      }
      case 'pause_turn':
        // The response is already in the history; sending it back lets the model continue.
        break;
      case 'max_tokens':
      case 'model_context_window_exceeded':
        // Never run a tool call from a cut-off response: its input may be incomplete.
        console.log('\nThe response was cut off before it finished. No action was taken.');
        return;
      case 'refusal':
        console.log('\nThis request was declined. Please handle it manually.');
        return;
      case null:
        console.log(`\nUnexpected stop (${response.stop_reason}). No further action taken.`);
        return;
    }
  }
  console.log('\nStopped after 10 turns without finishing. Escalating to a human.');
}

await handle('Hi, order A1042 arrived damaged. Can I get my money back?');
terminal.close();