testronaut 1.3.4 → 1.3.6

package/core/turnLoop.js

@@ -46,7 +46,7 @@ import {
 import { resolveProviderModel } from '../llm/modelResolver.js';
 import { getLLM } from '../llm/llmFactory.js';
 import { summarizeTurnIntentFromMessage } from './turnIntent.js';
-import { redactArgs } from './redaction.js';
+import { maskPreview, redactArgs } from './redaction.js';
 import { 
   sanitizeHeavyToolHistory, 
   pruneConversationContext,
@@ -132,6 +132,7 @@ const FIRE_AND_FORGET_TOOLS = new Set([
   'click_and_follow_popup',
   'switch_to_page',
   'close_current_page',
+  'request_human_input',
 ]);
 
 /**
@@ -227,7 +228,11 @@ export const turnLoop = async (
   const retryLimitClamped = Math.min(10, Math.max(1, Number.isFinite(retryLimitRaw) ? retryLimitRaw : DEFAULT_TURN_RETRY_LIMIT)); // retries allowed (excludes initial)
   const maxAttempts = retryLimitClamped + 1; // includes initial attempt
   ctx.groundControl = groundControl;
-  let agentMemory = { lastMenuExpanded: false };
+  const humanInput = ctx.humanInput || { enabled: true, timeoutSeconds: 60 };
+  const activeToolsSchema = humanInput.enabled === false
+    ? toolsSchema.filter(t => t?.function?.name !== 'request_human_input')
+    : toolsSchema;
+  let agentMemory = { lastMenuExpanded: false, humanInput };
   ensureDocProgress(agentMemory, resourceGuardCfg);
   let turnRetries = 0;
   let stepSeq = ctx._stepSeq || 0;
@@ -325,7 +330,7 @@ export const turnLoop = async (
       const { message, usage, headers } = await llm.chat({
         model: MODEL_ID,
         messages,
-        tools: toolsSchema,
+        tools: activeToolsSchema,
       });
       response = { message, usage, headers };
 
@@ -412,6 +417,19 @@ export const turnLoop = async (
           hadToolIssues = true;
         }
 
+        if (fnName === 'request_human_input') {
+          step.humanInput = step.humanInput || {};
+          step.humanInput.requested = true;
+          step.humanInput.codeType = args.codeType || 'verification_code';
+          step.humanInput.timeoutSeconds = humanInput.timeoutSeconds;
+          step.humanInput.status = errorMessage
+            ? (String(errorMessage).toLowerCase().includes('timed out') ? 'timeout' : 'invalid')
+            : 'provided';
+          step.events.push(errorMessage
+            ? `👤 Human-in-the-loop input ${step.humanInput.status}: ${errorMessage.replace(/^ERROR:\s*/, '')}`
+            : '👤 Human-in-the-loop input provided.');
+        }
+
         // Capture and log any file upload/download events (for reports)
         try {
           const maybeJson = JSON.parse(result);
@@ -443,7 +461,20 @@ export const turnLoop = async (
         }
 
         console.log(`[tool ] ← ${fnName} result:`, errorMessage ? '❌ Failed' : '✅ Success');
-        const truncated = result.length > 1000 ? result.slice(0, 1000) + '…' : result;
+        let resultForLog = result;
+        if (fnName === 'request_human_input') {
+          try {
+            const parsed = JSON.parse(result);
+            resultForLog = JSON.stringify({
+              ...parsed,
+              value: maskPreview(parsed.value),
+              redactedValue: maskPreview(parsed.value),
+            });
+          } catch {
+            resultForLog = errorMessage || 'Human input received.';
+          }
+        }
+        const truncated = resultForLog.length > 1000 ? resultForLog.slice(0, 1000) + '…' : resultForLog;
         step.events.push(`[tool ] ← ${fnName} result: ${errorMessage ? '❌ Failed' : '✅ Success'}`);
         step.events.push(`[tool ] ← ${truncated}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"
@@ -19,6 +19,10 @@
   "author": "",
   "license": "MIT",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mission-testronaut/testronaut-cli"
