handoff

Instructions

Implementation Reference

• src/index.ts:326-339 (handler)

  The handoff tool handler function. Writes a pause message to stderr asking the human to complete a step manually (e.g., 2FA, payment), then returns a paused state with an instruction for the agent to wait and call screenshot() after the human signals completion.

  async function handoff(args: { reason: string }) {
    // Surface to stderr so it's visible in the terminal where the user can react.
    process.stderr.write(
      `\n[helm] ⏸ HANDOFF: ${args.reason}\n` +
      `Complete this in your browser, then ask Claude to continue.\n\n`
    );
    return {
      paused: true,
      reason: args.reason,
      instruction:
        'The agent is paused. The human will complete this step manually in the browser. ' +
        'After they say to continue, call screenshot() to verify the new state.',
    };
  }

• src/index.ts:435-445 (schema)

  Input schema / tool definition for 'handoff'. Declares a string 'reason' (required) field that describes why the handoff is needed.

  {
    name: 'handoff',
    description:
      'Pause and ask the human to complete the next step manually (2FA, payment, sensitive ' +
      'config). Returns a paused state — the human resolves it in the browser, then tells Claude to continue.',
    inputSchema: {
      type: 'object',
      properties: { reason: { type: 'string' } },
      required: ['reason'],
    },
  },

• src/index.ts:455-472 (registration)

  Dispatch/call-site registration. The CallToolRequestSchema handler uses a switch statement on the tool name; 'handoff' case calls handoff() with the { reason } argument extracted from the request.

  server.setRequestHandler(CallToolRequestSchema, async (req) => {
    const name = req.params.name;
    const args = (req.params.arguments ?? {}) as Record<string, unknown>;
    try {
      let result: unknown;
      switch (name) {
        case 'attach':       result = await attach(args as { port?: number }); break;
        case 'list_tabs':    result = await listTabs(); break;
        case 'focus_tab':    result = await focusTab(args as { index?: number; urlContains?: string }); break;
        case 'screenshot':   result = await screenshot(args as { fullPage?: boolean }); break;
        case 'inspect':      result = await inspect(); break;
        case 'click':        result = await click(args as { id?: number; text?: string; selector?: string }); break;
        case 'type':         result = await type(args as { text: string; id?: number; selector?: string; submit?: boolean }); break;
        case 'navigate':     result = await navigate(args as { url: string }); break;
        case 'wait_for':     result = await waitFor(args as { text?: string; selector?: string; timeoutMs?: number }); break;
        case 'handoff':      result = await handoff(args as { reason: string }); break;
        default:             throw new Error(`Unknown tool: ${name}`);
      }

• src/index.ts:29-36 (helper)

  Handoff pattern triggers — a list of regex patterns and human-readable labels for prompts (2FA, CAPTCHA, payment, login, etc.) that when detected in page text, auto-suggest a handoff via the handoffTriggers field returned by screenshot().

  // Patterns that should auto-trigger a handoff suggestion when seen on screen.
  // Keep these tight — false positives would be more annoying than helpful.
  const HANDOFF_PATTERNS: Array<[RegExp, string]> = [
    [/2-?step verification/i, '2FA prompt'],
    [/verify it'?s you/i, 'identity verification'],
    [/enter (the )?(verification |security )?code/i, 'verification code'],
    [/recaptcha|i'?m not a robot/i, 'CAPTCHA'],
    [/cvv|cvc|security code/i, 'payment confirmation'],

• src/index.ts:141-147 (helper)

  detectHandoffTriggers helper function — scans a text string against HANDOFF_PATTERNS and returns a list of matching trigger labels. Used by the screenshot tool to surface handoff-relevant prompts to the AI.

  function detectHandoffTriggers(text: string): string[] {
    const found = new Set<string>();
    for (const [rx, label] of HANDOFF_PATTERNS) {
      if (rx.test(text)) found.add(label);
    }
    return [...found];
  }