job-application-agent 3.5.0 → 3.7.0

package/job-application-agent/references/agent-box/README.md

@@ -0,0 +1,77 @@
+# agent-box — fill display + live noVNC binding
+
+Hosted fill and the buyer live panel **must share one session**.
+
+| Piece | Value | Notes |
+|-------|-------|--------|
+| Fill display | `DISPLAY=:99` | Xvfb headed Chrome |
+| Fill VNC | x11vnc → **`localhost:5900`** | Mirrors `:99` |
+| Live HTTP front | noVNC / websockify historically **`:6080`** | Buyer iframe / magic-link target |
+| Forbidden | TigerVNC **`:1` / `5901`** | Cold XFCE / wrong desktop = product failure |
+
+## Hard rule
+
+**Live noVNC = fill display 5900.**  
+`websockify` must proxy `localhost:5900`. Never point buyer live at `5901`.
+
+Verify on the box:
+
+```bash
+node job-application-agent/scripts/novnc-display-guard.mjs --unit /etc/systemd/system/novnc.service
+# or:
+node job-application-agent/scripts/novnc-display-guard.mjs --text "$(systemctl cat novnc.service)"
+```
+
+Example unit: [`novnc.service.example`](./novnc.service.example).
+
+## Session binding (pause)
+
+When attention opens on a filled form, record a **local-only** binding:
+
+```bash
+# Prefer optional fields on attention add (not synced to cloud):
+node scripts/job-application.mjs attention add --stdin <<'JSON'
+{
+  "roundId": "round-…",
+  "applicationId": "app-…",
+  "url": "https://jobs.ashbyhq.com/…/application",
+  "stage": "submission",
+  "blocker": "captcha",
+  "requiredActions": ["complete-captcha"],
+  "browserProfilePath": "/home/runner/.jaa-chrome-fill",
+  "display": ":99",
+  "vncPort": 5900,
+  "tabHint": { "urlContains": "/application" }
+}
+JSON
+
+# Or write explicitly:
+node scripts/session-binding.mjs write --stdin <<'JSON'
+{
+  "attentionId": "attention-…",
+  "jobUrl": "https://jobs.ashbyhq.com/…/application",
+  "browserProfilePath": "/home/runner/.jaa-chrome-fill",
+  "display": ":99",
+  "vncPort": 5900
+}
+JSON
+```
+
+Keep Chrome on that **exact filled tab** (same user-data-dir / CDP). Do not wipe the profile mid-pause. Do not navigate to a jobs listing.
+
+## Resume → submit
+
+After `attention-runner-poll.mjs` exit `0`:
+
+```bash
+node scripts/attention-resume-submit.mjs --checklist
+node scripts/attention-resume-submit.mjs --attention-id attention-… --stdin <<'JSON'
+{
+  "pageUrl": "https://jobs.ashbyhq.com/…/application",
+  "submitEnabled": true,
+  "leaseHeld": true
+}
+JSON
+```
+
+Submit if the DOM is clear; ledger only after a **visible** ATS confirmation.

package/job-application-agent/references/agent-box/novnc.service.example

@@ -0,0 +1,16 @@
+[Unit]
+Description=noVNC for JobAppAgent fill display (Xvfb :99 / x11vnc 5900)
+After=network.target x11vnc-fill.service
+Requires=x11vnc-fill.service
+
+[Service]
+Type=simple
+# HARD RULE: proxy fill x11vnc on localhost:5900 — NEVER TigerVNC 5901.
+# Buyer live panel (ATTENTION_LIVE_SESSION_BASE_URL → :6080) must show the
+# paused filled ATS form on DISPLAY=:99, not a cold desktop.
+ExecStart=/usr/bin/websockify --web=/usr/share/novnc 6080 localhost:5900
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target

package/job-application-agent/scripts/ats/answer-inject.mjs