+  },
   "dependencies": {
     "@dqbd/tiktoken": "^1.0.21",
     "@google/generative-ai": "^0.24.1",

package/runner/testronaut.js

@@ -27,7 +27,7 @@ import fs from 'fs';
 import path from 'path';
 import { runAgent } from '../core/agent.js';
 import { redactPasswordInText } from '../core/redaction.js';
-import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig } from '../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig, getHumanInputConfig } from '../core/config.js';
 
 // Check process env for debug toggles (shared helper for tests and CLI).
 const isDebugEnabled = () => {
@@ -53,6 +53,7 @@ export async function runMissions({ preMission, mission, postMission }, missionN
   const retryLimit = retryInfo.value;
   const domListLimitInfo = getDomListLimit(cfg);
   const resourceGuard = getResourceGuardConfig(cfg);
+  const humanInput = getHumanInputConfig(cfg);
   const debugEnabled = isDebugEnabled();
   if (notes.length) {
     console.warn(notes.join('\n'));
@@ -66,6 +67,12 @@ export async function runMissions({ preMission, mission, postMission }, missionN
   if (domListLimitInfo?.mode === 'all') {
     console.warn('⚠️ DOM list limit is set to "all". This can dramatically increase token usage and may break flows on heavy pages.');
   }
+  if (humanInput.clamped) {
+    console.warn(`⚠️ Human input timeout clamped to ${humanInput.timeoutSeconds}s (allowed 5-300).`);
+  }
+  if (!humanInput.enabled) {
+    console.log('👤 Human-in-the-loop input tool disabled for this run.');
+  }
   if (debugEnabled) {
     const cfgDomRaw = cfg?.dom?.listItemLimit ?? cfg?.dom?.listLimit ?? cfg?.domListLimit;
     console.log('[debug] Debug mode enabled');
@@ -89,6 +96,12 @@ export async function runMissions({ preMission, mission, postMission }, missionN
       hrefIncludes: resourceGuard.hrefIncludes,
       dataTypes: resourceGuard.dataTypes,
     });
+    console.log('[debug] Human input', {
+      enabled: humanInput.enabled,
+      timeoutSeconds: humanInput.timeoutSeconds,
+      source: humanInput.source,
+      clamped: humanInput.clamped,
+    });
     // Helpful for upload missions: show missions/files contents
     const filesDir = path.resolve(process.cwd(), 'missions/files');
     try {
@@ -188,7 +201,7 @@ export async function runMissions({ preMission, mission, postMission }, missionN
     missionName,
     maxTurns,
     retryLimit,
-    { domListLimit: domListLimitInfo?.value, debug: debugEnabled, resourceGuard }
+    { domListLimit: domListLimitInfo?.value, debug: debugEnabled, resourceGuard, humanInput }
   );
   if (!success) {
     console.log(`❌ Aborting after failed goal.`);

package/tests/binTests/init.test.js

@@ -79,6 +79,8 @@ describe('initializeTestronautProject', () => {
     expect(typeof cfg.maxTurns).toBe('number');
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
+    expect(cfg.humanInput?.enabled).toBe(true);
+    expect(cfg.humanInput?.timeoutSeconds).toBe(60);
 
     // .env
     const envPath = path.join(temp, '.env');
@@ -112,6 +114,8 @@ describe('initializeTestronautProject', () => {
     expect(cfg.model).toBe('gemini-2.5-flash');
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
+    expect(cfg.humanInput?.enabled).toBe(true);
+    expect(cfg.humanInput?.timeoutSeconds).toBe(60);
 
     const envTxt = fs.readFileSync(path.join(temp, '.env'), 'utf8');
     expect(envTxt).toMatch(/GEMINI_API_KEY=AIza/);
@@ -191,5 +195,7 @@ describe('initializeTestronautProject', () => {
     expect(cfg.maxTurns).toBe(20); // default filled in
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
+    expect(cfg.humanInput?.enabled).toBe(true);
+    expect(cfg.humanInput?.timeoutSeconds).toBe(60);
   });
 });

package/tests/binTests/initHelpersTests/defaultConfig.test.js

@@ -11,5 +11,7 @@ describe('defaultConfig', () => {
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
     expect(cfg.resourceGuard?.hrefIncludes).toContain('/document/');
+    expect(cfg.humanInput?.enabled).toBe(true);
+    expect(cfg.humanInput?.timeoutSeconds).toBe(60);
   });
 });

package/tests/coreTests/config.test.js

@@ -13,6 +13,7 @@ import {
   enforceTurnBudget,
   getDomListLimit,
   getResourceGuardConfig,
+  getHumanInputConfig,
 } from '../../core/config.js';
 
 describe('core/config', () => {
@@ -201,6 +202,45 @@ describe('core/config', () => {
     });
   });
 
+  describe('getHumanInputConfig', () => {
+    const OLD_ENV = { ...process.env };
+    beforeEach(() => {
+      process.env = { ...OLD_ENV };
+      delete process.env.TESTRONAUT_HUMAN_INPUT;
+      delete process.env.TESTRONAUT_HUMAN_INPUT_TIMEOUT_SECONDS;
+    });
+    afterEach(() => {
+      process.env = { ...OLD_ENV };
+    });
+
+    it('defaults to enabled with a 60 second timeout', () => {
+      const res = getHumanInputConfig({});
+      expect(res.enabled).toBe(true);
+      expect(res.timeoutSeconds).toBe(60);
+      expect(res.source.enabled).toBe('default');
+      expect(res.source.timeout).toBe('default');
+    });
+
+    it('uses config values and clamps timeout', () => {
+      const res = getHumanInputConfig({ humanInput: { enabled: false, timeoutSeconds: 999 } });
+      expect(res.enabled).toBe(false);
+      expect(res.timeoutSeconds).toBe(300);
+      expect(res.source.enabled).toBe('config');
+      expect(res.source.timeout).toBe('config');
+      expect(res.clamped).toBe(true);
+    });
+
+    it('prefers env overrides over config', () => {
+      process.env.TESTRONAUT_HUMAN_INPUT = 'true';
+      process.env.TESTRONAUT_HUMAN_INPUT_TIMEOUT_SECONDS = '7';
+      const res = getHumanInputConfig({ humanInput: { enabled: false, timeoutSeconds: 120 } });
+      expect(res.enabled).toBe(true);
+      expect(res.timeoutSeconds).toBe(7);
+      expect(res.source.enabled).toBe('env');
+      expect(res.source.timeout).toBe('env');
+    });
+  });
+
   describe('enforceTurnBudget (lenient)', () => {
     it('clamps > hardMaxTurns', () => {
       const cfg = { maxTurns: 1000 };

package/tests/coreTests/redation.test.js

@@ -75,6 +75,14 @@ describe('redaction utilities', () => {
       const redacted = redactArgs('fill', args);
       expect(redacted.text).toBe('hello world');
     });
+
+    it('masks human input tool values', () => {
+      const args = { prompt: 'Enter code', value: '123456', code: '654321' };
+      const redacted = redactArgs('request_human_input', args);
+      expect(redacted.prompt).toBe('Enter code');
+      expect(redacted.value).toBe('•••••• (6)');
+      expect(redacted.code).toBe('•••••• (6)');
+    });
   });
 
   describe('redactPasswordInText', () => {
@@ -91,6 +99,13 @@ describe('redaction utilities', () => {
       expect(out).toContain(`auth with •••••• (3)`);
     });
 
+    it('masks MFA codes mentioned as entered in final text', () => {
+      const input = `SUCCESS: Logged in as ISAAC, completed MFA (entered 123456), and reached the dashboard.`;
+      const out = redactPasswordInText(input);
+      expect(out).toContain(`MFA (entered •••••• (6))`);
+      expect(out).not.toContain('123456');
+    });
+
     it('Case 3: "VALUE" into sensitive target (#access)', () => {
       const input = `Type "Imp0st3r123!" into #access`;
       const out = redactPasswordInText(input);
@@ -103,6 +118,21 @@ describe('redaction utilities', () => {
       expect(out).toBe(input);
     });
 
+    it('does not mangle MFA mission instructions while masking the access value', () => {
+      const input = `Fill the access code field (#access) with sword.
+Check the "Challenge with MFA code" checkbox.
+Set MFA code digits to 8.
+There should be an MFA challenge. Prompt the user for an MFA code, then fill the MFA Code field (#mfa-code) with that code.
+Click the "Verify Code" button (#mfa-submit).`;
+      const out = redactPasswordInText(input);
+      expect(out).toContain('Fill the access code field (#access) with •••••• (5)');
+      expect(out).toContain('Check the "Challenge with MFA code" checkbox.');
+      expect(out).toContain('Set MFA code digits to 8.');
+      expect(out).toContain('with that code.');
+      expect(out).toContain('Click the "Verify Code" button (#mfa-submit).');
+      expect(out).not.toContain('sword');
+    });
+
     it('handles api key forms with spaces/underscores/hyphens', () => {
       const cases = [
         `api-key "abcDEF123"`,

package/tests/coreTests/turnLoop.test.js

@@ -94,6 +94,7 @@ vi.mock('../../core/turnIntent.js', () => ({
 }));
 
 vi.mock('../../core/redaction.js', () => ({
+  maskPreview: (value) => `masked:${String(value ?? '').length}`,
   redactArgs: (name, args) => args,
 }));
 

package/tests/runnerTests/testronaut.test.js

@@ -12,10 +12,11 @@ vi.mock('../../core/config.js', () => ({
   getRetryLimit: vi.fn(),
   getDomListLimit: vi.fn(),
   getResourceGuardConfig: vi.fn(),
+  getHumanInputConfig: vi.fn(),
 }));
 
 import { runAgent } from '../../core/agent.js';
-import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig } from '../../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig, getHumanInputConfig } from '../../core/config.js';
 
 // Adjust the import path if your file lives elsewhere
 import { runMissions, __test__ as testronautInternals } from '../../runner/testronaut.js';
@@ -29,6 +30,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     getRetryLimit.mockReturnValue({ value: 2, source: 'default', clamped: false });
     getDomListLimit.mockReturnValue({ value: 3, mode: 'number', source: 'default', clamped: false });
     getResourceGuardConfig.mockReturnValue({ enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] });
+    getHumanInputConfig.mockReturnValue({ enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false });
   });
 
   it('passes effectiveMax to runAgent and logs any notes', async () => {
@@ -56,7 +58,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
       expect.stringContaining('Clamping to 200')
     );
     expect(runAgent).toHaveBeenCalledWith(
-      expect.any(Array), 'Budgeted Run', 200, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] } }
+      expect.any(Array), 'Budgeted Run', 200, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } }
     );
 
     warn.mockRestore();
@@ -83,7 +85,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     await runMissions({ mission: 'No warnings' }, 'Clean');
 
     expect(warn).not.toHaveBeenCalled();
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20, 3, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20, 3, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     warn.mockRestore();
     log.mockRestore();
@@ -176,7 +178,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     expect(goals[1].submissionName).toMatch(/^My Mission/);
 
     // Effective max turns and retry limit passed through
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15, 2, { domListLimit: 3, debug: false, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     log.mockRestore();
   });
@@ -215,7 +217,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
 
     await runMissions({ mission: 'Debug' }, 'Debug Mission');
 
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Debug Mission', 20, 2, { domListLimit: 3, debug: true, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] } });
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Debug Mission', 20, 2, { domListLimit: 3, debug: true, resourceGuard: { enabled: true, hrefIncludes: ['/document/'], dataTypes: ['document'] }, humanInput: { enabled: true, timeoutSeconds: 60, source: { enabled: 'default', timeout: 'default' }, clamped: false } });
 
     log.mockRestore();
   });

package/tests/toolsTests/humanInput.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import {
+  sanitizeHumanCodeInput,
+  normalizeHumanInputOptions,
+} from '../../tools/humanInput.js';
+
+describe('tools/humanInput', () => {
+  it('accepts short verification codes and removes whitespace', () => {
+    expect(sanitizeHumanCodeInput(' 123 456 ').value).toBe('123456');
+    expect(sanitizeHumanCodeInput('AB-12_cd').ok).toBe(true);
+  });
+
+  it('rejects empty, long, and unsafe input', () => {
+    expect(sanitizeHumanCodeInput('')).toMatchObject({ ok: false, reason: 'empty' });
+    expect(sanitizeHumanCodeInput('a'.repeat(65))).toMatchObject({ ok: false, reason: 'too_long' });
+    expect(sanitizeHumanCodeInput('abc@example.com')).toMatchObject({ ok: false, reason: 'invalid_characters' });
+  });
+
+  it('normalizes timeout and length limits', () => {
+    const low = normalizeHumanInputOptions({ timeoutSeconds: 1, maxLength: 1000 });
+    expect(low.timeoutSeconds).toBe(5);
+    expect(low.maxLength).toBe(64);
+    expect(low.timeoutClamped).toBe(true);
+    expect(low.maxLengthClamped).toBe(true);
+  });
+});

package/tests/toolsTests/toolSchema.test.js

@@ -15,6 +15,14 @@ describe('tools/toolSchema', () => {
     expect(entry.function.parameters?.properties).toHaveProperty('dir');
   });
 
+  it('includes request_human_input for verification codes', () => {
+    const entry = toolsSchema.find(t => t.function?.name === 'request_human_input');
+    expect(entry?.type).toBe('function');
+    expect(entry.function.description).toMatch(/verification code/i);
+    expect(entry.function.parameters?.properties?.codeType?.enum).toContain('totp');
+    expect(entry.function.parameters?.properties?.maxLength?.default).toBe(64);
+  });
+
   it('defines navigate and download_file with required fields', () => {
     const nav = toolsSchema.find(t => t.function?.name === 'navigate');
     const download = toolsSchema.find(t => t.function?.name === 'download_file');

package/tests/toolsTests/turnLoopUtils.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi } from 'vitest';
+import { finalResponseHandler } from '../../tools/turnLoopUtils.js';
+
+describe('tools/turnLoopUtils', () => {
+  it('redacts verification codes before printing and returning final responses', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    try {
+      const result = finalResponseHandler({
+        content: 'SUCCESS: Logged in, completed MFA (entered 123456), and reached the dashboard.',
+      });
+
+      expect(result).toMatchObject({ success: true });
+      expect(result.finalMessage).toContain('MFA (entered •••••• (6))');
+      expect(result.finalMessage).not.toContain('123456');
+
+      const printed = logSpy.mock.calls.flat().join('\n');
+      expect(printed).toContain('MFA (entered •••••• (6))');
+      expect(printed).not.toContain('123456');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});

package/tools/chromeBrowser.js

@@ -22,6 +22,7 @@ import {
 import fs from 'fs';
 import path from 'path';
 import { ensureBrowsers } from '../tools/playwrightSetup.js';
+import { requestHumanInput } from './humanInput.js';
 
 const FILES_DIR = path.join('missions', 'files');
 const REPORTS_DIR = path.join('missions', 'mission_reports');
@@ -1361,6 +1362,7 @@ export const CHROME_TOOL_MAP = {
   upload_file: (b, args) => b.upload_file(args),
   download_file: (b, args) => b.download_file(args),
   list_local_files: (b, args) => b.list_local_files(args),
+  request_human_input: (b, args, agentMemory) => requestHumanInput(args, agentMemory?.humanInput),
   resource_progress: (b, args, agentMemory) => {
     const prog = agentMemory?.docProgress;
     if (!prog) return JSON.stringify({ enabled: false, total: 0, downloaded: 0, remaining: [] });

package/tools/generateHtmlReport.js

@@ -35,8 +35,8 @@ export function generateHtmlReport(report, outputPath) {
   // Escaping helpers for text and HTML attributes
   const esc = (s) => String(s ?? '')
     .replace(/&/g, '&amp;').replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-  const escAttr = (s) => esc(s).replace(/"/g, '&quot;'); // for HTML attributes
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
   const badge = (status) =>
     status === 'passed' ? '✅ Passed' :
     status === 'failed' ? '❌ Failed' : (status || '—');
@@ -62,6 +62,9 @@ export function generateHtmlReport(report, outputPath) {
       const attemptLabel = retryNumber > 0
         ? ` (re-attempt ${retryNumber}/${retryTotal || retryNumber})`
         : '';
+      const humanInput = step.humanInput?.requested
+        ? `<span class="hitl" title="Human-in-the-loop input: ${esc(step.humanInput.status || 'requested')}">👤 Human in-the-loop</span>`
+        : '';
       const imgTag = step.screenshotPath
         ? `<img src="${esc(step.screenshotPath)}" alt="screenshot turn ${esc(step.turn ?? idx)}">`
         : '';
@@ -70,15 +73,16 @@ export function generateHtmlReport(report, outputPath) {
         ? step.summary.trim()
         : '';
       const planSpan = plan
-        ? `<span class="plan" title="${escAttr(plan)}">${esc(plan)}</span>`
+        ? `<span class="plan" title="${esc(plan)}">${esc(plan)}</span>`
         : '';
 
       return `
         <details class="step" ${ok ? '' : 'open'}>
           <summary>
             <span class="turn">Turn ${esc((step.turn ?? idx) + 1)}${esc(attemptLabel)}</span>
+            ${humanInput}
             ${planSpan}
-            <span class="step-result ${ok ? 'ok' : 'bad'}" ${resultTooltip ? `title="${escAttr(resultTooltip)}"` : ''}>${esc(resultRaw)}</span>
+            <span class="step-result ${ok ? 'ok' : 'bad'}" ${resultTooltip ? `title="${esc(resultTooltip)}"` : ''}>${esc(resultRaw)}</span>
             <span class="tokens">tokens: ${esc(step.tokensUsed ?? '—')} / total: ${esc(step.totalTokensUsed ?? '—')}</span>
           </summary>
           <pre class="events">${esc(events.join('\n')) || '(no events)'}</pre>
@@ -276,6 +280,11 @@ export function generateHtmlReport(report, outputPath) {
     .step summary:hover{ background: rgba(255,255,255,.08); }
 
     .turn{ font-weight:700; }
+    .hitl{
+      color:#fbbf24; border:1px solid rgba(251,191,36,.45);
+      background:rgba(251,191,36,.12); border-radius:999px;
+      padding:2px 8px; font-size:12px; font-weight:700;
+    }
     .plan{
       flex:1; color: var(--text-muted); font-size:12px;
       white-space:nowrap; overflow:hidden; text-overflow:ellipsis;

package/tools/humanInput.js

@@ -0,0 +1,165 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { stdin as input, stdout as output } from 'node:process';
+import { maskPreview } from '../core/redaction.js';
+
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const MIN_TIMEOUT_SECONDS = 5;
+const MAX_TIMEOUT_SECONDS = 300;
+const DEFAULT_MAX_CODE_LENGTH = 64;
+const MIN_CODE_LENGTH = 1;
+const MAX_CODE_LENGTH = 64;
+const CODE_RE = /^[A-Za-z0-9_-]+$/;
+
+class HiddenInputOutput extends Writable {
+  constructor(realOutput) {
+    super();
+    this.realOutput = realOutput;
+    this.hidden = false;
+  }
+
+  _write(chunk, encoding, callback) {
+    if (!this.hidden) {
+      this.realOutput.write(chunk, encoding);
+    }
+    callback();
+  }
+}
+
+function clampNumber(raw, fallback, min, max) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { value: fallback, clamped: false };
+  const value = Math.min(max, Math.max(min, Math.trunc(n)));
+  return { value, clamped: value !== n };
+}
+
+export function normalizeHumanInputOptions(opts = {}) {
+  const timeout = clampNumber(
+    opts.timeoutSeconds,
+    DEFAULT_TIMEOUT_SECONDS,
+    MIN_TIMEOUT_SECONDS,
+    MAX_TIMEOUT_SECONDS
+  );
+  const maxLength = clampNumber(
+    opts.maxLength,
+    DEFAULT_MAX_CODE_LENGTH,
+    MIN_CODE_LENGTH,
+    MAX_CODE_LENGTH
+  );
+
+  return {
+    enabled: opts.enabled !== false,
+    timeoutSeconds: timeout.value,
+    timeoutClamped: timeout.clamped,
+    maxLength: maxLength.value,
+    maxLengthClamped: maxLength.clamped,
+  };
+}
+
+export function sanitizeHumanCodeInput(raw, { maxLength = DEFAULT_MAX_CODE_LENGTH } = {}) {
+  const normalizedMax = clampNumber(maxLength, DEFAULT_MAX_CODE_LENGTH, MIN_CODE_LENGTH, MAX_CODE_LENGTH).value;
+  const value = String(raw ?? '').trim().replace(/\s+/g, '');
+
+  if (!value) {
+    return { ok: false, reason: 'empty', value: '' };
+  }
+  if (value.length > normalizedMax) {
+    return { ok: false, reason: 'too_long', value: '' };
+  }
+  if (!CODE_RE.test(value)) {
+    return { ok: false, reason: 'invalid_characters', value: '' };
+  }
+
+  return { ok: true, value };
+}
+
+export function questionWithHiddenInput(prompt, { timeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    const maskedOutput = new HiddenInputOutput(output);
+    const rl = createInterface({
+      input,
+      output: maskedOutput,
+      terminal: Boolean(output.isTTY),
+    });
+
+    let settled = false;
+    let timeout;
+
+    function finish(err, answer) {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      maskedOutput.hidden = false;
+      output.write('\n');
+      rl.close();
+      if (err) reject(err);
+      else resolve(answer);
+    }
+
+    if (timeoutMs) {
+      timeout = setTimeout(() => {
+        const err = new Error('Human input timed out.');
+        err.name = 'AbortError';
+        finish(err);
+      }, timeoutMs);
+    }
+
+    output.write(prompt);
+    maskedOutput.hidden = true;
+    rl.question('', (answer) => finish(null, answer));
+  });
+}
+
+export async function requestHumanInput(args = {}, options = {}) {
+  const opts = normalizeHumanInputOptions({
+    ...options,
+    maxLength: args.maxLength ?? options.maxLength,
+  });
+
+  if (!opts.enabled) {
+    throw new Error('Human input tool is disabled for this run.');
+  }
+
+  const codeType = String(args.codeType || 'verification_code')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '')
+    .slice(0, 40) || 'verification_code';
+  const prompt = String(args.prompt || `Enter ${codeType.replace(/_/g, ' ')}:`).trim();
+  const label = prompt.endsWith(':') ? prompt : `${prompt}:`;
+  const timeoutMs = opts.timeoutSeconds * 1000;
+
+  let answer;
+  try {
+    answer = await questionWithHiddenInput(`\n👤 ${label} `, { timeoutMs });
+  } catch (err) {
+    if (err?.name === 'AbortError') {
+      throw new Error(`Human input timed out after ${opts.timeoutSeconds}s.`);
+    }
+    throw err;
+  }
+
+  const sanitized = sanitizeHumanCodeInput(answer, { maxLength: opts.maxLength });
+  if (!sanitized.ok) {
+    throw new Error(`Human input rejected: ${sanitized.reason}.`);
+  }
+
+  return {
+    ok: true,
+    humanInputProvided: true,
+    codeType,
+    value: sanitized.value,
+    redactedValue: maskPreview(sanitized.value),
+  };
+}
+
+export const __test__ = {
+  DEFAULT_TIMEOUT_SECONDS,
+  MIN_TIMEOUT_SECONDS,
+  MAX_TIMEOUT_SECONDS,
+  DEFAULT_MAX_CODE_LENGTH,
+  MAX_CODE_LENGTH,
+  sanitizeHumanCodeInput,
+  normalizeHumanInputOptions,
+  questionWithHiddenInput,
+};