halo-agent 2.2.1 → 2.2.3

package/detectFormErrors.js

@@ -308,7 +308,7 @@ async function detectFormErrorsInRoot(page) {
  *
  * Output: { hasEmptyRequired: boolean, emptyFields: [{label, selector?}] }
  */
-async function detectRequiredEmpties(page) {
+async function detectRequiredEmpties(page, opts = {}) {
   const roots = [page, ...page.frames().filter((f) => {
     const u = f.url();
     return f !== page.mainFrame() && u && DFE_EMBED_HOSTS.test(u) && !/google\.com|gstatic\.com|recaptcha/i.test(u);
@@ -321,13 +321,30 @@ async function detectRequiredEmpties(page) {
       merged.emptyFields.push(...(r.emptyFields || []));
     }
   }
-  // Dedup by label
+  // Exclude labels the planner deliberately skipped (conditional-not-applicable,
+  // honeypots, optional). The planner has dependency context the DOM walk lacks,
+  // so a field it intentionally left blank is NOT an unfilled required field.
+  const excluded = new Set((opts.excludeLabels || []).map((l) => String(l || '').toLowerCase().trim()).filter(Boolean));
+  // Dedup by label, drop excluded.
   const seen = new Set();
   merged.emptyFields = merged.emptyFields.filter((f) => {
     const k = (f.label || '').toLowerCase().trim();
     if (!k || seen.has(k)) return false;
-    seen.add(k); return true;
+    seen.add(k);
+    // If smartFill confirmed a resume upload, a file/resume field reading
+    // "empty" is a false positive: Ashby (and similar) keep the native
+    // <input type=file> at files.length===0 after upload because they stash
+    // the file in their own state and show a filename chip elsewhere. Don't
+    // block on it.
+    if (opts.resumeUploaded && f.isFile) return false;
+    // Match excluded loosely — DOM label vs planner label can differ by
+    // trailing punctuation/truncation.
+    for (const ex of excluded) {
+      if (k === ex || k.startsWith(ex) || ex.startsWith(k) || k.includes(ex) || ex.includes(k)) return false;
+    }
+    return true;
   });
+  merged.hasEmptyRequired = merged.emptyFields.length > 0;
   return merged;
 }
 
@@ -396,18 +413,42 @@ async function detectRequiredEmptiesInRoot(page) {
     // A radiogroup / checkbox-set counts as "filled" if ANY member is checked.
     // We track required groups by name so we don't flag every individual radio.
     function isRequired(el) {
+      // Programmatic markers are authoritative and field-specific.
       if (el.required) return true;
       if (el.getAttribute('aria-required') === 'true') return true;
-      // Asterisked label is the most common ATS convention (Ashby, Greenhouse).
-      const lbl = nearestLabel(el);
-      // The raw label may have had its trailing * stripped by nearestLabel, so
-      // also look at the surrounding label text for an asterisk.
+
+      // Asterisk/"required" in label text is the common ATS convention, BUT
+      // it must come from THIS field's OWN label — not a sibling's. The Plaid
+      // false-positive ("If yes, please provide further explanation below")
+      // was a conditional field flagged because a climb-5-ancestors walk
+      // scooped up a neighbouring required field's asterisk. Only trust the
+      // directly-associated label:
+      //   1. <label for=id>
+      //   2. el.labels[0]
+      //   3. the SINGLE closest wrapping label/legend that contains ONLY this
+      //      control (not a shared group container with multiple inputs).
+      const labelTextOf = (lblEl) => (lblEl && (lblEl.innerText || lblEl.textContent || '')).trim();
+      const marks = (txt) => /\*\s*$/.test(txt) || /\(\s*required\s*\)/i.test(txt) || /\brequired\b\s*\*?$/i.test(txt);
+
+      if (el.id) {
+        const lbl = document.querySelector(`label[for="${el.id}"]`);
+        if (lbl) return marks(labelTextOf(lbl));
+      }
+      if (el.labels && el.labels[0]) return marks(labelTextOf(el.labels[0]));
+
+      // Closest wrapping label/legend, but ONLY if that container holds a
+      // single control (so we don't inherit a group asterisk meant for a
+      // different required field in the same fieldset).
       let p = el.parentElement; let hops = 0;
-      while (p && hops < 5) {
-        const labelEl = p.querySelector('label, legend, [class*="label"]');
+      while (p && hops < 4) {
+        const labelEl = p.querySelector(':scope > label, :scope > legend, :scope > [class*="label"]');
         if (labelEl) {
-          const raw = (labelEl.innerText || labelEl.textContent || '');
-          if (/\*\s*$/.test(raw.trim()) || /\brequired\b/i.test(raw)) return true;
+          const controlsInScope = p.querySelectorAll('input:not([type=hidden]), textarea, select, [role="combobox"], [contenteditable="true"]').length;
+          if (controlsInScope <= 1) return marks(labelTextOf(labelEl));
+          // Shared container with multiple controls — the asterisk isn't
+          // necessarily ours. Stop; treat as not-required unless a
+          // programmatic marker said otherwise (handled above).
+          return false;
         }
         p = p.parentElement; hops += 1;
       }
@@ -458,7 +499,9 @@ async function detectRequiredEmptiesInRoot(page) {
       const key = label.toLowerCase();
       if (seen.has(key)) continue;
       seen.add(key);
-      emptyFields.push({ label, selector: el.id ? `#${el.id}` : (el.name ? `[name="${el.name}"]` : null) });
+      const isFile = type === 'file'
+        || /resume|cv\b|cover.?letter|attach|upload/i.test(label);
+      emptyFields.push({ label, isFile, selector: el.id ? `#${el.id}` : (el.name ? `[name="${el.name}"]` : null) });
     }
 
     return { hasEmptyRequired: emptyFields.length > 0, emptyFields };

package/index.js

@@ -38,14 +38,18 @@ async function main() {
     let v = '';
     try { v = require('./package.json').version; } catch {}
     ui.banner(v);
+    console.log(`  ${ui.bold('Usage')}  ${ui.gray('halo-agent <command>')}`);
     console.log('');
-    console.log(`  ${ui.bold('Usage')}`);
-    console.log(`    ${ui.cyan('halo-agent pair')} ${ui.gray('<code>')}            One-click pair with the dashboard`);
-    console.log(`    ${ui.cyan('halo-agent start')}                   Start the agent`);
-    console.log(`    ${ui.cyan('halo-agent install-autostart')}       Auto-start at login`);
-    console.log(`    ${ui.cyan('halo-agent uninstall-autostart')}     Remove login auto-start`);
-    console.log(`    ${ui.cyan('halo-agent init')}                    First-time setup (legacy: token paste)`);
-    console.log(`    ${ui.cyan('halo-agent token')} ${ui.gray('<value>')}          Update auth token`);
+    ui.commandTable([
+      ['pair <code>',           'One-click pair with the HALO dashboard'],
+      ['start',                 'Connect to Chrome and run the agent'],
+      ['install-autostart',     'Run automatically at every login'],
+      ['uninstall-autostart',   'Remove the login auto-start'],
+      ['init',                  'First-time setup (legacy token paste)'],
+      ['token <value>',         'Update the auth token'],
+    ]);
+    console.log('');
+    ui.hint('Get a pairing code: HALO dashboard → Profile → Auto-apply agent → Get pairing code.');
     console.log('');
     process.exit(1);
   }
@@ -123,7 +127,8 @@ async function runPair(code) {
   spin.stop(`Paired with HALO`);
   ui.muted(`  Token saved to ~/.halo-agent/config.json`);
   console.log('');
-  console.log(`  ${ui.gray('Next:')} ${ui.cyan('halo-agent start')}`);
+  ui.nextStep('halo-agent start', 'connect Chrome and start applying');
+  ui.hint('Or `halo-agent install-autostart` to run it at every login.');
   console.log('');
 }
 
@@ -308,7 +313,7 @@ async function runInit() {
   saveConfig(config);
   console.log('');
   ui.success('Config saved to ~/.halo-agent/config.json');
-  console.log(`  ${ui.gray('Next:')} ${ui.cyan('halo-agent start')}`);
+  ui.nextStep('halo-agent start', 'connect Chrome and start applying');
   console.log('');
 }
 
@@ -467,8 +472,8 @@ async function waitForChromeGone(timeoutMs) {
 async function runStart() {
   const config = loadConfig();
   if (!config || !config.token) {
-    ui.fail('No config found.');
-    console.log(`  ${ui.gray('Run')} ${ui.cyan('halo-agent pair <code>')} ${ui.gray('first. Get a code from the HALO dashboard.')}`);
+    ui.fail('Not paired yet — no config found.');
+    ui.nextStep('halo-agent pair <code>', 'get a code from the HALO dashboard');
     process.exit(1);
   }
 

package/orchestrator.js

@@ -47,6 +47,7 @@ async function fillFields(page, aep, opts) {
     askUserReasons: result.askUserReasons || [],
     plannedActions: result.planned || 0,
     fellBackToLegacy: !!result.fallback,
+    resumeUploaded: !!result.resumeUploaded,
   };
 }
 const { detectCaptcha, solveCaptcha, injectCaptchaToken } = require('./captcha');
@@ -217,8 +218,14 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
       }
     }
 
-    // Upload resume if we have a temp file
-    if (tempResumeFile) {
+    // Upload resume ONLY if smartFill didn't already place it. This blanket
+    // fallback predates smartFill's per-field upload_file action; running it
+    // unconditionally dumped the resume into the FIRST file input it found —
+    // which on Greenhouse (resume + cover-letter inputs) put the resume into
+    // the cover-letter slot too. smartFill now reports resumeUploaded, so we
+    // only fall back when the planner genuinely missed the resume field.
+    if (tempResumeFile && !fillResult.resumeUploaded) {
+      console.log('[orchestrator] smartFill did not upload a resume — running fallback uploader.');
       const uploaded = await uploadFile(page, 'input[type="file"], [data-testid*="resume"], button:has-text("Upload")', tempResumeFile);
       if (uploaded) fillResult.filled = (fillResult.filled || 0) + 1;
     }
@@ -444,7 +451,8 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
     // what the config/agent_config says: we route to REVIEWING so the human
     // sees exactly which fields are blank. Never silently submit incomplete.
     // ─────────────────────────────────────────────────────────────────────
-    const requiredCheck = await detectRequiredEmpties(page).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
+    const skippedLabels = (ctx.skippedFields || []).map((s) => s.label);
+    const requiredCheck = await detectRequiredEmpties(page, { excludeLabels: skippedLabels, resumeUploaded: !!fillResult.resumeUploaded }).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
     let forceReview = false;
     if (requiredCheck.hasEmptyRequired) {
       const list = requiredCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
@@ -459,16 +467,21 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
 
     if (forceReview) {
       const list = requiredCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
-      await reportStatus('NEEDS_ATTENTION', {
+      // Report REVIEWING (not NEEDS_ATTENTION): the agent is going to WAIT on
+      // the submit-confirmed flag, and POST /apply-queue/submit/:id only
+      // accepts rows in REVIEWING state. Using NEEDS_ATTENTION here meant the
+      // dashboard's "Resolved" click 400'd and the agent waited forever. The
+      // reason text still tells the user exactly which fields to fill; the
+      // "Submit" button then wakes the agent once they've filled them in Chrome.
+      await reportStatus('REVIEWING', {
         review_screenshot_r2_key: reviewKey || null,
-        needs_attention_reason: `${requiredCheck.emptyFields.length} required field(s) could not be filled: ${list}. Fill them in Chrome, then click Submit / Resume.`,
-        intervention_type: 'incomplete_fields',
         step: 'REVIEWING',
-        step_detail: `Empty required: ${list}`.slice(0, 200),
+        step_detail: `${requiredCheck.emptyFields.length} required field(s) need you: ${list}. Fill them in Chrome, then click Submit.`.slice(0, 200),
+        needs_attention_reason: `${requiredCheck.emptyFields.length} required field(s) could not be auto-filled: ${list}. Fill them in your Chrome window, then click Submit.`,
         fields_filled: cumulativeFilled,
       });
-      // Wait for the human to fill + confirm, exactly like the no-auto-submit
-      // path. They resolve the blanks in Chrome, then click Submit/Resume.
+      // Wait for the human to fill + confirm. They resolve the blanks in
+      // Chrome, then click Submit on the dashboard.
       await waitForSubmitConfirmation(config, queueId);
     } else {
       await reportStatus('REVIEWING', {
@@ -647,7 +660,8 @@ async function runJob(queueItem, chromeConn, config, reportStatus) {
       //      redirect, verifier down → it had said "trusting click").
       // If either holds, we refuse the silent DONE and route to REVIEWING.
       const stillOnForm = !/thank|confirm|success|applied|submitted/i.test(verdictUrl);
-      const postCheck = await detectRequiredEmpties(page).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
+      const postSkipped = (ctx.skippedFields || []).map((s) => s.label);
+      const postCheck = await detectRequiredEmpties(page, { excludeLabels: postSkipped, resumeUploaded: !!fillResult.resumeUploaded }).catch(() => ({ hasEmptyRequired: false, emptyFields: [] }));
 
       if (postCheck.hasEmptyRequired) {
         const list = postCheck.emptyFields.map((f) => f.label).slice(0, 8).join(', ');
@@ -1324,7 +1338,7 @@ async function runExtensionFill({
     fillResult.filled += precision.filled || 0;
   }
 
-  if (tempResumeFile) {
+  if (tempResumeFile && !fillResult.resumeUploaded) {
     const uploaded = await uploadFile(page, 'input[type="file"], [data-testid*="resume"], button:has-text("Upload")', tempResumeFile);
     if (uploaded) fillResult.filled = (fillResult.filled || 0) + 1;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halo-agent",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "HALO local apply agent — auto-fills job applications using your real Chrome session",
   "main": "index.js",
   "bin": {

package/poller.js

@@ -15,7 +15,8 @@ let sessionId = null;
 
 async function startPolling(chromeConn, config) {
   ui.success('Listening for jobs');
-  ui.muted(`  Polling every 5s. ${ui.cyan('Ctrl-C')} to stop.`);
+  ui.hint(`Queue one from HALO: a job's prep page → Approve & send to agent.`);
+  ui.muted(`  Polling every 5s · ${ui.cyan('Ctrl-C')} to stop`);
   console.log('');
 
   // Register agent session with backend

package/smartFill.js

@@ -781,6 +781,7 @@ async function smartFillPage(page, aep, options) {
   const fieldByMmid = new Map(fields.map((f) => [String(f.mmid), f]));
   const planByMmid = new Map(plan.map((p) => [String(p.mmid), p]));
   let filled = 0, skipped = 0, failed = 0;
+  let resumeUploaded = false; // so the orchestrator can skip its blanket fallback
   const askUserReasons = [];
 
   for (const f of fields) {
@@ -807,9 +808,24 @@ async function smartFillPage(page, aep, options) {
       if (item.action === 'skip') {
         console.log(`[smartFill] skip "${labelShort}" — ${result.reason}`);
         skipped += 1;
+        // Record the planner's deliberate skips so the orchestrator's
+        // required-empty guard can EXCLUDE them. The planner has full
+        // context (it saw "If yes…" conditional dependencies); the guard is
+        // a blind DOM walk. A field the planner intentionally left blank
+        // (conditional-not-applicable, honeypot, optional) must not be
+        // mistaken for an unfilled required field.
+        if (ctx && Array.isArray(ctx.skippedFields) && f.label) {
+          ctx.skippedFields.push({ label: f.label, reason: (item.reasoning || result.reason || '').slice(0, 160) });
+        }
       } else {
         console.log(`[smartFill] ${item.action} "${labelShort}" — ${result.reason}${item.reasoning ? ` (why: ${item.reasoning.slice(0, 80)})` : ''}`);
         filled += 1;
+        // Note a successful resume upload so the orchestrator doesn't run its
+        // legacy blanket "upload resume to the first file input" fallback,
+        // which was dumping the resume into the COVER-LETTER slot too.
+        if (item.action === 'upload_file' && String(item.value).toLowerCase().trim() !== 'cover_letter') {
+          resumeUploaded = true;
+        }
         // Track in ctx for cross-page dedup
         if (ctx && ctx.answeredFields) {
           ctx.answeredFields.set(f.label || f.selectorHint, {
@@ -827,7 +843,7 @@ async function smartFillPage(page, aep, options) {
     }
   }
 
-  return { filled, skipped, failed, askUserReasons, planned: plan.length, fallback: false };
+  return { filled, skipped, failed, askUserReasons, planned: plan.length, fallback: false, resumeUploaded };
 }
 
 module.exports = { smartFillPage };

package/ui.js

@@ -41,15 +41,56 @@ const warn    = (msg) => console.log(`${yellow('!')} ${msg}`);
 const muted   = (msg) => console.log(gray(msg));
 const step    = (msg) => console.log(`${gray(sym.dot)} ${msg}`);
 
-// Banner shown on `start`. Three lines so it has presence on camera without
-// being a giant ASCII-art block that ages badly.
+// Strip ANSI so box math measures the VISIBLE width, not the escape-padded
+// string length. Without this, colored content overflows the box border.
+const STRIP_ANSI = /\x1b\[[0-9;]*m/g;
+const visLen = (s) => String(s).replace(STRIP_ANSI, '').length;
+
+// Box-drawing glyphs (rounded). ASCII fallback on legacy Windows terminals.
+const box = (process.platform === 'win32' && !process.env.WT_SESSION)
+  ? { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|' }
+  : { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' };
+
+// The compact boxed wordmark. Ember mark + tagline + version, in a rounded
+// box — the Vercel/Bun look. Reads well on camera and in a small terminal,
+// and ages better than big ASCII art. The ⬢ is HALO's hex mark.
 function banner(version) {
-  const v = version ? gray(`v${version}`) : '';
-  const line = gray('─'.repeat(40));
+  const mark = `${ember('⬢')} ${ember(bold('HALO'))}`;
+  const ver  = version ? `${gray('agent')} ${gray('v' + version)}` : gray('agent');
+  // Two content lines.
+  const line1 = `${mark}  ${gray('·')}  ${ver}`;
+  const line2 = gray('auto-apply, in your own Chrome');
+  const inner = Math.max(visLen(line1), visLen(line2)) + 2; // 1 space padding each side
+  const pad = (s) => ' ' + s + ' '.repeat(inner - visLen(s) - 1);
+  const top = gray(box.tl + box.h.repeat(inner) + box.tr);
+  const bot = gray(box.bl + box.h.repeat(inner) + box.br);
+  const bar = gray(box.v);
+  console.log('');
+  console.log(`  ${top}`);
+  console.log(`  ${bar}${pad(line1)}${bar}`);
+  console.log(`  ${bar}${pad(line2)}${bar}`);
+  console.log(`  ${bot}`);
   console.log('');
-  console.log(`  ${ember(bold('HALO'))} ${bold('Agent')}  ${v}`);
-  console.log(`  ${gray('Auto-apply, in your own Chrome.')}`);
-  console.log(`  ${line}`);
+}
+
+// Affordance helper: the obvious next command, rendered consistently so the
+// user always knows what to type next. Shown after pair/init/etc.
+function nextStep(cmd, note) {
+  const tail = note ? `   ${gray(note)}` : '';
+  console.log(`  ${gray('Next')} ${gray(sym.arrow)} ${cyan(cmd)}${tail}`);
+}
+
+// A hint line — softer than nextStep, for "you can also…" affordances.
+function hint(msg) {
+  console.log(`  ${gray(sym.dot)} ${gray(msg)}`);
+}
+
+// Aligned command table for the usage screen. rows: [[cmd, desc], ...].
+function commandTable(rows) {
+  const w = Math.max(...rows.map(([c]) => c.length));
+  for (const [cmd, desc] of rows) {
+    console.log(`    ${cyan(cmd.padEnd(w))}   ${gray(desc)}`);
+  }
 }
 
 // Lightweight spinner for waiting states ("Connecting to Chrome..."). Frames
@@ -81,5 +122,6 @@ function spinner(message) {
 
 module.exports = {
   bold, dim, red, green, yellow, blue, magenta, cyan, gray, ember,
-  sym, success, fail, info, warn, muted, step, banner, spinner,
+  sym, success, fail, info, warn, muted, step,
+  banner, spinner, nextStep, hint, commandTable, visLen,
 };