@@ -0,0 +1,203 @@
+/**
+ * Map approved attention answers → ATS narrative fields (Ashby-first).
+ *
+ * Pure helpers for the resume→submit loop. Browser automation stays outside —
+ * the runner receives fill instructions and injects into matching textareas.
+ */
+
+import { fingerprintPrompt } from "../attention-questions.mjs";
+
+export { fingerprintPrompt };
+
+/**
+ * @typedef {{
+ *   id?: string,
+ *   label?: string,
+ *   name?: string,
+ *   placeholder?: string,
+ *   selector?: string,
+ *   required?: boolean,
+ *   value?: string,
+ * }} NarrativeField
+ */
+
+/**
+ * @typedef {{
+ *   questionId: string,
+ *   text: string,
+ *   source?: string,
+ *   prompt?: string,
+ * }} ApprovedAnswer
+ */
+
+const ASHBY_NARRATIVE_SELECTORS = Object.freeze([
+  'textarea[name*="question" i]',
+  'textarea[id*="question" i]',
+  'textarea[aria-label]',
+  "textarea",
+]);
+
+/**
+ * @param {string} value
+ */
+export function normalizeFieldLabel(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Token Jaccard similarity in [0, 1].
+ * @param {string} left
+ * @param {string} right
+ */
+export function labelSimilarity(left, right) {
+  const a = new Set(normalizeFieldLabel(left).split(" ").filter((t) => t.length > 2));
+  const b = new Set(normalizeFieldLabel(right).split(" ").filter((t) => t.length > 2));
+  if (!a.size || !b.size) return 0;
+  let overlap = 0;
+  for (const token of a) if (b.has(token)) overlap += 1;
+  return overlap / (a.size + b.size - overlap);
+}
+
+/**
+ * Prefer exact questionId → field.id, then best prompt/label similarity.
+ *
+ * @param {ApprovedAnswer[]} answers
+ * @param {NarrativeField[]} fields
+ * @param {{ minScore?: number }} [options]
+ */
+export function mapAnswersToFields(answers, fields, options = {}) {
+  const minScore = Number.isFinite(options.minScore) ? options.minScore : 0.25;
+  const remaining = [...(Array.isArray(fields) ? fields : [])];
+  const mappings = [];
+  const unmatchedAnswers = [];
+
+  for (const answer of Array.isArray(answers) ? answers : []) {
+    const text = String(answer?.text ?? "").trim();
+    const questionId = String(answer?.questionId ?? "").trim();
+    if (!text || !questionId) continue;
+
+    let bestIndex = -1;
+    let bestScore = 0;
+    let matchedBy = "none";
+
+    for (let i = 0; i < remaining.length; i += 1) {
+      const field = remaining[i];
+      const fieldId = String(field.id ?? "").trim();
+      if (fieldId && fieldId === questionId) {
+        bestIndex = i;
+        bestScore = 1;
+        matchedBy = "question_id";
+        break;
+      }
+      const label = String(field.label ?? field.name ?? field.placeholder ?? "").trim();
+      const prompt = String(answer.prompt ?? "").trim();
+      const score = Math.max(
+        labelSimilarity(prompt, label),
+        labelSimilarity(questionId, label),
+        labelSimilarity(prompt, fieldId),
+      );
+      if (score > bestScore) {
+        bestScore = score;
+        bestIndex = i;
+        matchedBy = "label_similarity";
+      }
+    }
+
+    if (bestIndex < 0 || bestScore < minScore) {
+      unmatchedAnswers.push(answer);
+      continue;
+    }
+
+    const [field] = remaining.splice(bestIndex, 1);
+    const label = String(field.label ?? field.name ?? field.placeholder ?? field.id ?? "").trim();
+    mappings.push({
+      questionId,
+      fieldId: field.id ? String(field.id) : null,
+      selector: field.selector ? String(field.selector) : null,
+      label,
+      text,
+      source: String(answer.source ?? "typed"),
+      score: bestScore,
+      matchedBy,
+    });
+  }
+
+  return {
+    mappings,
+    unmatchedAnswers,
+    unmatchedFields: remaining,
+  };
+}
+
+/**
+ * Build Playwright/CDP-oriented inject plan for Ashby (and generic) textareas.
+ *
+ * @param {{
+ *   answers?: ApprovedAnswer[],
+ *   questions?: { id: string, prompt: string }[],
+ *   fields?: NarrativeField[],
+ *   pageUrl?: string,
+ * }} input
+ */
+export function buildAnswerInjectPlan(input = {}) {
+  const questions = Array.isArray(input.questions) ? input.questions : [];
+  const answers = (Array.isArray(input.answers) ? input.answers : []).map((answer) => {
+    const question = questions.find((item) => item.id === answer.questionId);
+    return {
+      ...answer,
+      prompt: answer.prompt ?? question?.prompt ?? "",
+    };
+  });
+
+  const fields = Array.isArray(input.fields) && input.fields.length
+    ? input.fields
+    : answers.map((answer, index) => ({
+      id: answer.questionId,
+      label: answer.prompt || answer.questionId,
+      selector: `textarea >> nth=${index}`,
+      required: true,
+    }));
+
+  const mapped = mapAnswersToFields(answers, fields);
+  return {
+    adapterHint: /ashbyhq\.com/i.test(String(input.pageUrl ?? "")) ? "ashby" : "generic",
+    textareaSelectors: [...ASHBY_NARRATIVE_SELECTORS],
+    fills: mapped.mappings.map((item) => ({
+      questionId: item.questionId,
+      selector: item.selector,
+      label: item.label,
+      text: item.text,
+      source: item.source,
+      matchedBy: item.matchedBy,
+      score: item.score,
+      action: "fill_textarea",
+    })),
+    unmatchedAnswers: mapped.unmatchedAnswers,
+    unmatchedFields: mapped.unmatchedFields,
+    notes: [
+      "Inject approved answers into matching textareas on the BOUND filled tab only.",
+      "Never silent-paste model drafts — only typed / draft_approved / bank answers from the resume signal.",
+      "After fill, re-inspect; if required narrative remains empty → attention again.",
+      "Then continue existing resume→submit adapters.",
+    ],
+  };
+}
+
+/**
+ * @param {{ answers?: ApprovedAnswer[], blockers?: string[] }} input
+ */
+export function shouldInjectAnswersBeforeSubmit(input = {}) {
+  const answers = Array.isArray(input.answers)
+    ? input.answers.filter((a) => String(a?.text ?? "").trim())
+    : [];
+  if (!answers.length) return { inject: false, reason: "no_answers" };
+  return {
+    inject: true,
+    reason: "approved_answers_present",
+    answerCount: answers.length,
+  };
+}

package/job-application-agent/scripts/ats/submit-adapters.mjs

@@ -0,0 +1,194 @@
+/**
+ * ATS-agnostic resume submit / confirmation helpers.
+ *
+ * Pure selector + classification data for the hosted resume→submit loop.
+ * Browser automation (Playwright/CDP) stays outside this module — the runner
+ * injects a page snapshot; these helpers decide the next action.
+ *
+ * Prefer submit after resume when the DOM is clear (golden-path submit bias).
+ * filled ≠ applied until a visible confirmation surface is observed.
+ */
+
+/** Absolute blockers that must stay paused for a human. */
+export const ABSOLUTE_BLOCKER_HINTS = Object.freeze([
+  { id: "captcha", patterns: [/recaptcha/i, /hcaptcha/i, /captcha/i, /cf-turnstile/i] },
+  { id: "authentication", patterns: [/sign in/i, /log in/i, /sso/i, /single sign-on/i, /verify your identity/i] },
+  { id: "mfa", patterns: [/two-factor/i, /2fa/i, /authenticator/i, /enter (the )?code/i, /one-time password/i] },
+  { id: "legal-attestation", patterns: [/i agree/i, /terms of use/i, /privacy policy/i, /ai policy/i, /acknowledge/i] },
+  { id: "judgment", patterns: [/why (do )?you (want to )?work/i, /cover letter/i, /in your own words/i] },
+  { id: "government-id", patterns: [/passport/i, /driver'?s license/i, /government (issued )?id/i] },
+  { id: "demographic", patterns: [/gender identity/i, /race\/ethnicity/i, /veteran status/i, /disability status/i] },
+]);
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   matchHosts?: RegExp[],
+ *   submitSelectors: string[],
+ *   confirmationSelectors: string[],
+ *   confirmationUrlPatterns: RegExp[],
+ *   blockerSelectors?: string[],
+ * }} AtsSubmitAdapter
+ */
+
+/** @type {AtsSubmitAdapter} */
+export const ASHBY_ADAPTER = Object.freeze({
+  id: "ashby",
+  matchHosts: [/ashbyhq\.com$/i, /jobs\.ashbyhq\.com$/i],
+  submitSelectors: [
+    'button[type="submit"]',
+    'button:has-text("Submit")',
+    'button:has-text("Submit application")',
+    '[data-testid="submit-application"]',
+    'input[type="submit"]',
+  ],
+  confirmationSelectors: [
+    "text=/thank you for applying/i",
+    "text=/application (has been )?submitted/i",
+    "text=/we.?ve received your application/i",
+    '[data-testid="application-submitted"]',
+    ".application-submitted",
+  ],
+  confirmationUrlPatterns: [
+    /\/application-submitted\b/i,
+    /[?&]submitted=1\b/i,
+    /\/confirmation\b/i,
+  ],
+  blockerSelectors: [
+    "iframe[src*='recaptcha']",
+    "iframe[src*='hcaptcha']",
+    ".g-recaptcha",
+    "[data-testid='captcha']",
+  ],
+});
+
+/** @type {AtsSubmitAdapter} */
+export const GENERIC_ADAPTER = Object.freeze({
+  id: "generic",
+  submitSelectors: [
+    'button[type="submit"]',
+    'button:has-text("Submit")',
+    'button:has-text("Submit application")',
+    'input[type="submit"][value*="Submit" i]',
+  ],
+  confirmationSelectors: [
+    "text=/thank you for applying/i",
+    "text=/application (has been )?submitted/i",
+    "text=/we.?ve received your application/i",
+    "text=/successfully submitted/i",
+  ],
+  confirmationUrlPatterns: [
+    /\/thanks?\b/i,
+    /\/confirmation\b/i,
+    /\/application-submitted\b/i,
+    /[?&]submitted=1\b/i,
+  ],
+  blockerSelectors: [
+    "iframe[src*='recaptcha']",
+    "iframe[src*='hcaptcha']",
+    ".g-recaptcha",
+  ],
+});
+
+export const ATS_ADAPTERS = Object.freeze([ASHBY_ADAPTER, GENERIC_ADAPTER]);
+
+/**
+ * @param {string} pageUrl
+ * @returns {AtsSubmitAdapter}
+ */
+export function resolveAtsAdapter(pageUrl) {
+  let host = "";
+  try {
+    host = new URL(pageUrl).hostname;
+  } catch {
+    return GENERIC_ADAPTER;
+  }
+  for (const adapter of ATS_ADAPTERS) {
+    if (adapter.id === "generic") continue;
+    if (adapter.matchHosts?.some((re) => re.test(host))) return adapter;
+  }
+  return GENERIC_ADAPTER;
+}
+
+/**
+ * @param {{
+ *   pageUrl?: string,
+ *   pageText?: string,
+ *   visibleTexts?: string[],
+ *   matchedBlockerSelectors?: string[],
+ * }} snapshot
+ * @param {{ mode?: "pause" | "resume" }} [options]
+ * @returns {{ blocked: boolean, blockers: string[] }}
+ */
+export function detectAbsoluteBlockers(snapshot = {}, options = {}) {
+  const mode = options.mode === "resume" ? "resume" : "pause";
+  const blockers = new Set();
+  const haystack = [
+    String(snapshot.pageText ?? ""),
+    ...(Array.isArray(snapshot.visibleTexts) ? snapshot.visibleTexts : []),
+  ].join("\n");
+
+  // On resume, prefer active challenge signals — static legal/"why us" copy often
+  // remains visible after the candidate already acted in the live panel.
+  const hints = mode === "resume"
+    ? ABSOLUTE_BLOCKER_HINTS.filter((hint) => ["captcha", "authentication", "mfa", "government-id"].includes(hint.id))
+    : ABSOLUTE_BLOCKER_HINTS;
+
+  for (const hint of hints) {
+    if (hint.patterns.some((re) => re.test(haystack))) blockers.add(hint.id);
+  }
+  if (Array.isArray(snapshot.matchedBlockerSelectors) && snapshot.matchedBlockerSelectors.length) {
+    blockers.add("captcha");
+  }
+  return { blocked: blockers.size > 0, blockers: [...blockers] };
+}
+
+/**
+ * @param {{
+ *   pageUrl?: string,
+ *   matchedConfirmationSelectors?: string[],
+ *   pageText?: string,
+ * }} snapshot
+ * @param {AtsSubmitAdapter} [adapter]
+ */
+export function detectConfirmation(snapshot = {}, adapter) {
+  const resolved = adapter ?? resolveAtsAdapter(snapshot.pageUrl ?? "");
+  const url = String(snapshot.pageUrl ?? "");
+  if (resolved.confirmationUrlPatterns.some((re) => re.test(url))) {
+    return { confirmed: true, reason: "url_pattern", adapterId: resolved.id };
+  }
+  if (Array.isArray(snapshot.matchedConfirmationSelectors) && snapshot.matchedConfirmationSelectors.length) {
+    return {
+      confirmed: true,
+      reason: "confirmation_selector",
+      adapterId: resolved.id,
+      matched: snapshot.matchedConfirmationSelectors,
+    };
+  }
+  const text = String(snapshot.pageText ?? "");
+  if (/thank you for applying|application (has been )?submitted|we.?ve received your application/i.test(text)) {
+    return { confirmed: true, reason: "confirmation_text", adapterId: resolved.id };
+  }
+  return { confirmed: false, reason: "not_found", adapterId: resolved.id };
+}
+
+/**
+ * Guidance payload for a browser tool (selectors only — no automation here).
+ * @param {string} pageUrl
+ */
+export function buildSubmitProbePlan(pageUrl) {
+  const adapter = resolveAtsAdapter(pageUrl);
+  return {
+    adapterId: adapter.id,
+    submitSelectors: [...adapter.submitSelectors],
+    confirmationSelectors: [...adapter.confirmationSelectors],
+    blockerSelectors: [...(adapter.blockerSelectors ?? [])],
+    confirmationUrlPatterns: adapter.confirmationUrlPatterns.map((re) => re.source),
+    notes: [
+      "Focus the same filled ATS tab from session binding (never a cold jobs listing).",
+      "If absolute blockers remain, update attention honestly — do not submit.",
+      "If clear, click submit (submit bias). Wait for a visible confirmation surface.",
+      "Only then: cloud intent-confirm / ledger add. filled ≠ applied.",
+    ],
+  };
+}

package/job-application-agent/scripts/attention-questions.mjs

@@ -0,0 +1,111 @@
+/**
+ * Pause-time attention question packaging + AI-policy detection (skill/runner).
+ * Mirrors site/lib/attention-questions.mjs for the published skill package.
+ */
+
+export const AI_ASSISTANCE_DISCOURAGED_PATTERNS = Object.freeze([
+  /\bdo(?:n'?t| not)\s+use\s+ai\b/i,
+  /\bno\s+ai\s+assistance\b/i,
+  /\bwithout\s+ai\s+assistance\b/i,
+  /\bai[- ]generated\s+(?:answers?|content|responses?)\s+(?:are|is)\s+(?:not\s+)?(?:allowed|permitted|welcome)/i,
+  /\bplease\s+(?:write|answer)\s+in\s+your\s+own\s+(?:words|voice)\b/i,
+  /\b(?:write|answer)\s+in\s+your\s+own\s+(?:words|voice)\b/i,
+  /\bgenerative\s+ai\s+(?:is|are)\s+(?:not\s+)?(?:allowed|permitted)/i,
+  /\bchatgpt\b.*\b(?:not|never|don'?t)\b/i,
+  /\b(?:not|never|don'?t)\b.*\bchatgpt\b/i,
+]);
+
+/**
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function detectAiAssistanceDiscouraged(text) {
+  const haystack = String(text ?? "");
+  if (!haystack.trim()) return false;
+  return AI_ASSISTANCE_DISCOURAGED_PATTERNS.some((re) => re.test(haystack));
+}
+
+/**
+ * @param {string} prompt
+ */
+export function fingerprintPrompt(prompt) {
+  const normalized = String(prompt ?? "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 240);
+  let hash = 2166136261;
+  for (let i = 0; i < normalized.length; i += 1) {
+    hash ^= normalized.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `q-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+const KINDS = new Set(["judgment", "why-us", "proud-project", "narrative", "other"]);
+
+/**
+ * @param {unknown} raw
+ * @returns {{ id: string, prompt: string, kind: string, required: boolean }[]}
+ */
+export function normalizeAttentionQuestions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of raw.slice(0, 8)) {
+    if (!item || typeof item !== "object") continue;
+    const prompt = String(item.prompt ?? item.text ?? item.label ?? "").trim().slice(0, 800);
+    if (!prompt) continue;
+    let id = String(item.id ?? "").trim().slice(0, 120);
+    if (!id) id = fingerprintPrompt(prompt);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const kindRaw = String(item.kind ?? "judgment").trim().toLowerCase().slice(0, 40);
+    out.push({
+      id,
+      prompt,
+      kind: KINDS.has(kindRaw) ? kindRaw : "judgment",
+      required: item.required !== false,
+    });
+  }
+  return out;
+}
+
+/**
+ * Extract narrative prompts from posting / form copy when the agent did not pass questions[].
+ * Best-effort packaging for judgment pauses.
+ * @param {string} pageText
+ * @param {{ limit?: number }} [options]
+ */
+export function extractNarrativeQuestionsFromText(pageText, options = {}) {
+  const limit = Number.isFinite(options.limit) ? Math.max(1, Math.min(options.limit, 6)) : 4;
+  const text = String(pageText ?? "");
+  if (!text.trim()) return [];
+  const patterns = [
+    /why (?:do )?you (?:want to )?work(?: at| for| with)?[^\n?]{0,80}\?/gi,
+    /why (?:are you interested|this (?:role|company|team))[^\n?]{0,80}\?/gi,
+    /(?:tell us about|describe) (?:a )?project you(?:'re| are)? proud of[^\n?]{0,40}\?/gi,
+    /what (?:motivates|excites) you[^\n?]{0,60}\?/gi,
+    /in your own words[^\n?]{0,80}\?/gi,
+  ];
+  const found = [];
+  const seen = new Set();
+  for (const re of patterns) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(text)) && found.length < limit) {
+      const prompt = match[0].replace(/\s+/g, " ").trim();
+      const id = fingerprintPrompt(prompt);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      found.push({
+        id,
+        prompt,
+        kind: /proud|project/i.test(prompt) ? "proud-project" : /why/i.test(prompt) ? "why-us" : "judgment",
+        required: true,
+      });
+    }
+  }
+  return found;
+}