@proagentstore/cli 0.4.77 → 0.4.79

package/dist/browser-runner/local-artifact/contract.js

@@ -0,0 +1,188 @@
+/**
+ * Local artifact generation — the wire contract between PAGS and the runner (#956, epic #943).
+ *
+ * The Application Tailor turns an approved job lead (#955) into a tailored résumé and cover letter,
+ * written by a Codex or Claude Code CLI signed in on the owner's machine, from source files the
+ * owner keeps in a workspace folder (`~/jobs` by default). No repository, no browser, no Workers AI
+ * and no provider API key: the CLI runs on the machine's own login or subscription only.
+ *
+ * Like `local-browser/contract.ts`, this file is kept BYTE-IDENTICAL at
+ *
+ *   workers/api/src/lib/local-artifact/contract.ts
+ *   packages/browser-runner/src/local-artifact/contract.ts
+ *
+ * (`contract.test.ts` fails the moment they differ) and imports nothing, so it can be vendored.
+ *
+ * PULL, not push: the runner holds no API token, so PAGS reads a run's events and result with
+ * `status` — when an application is read and from the per-minute cron.
+ */
+export const LOCAL_ARTIFACT_TASK_TYPE = "local_artifact.generate";
+export const LOCAL_ARTIFACT_RUN_PATH = "/local-artifact/run";
+export const LOCAL_ARTIFACT_STATUS_PATH = "/local-artifact/status";
+export const LOCAL_ARTIFACT_CANCEL_PATH = "/local-artifact/cancel";
+/** The readiness event a completed tailoring run emits, once, through the connection outbox. */
+export const MATERIALS_READY_EVENT = "job.application.materials_ready";
+export const LOCAL_ARTIFACT_ENGINES = ["claude", "codex"];
+export const LOCAL_ARTIFACT_AUTH_MODES = ["machine", "subscription"];
+export const LOCAL_ARTIFACT_SOURCE_ROLES = ["resume", "profile", "answers"];
+export const REQUIRED_SOURCE_ROLES = ["resume", "profile"];
+export const LOCAL_ARTIFACT_BLOCK_REASONS = [
+    "missing_source",
+    "malformed_lead",
+    "workspace_unavailable",
+    "missing_information",
+    "uncertain_claim",
+    "engine_not_signed_in",
+    "api_key_refused",
+];
+export const LOCAL_ARTIFACT_EVENT_TYPES = [
+    "engine.auth_checked",
+    "engine.started",
+    "engine.ended",
+    "source.read",
+    "source.missing",
+    "claims.checked",
+    "artifact.written",
+    "run.needs_human",
+    "retention.swept",
+    "note",
+];
+export const LOCAL_ARTIFACT_ENGINE_AUTHS = ["machine-login", "subscription", "api-key", "missing_login", "unknown"];
+export const LOCAL_ARTIFACT_CAPS = { questions: 20, questionChars: 300, sources: 6, sourceBytes: 256 * 1024 };
+/** An id used as a folder name: no separators, no dots, nothing a path could be built out of. */
+export const PATH_SEGMENT = /^[A-Za-z0-9_-]{1,100}$/;
+/** A source path inside the workspace: relative, no `..`, no absolute, no NUL, no backslash. */
+export function isWorkspaceRelative(path) {
+    if (!path || path.length > 300 || path.startsWith("/") || path.startsWith("~") || /[\0\\]/.test(path))
+        return false;
+    return path.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+/** A workspace folder: `~/…` with the same segment rules. */
+export function isHomeRelative(path) {
+    return typeof path === "string" && path.startsWith("~/") && isWorkspaceRelative(path.slice(2));
+}
+const str = (v, max) => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : null);
+const oneOf = (list, v) => (list.includes(v) ? v : null);
+const LEAD_FIELDS = ["company", "location", "url", "source", "posted_date", "match_rationale"];
+const HASH = /^[a-f0-9]{64}$/;
+/**
+ * The approved lead, validated — or why it is not one. A malformed lead never reaches a CLI: it
+ * pauses the application instead, because a résumé tailored to a half-read lead is a plausible guess.
+ */
+export function parseLocalArtifactLead(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return { error: "the lead must be an object" };
+    const o = raw;
+    const eventId = str(o.eventId, 300);
+    if (!eventId)
+        return { error: "the lead has no eventId" };
+    const sourceInstanceId = str(o.sourceInstanceId, 100);
+    if (!sourceInstanceId)
+        return { error: "the lead has no sourceInstanceId" };
+    const leadId = str(o.leadId, 100);
+    if (!leadId || !PATH_SEGMENT.test(leadId))
+        return { error: "the lead has no usable leadId" };
+    const lifecycleVersion = o.lifecycleVersion;
+    if (typeof lifecycleVersion !== "number" || !Number.isInteger(lifecycleVersion) || lifecycleVersion < 1)
+        return { error: "the lead has no lifecycleVersion" };
+    const leadUrl = str(o.leadUrl, 2000) ?? "";
+    if (leadUrl && !/^https?:\/\/[^\s/]+/i.test(leadUrl))
+        return { error: "the lead's URL is not an http(s) URL" };
+    const requestedAt = str(o.requestedAt, 40);
+    if (!requestedAt || Number.isNaN(Date.parse(requestedAt)))
+        return { error: "the lead has no requestedAt time" };
+    const body = o.lead && typeof o.lead === "object" && !Array.isArray(o.lead) ? o.lead : null;
+    const title = body ? str(body.title, 300) : null;
+    if (!body || !title)
+        return { error: "the lead has no job title" };
+    const lead = { title };
+    for (const f of LEAD_FIELDS) {
+        const v = str(body[f], f === "match_rationale" ? 2000 : 500);
+        if (v)
+            lead[f] = v;
+    }
+    return { lead: { eventId, sourceInstanceId, leadId, leadUrl, lifecycleVersion, requestedAt, lead } };
+}
+const DETAIL_KEYS = new Set(["engine", "authMode", "engineAuth", "role", "path", "sha256", "bytes", "kind", "total", "unmatched", "reason", "exitCode", "count", "removed", "status"]);
+/** A validated event, or null. Detail keeps only whitelisted, primitive, bounded values. */
+export function parseLocalArtifactEvent(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const type = oneOf(LOCAL_ARTIFACT_EVENT_TYPES, o.type);
+    const at = str(o.at, 40);
+    if (!type || !at || Number.isNaN(Date.parse(at)))
+        return null;
+    const event = { type, at };
+    if (o.detail && typeof o.detail === "object" && !Array.isArray(o.detail)) {
+        const detail = {};
+        for (const [k, v] of Object.entries(o.detail)) {
+            if (!DETAIL_KEYS.has(k))
+                continue;
+            if (typeof v === "string")
+                detail[k] = v.slice(0, 300);
+            else if (typeof v === "number" || typeof v === "boolean")
+                detail[k] = v;
+        }
+        if (Object.keys(detail).length)
+            event.detail = detail;
+    }
+    return event;
+}
+/** A validated result envelope, or the reason it is not one. */
+export function parseLocalArtifactResult(raw) {
+    if (!raw || typeof raw !== "object")
+        return { error: "result must be an object" };
+    const o = raw;
+    const runId = str(o.runId, 100);
+    if (!runId)
+        return { error: "runId is required" };
+    const outcome = o.outcome === "completed" || o.outcome === "needs_human" || o.outcome === "failed" ? o.outcome : null;
+    if (!outcome)
+        return { error: "outcome must be completed, needs_human or failed" };
+    const traceId = str(o.traceId, 100);
+    if (!traceId)
+        return { error: "traceId is required" };
+    const engineAuth = oneOf(LOCAL_ARTIFACT_ENGINE_AUTHS, o.engineAuth);
+    if (!engineAuth)
+        return { error: `engineAuth must be one of ${LOCAL_ARTIFACT_ENGINE_AUTHS.join(", ")}` };
+    if (!Array.isArray(o.artifacts) || !Array.isArray(o.sourceHashes))
+        return { error: "artifacts and sourceHashes must be arrays" };
+    const artifacts = [];
+    for (const [i, a] of o.artifacts.slice(0, 10).entries()) {
+        const r = (a && typeof a === "object" ? a : {});
+        const kind = r.kind === "resume" || r.kind === "cover_letter" ? r.kind : null;
+        const path = str(r.path, 500);
+        const sha256 = str(r.sha256, 64);
+        if (!kind || !path || !isHomeRelative(path) || !sha256 || !HASH.test(sha256) || typeof r.bytes !== "number")
+            return { error: `artifacts[${i}] needs a kind, a ~/ path, a sha256 and bytes` };
+        artifacts.push({ kind, path, sha256, bytes: r.bytes });
+    }
+    const sourceHashes = [];
+    for (const [i, s] of o.sourceHashes.slice(0, LOCAL_ARTIFACT_CAPS.sources).entries()) {
+        const r = (s && typeof s === "object" ? s : {});
+        const role = oneOf(LOCAL_ARTIFACT_SOURCE_ROLES, r.role);
+        const path = str(r.path, 500);
+        const sha256 = str(r.sha256, 64);
+        if (!role || !path || !sha256 || !HASH.test(sha256) || typeof r.bytes !== "number")
+            return { error: `sourceHashes[${i}] needs a role, a path, a sha256 and bytes` };
+        sourceHashes.push({ role, path, sha256, bytes: r.bytes });
+    }
+    if (outcome === "completed" && (!artifacts.some((a) => a.kind === "resume") || !artifacts.some((a) => a.kind === "cover_letter"))) {
+        return { error: "a completed run must report both a resume and a cover_letter artifact" };
+    }
+    const out = { runId, outcome, artifacts, sourceHashes, profileVersion: str(o.profileVersion, 100), engineAuth, traceId };
+    const generatedAt = str(o.generatedAt, 40);
+    if (generatedAt && !Number.isNaN(Date.parse(generatedAt)))
+        out.generatedAt = generatedAt;
+    if (outcome === "needs_human") {
+        out.blockReason = oneOf(LOCAL_ARTIFACT_BLOCK_REASONS, o.blockReason) ?? "missing_information";
+        out.questions = (Array.isArray(o.questions) ? o.questions : [])
+            .filter((q) => typeof q === "string" && q.trim() !== "")
+            .slice(0, LOCAL_ARTIFACT_CAPS.questions)
+            .map((q) => q.trim().slice(0, LOCAL_ARTIFACT_CAPS.questionChars));
+    }
+    if (outcome === "failed")
+        out.error = str(o.error, 1000) ?? "The run failed without a reason.";
+    return { result: out };
+}

package/dist/browser-runner/local-artifact/engine.js

@@ -0,0 +1,166 @@
+/**
+ * How a tailoring run launches its CLI, what it asks it for, and how the answer is checked (#956).
+ *
+ * The CLI gets NO tools. Claude Code runs with `--tools ""` and an empty, strict MCP config; Codex
+ * runs `--sandbox read-only` with user config and web search off, in an empty scratch folder. The
+ * owner's sources are read by the RUNTIME and handed over in the prompt, and the CLI answers with
+ * one JSON object; the runtime — not the CLI — writes the files. So the CLI cannot write anywhere,
+ * and every write is confined to the run's own folder by code the runner controls.
+ *
+ * Subscription-only: both modes remove the per-token provider keys from the inherited environment
+ * (an empty overlay value means remove — `mergeEnv`), and `machine` also removes the Claude
+ * subscription token so the CLI's own stored login is what runs. The env is then READ BACK
+ * (`resolveEngineAuth`) and a run whose engine would still see an API key is refused, not started.
+ *
+ * Truthfulness is checked, not requested: the CLI must cite, for every claim, a verbatim quote
+ * from a named source, and every quote is looked up in that source. Years, emails and phone
+ * numbers in the generated text must also appear in the sources. Anything that does not check
+ * out pauses the run with `needs_human` — no file is written from an unverified draft.
+ */
+import { mergeEnv } from "../coding/engine-env.js";
+import { resolveEngineAuth } from "../coding/engine-auth.js";
+import { finalText, missingLogin } from "../local-browser/engine.js";
+export { finalText, missingLogin };
+const PROVIDER_KEYS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+const SUBSCRIPTION_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
+/** The engine's environment: the machine's, never with a provider API key. */
+export function artifactEngineEnv(authMode, base = process.env) {
+    const overlay = {};
+    for (const k of PROVIDER_KEYS)
+        overlay[k] = "";
+    if (authMode === "machine")
+        overlay[SUBSCRIPTION_TOKEN] = "";
+    return mergeEnv(base, overlay);
+}
+export function observedArtifactAuth(engine, env) {
+    return resolveEngineAuth(engine, env);
+}
+export function buildArtifactEngineSpec(input) {
+    const env = artifactEngineEnv(input.authMode, input.baseEnv);
+    if (input.engine === "claude") {
+        return {
+            command: "claude",
+            args: ["-p", input.prompt, "--output-format", "stream-json", "--verbose", "--tools", "", "--strict-mcp-config", "--permission-mode", "dontAsk"],
+            env,
+        };
+    }
+    return {
+        command: "codex",
+        args: ["exec", "--json", "--skip-git-repo-check", "--sandbox", "read-only", "--ignore-user-config", "-c", 'web_search="disabled"', "-c", "tools.web_search=false", input.prompt],
+        env,
+    };
+}
+/** The brief. The rules are stated, but the checks in `checkDraft` are what enforce them. */
+export function tailorPrompt(lead, sources) {
+    const l = lead.lead;
+    const job = [
+        `Title: ${l.title}`,
+        l.company ? `Company: ${l.company}` : "",
+        l.location ? `Location: ${l.location}` : "",
+        lead.leadUrl ? `URL: ${lead.leadUrl}` : "",
+        l.match_rationale ? `Why it matched: ${l.match_rationale}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const blocks = sources.map((s) => `<source role="${s.role}">\n${s.text}\n</source>`).join("\n\n");
+    return [
+        "You tailor a job application for the owner of this machine: a résumé variant and a cover letter for ONE job.",
+        "You have no tools. Everything you may use is below. Answer with ONE JSON object and nothing else.",
+        "",
+        "<job>",
+        job,
+        "</job>",
+        "",
+        blocks,
+        "",
+        "Rules — these are checked mechanically, and a draft that breaks one is discarded:",
+        "- Use ONLY facts stated in the sources. Never invent or embellish an employer, title, qualification, date, skill, metric, work authorisation, salary expectation or answer.",
+        '- For EVERY factual claim about the owner in either document, add an entry to "claims" with the claim, the source role it comes from, and a short VERBATIM quote copied exactly from that source.',
+        "- Every year, email address and phone number you write must appear in the sources.",
+        "- Reword and reorder to fit the job; do not add what the sources do not say. Leave out what does not fit.",
+        '- If something the application needs is missing or uncertain, do not guess: answer {"status":"needs_human","questions":["…"]} instead.',
+        "",
+        "Answer shape when you can do it:",
+        '{"status":"ready","resume_markdown":"…","cover_letter_markdown":"…","claims":[{"text":"…","source":"resume","quote":"…"}]}',
+    ].join("\n");
+}
+/** The CLI's answer: the first JSON object in its final text, fences and prose around it ignored. */
+export function parseDraft(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const v = JSON.parse(text.slice(start, end + 1));
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Case, whitespace, quote-style and dash-style insensitive — so a faithful quote is never failed on typography. */
+export function normalize(s) {
+    return s
+        .toLowerCase()
+        .replace(/[‘’]/g, "'")
+        .replace(/[“”]/g, '"')
+        .replace(/[–—]/g, "-")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const YEAR = /\b(?:19|20)\d{2}\b/g;
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+/** Nine digits or more, so a year range ("2019 - 2021") is not read as a phone number. */
+const PHONE = /\+?\d[\d\s().-]{7,}\d/g;
+const digits = (s) => s.replace(/\D/g, "");
+/**
+ * Check the CLI's draft against the sources. Questions name WHAT to confirm, bounded, and are
+ * returned only to the owner's own record — never to a trace.
+ */
+export function checkDraft(draft, sources) {
+    if (!draft)
+        return { ok: false, reason: "uncertain_claim", questions: ["The CLI did not return a readable draft. Run it again, or check the source files."], claims: 0, unmatched: 0 };
+    if (draft.status === "needs_human") {
+        const qs = (Array.isArray(draft.questions) ? draft.questions : []).filter((q) => typeof q === "string" && q.trim() !== "").map((q) => q.trim());
+        return { ok: false, reason: "missing_information", questions: qs.length ? qs : ["The CLI needs more information but did not say what."], claims: 0, unmatched: 0 };
+    }
+    const resume = typeof draft.resume_markdown === "string" ? draft.resume_markdown.trim() : "";
+    const coverLetter = typeof draft.cover_letter_markdown === "string" ? draft.cover_letter_markdown.trim() : "";
+    const claims = Array.isArray(draft.claims) ? draft.claims : [];
+    if (draft.status !== "ready" || !resume || !coverLetter || !claims.length) {
+        return { ok: false, reason: "uncertain_claim", questions: ["The draft was incomplete (missing a document or its source citations). Run it again."], claims: claims.length, unmatched: 0 };
+    }
+    const byRole = new Map(sources.map((s) => [s.role, normalize(s.text)]));
+    const all = normalize(sources.map((s) => s.text).join("\n"));
+    const questions = [];
+    let unmatched = 0;
+    const flag = (question) => {
+        unmatched++;
+        if (questions.length < 20)
+            questions.push(question);
+    };
+    for (const raw of claims) {
+        const c = (raw && typeof raw === "object" ? raw : {});
+        const quote = typeof c.quote === "string" ? normalize(c.quote) : "";
+        const src = typeof c.source === "string" ? byRole.get(c.source) : undefined;
+        if (quote.length >= 3 && src?.includes(quote))
+            continue;
+        const claim = typeof c.text === "string" ? c.text.trim() : "";
+        flag(`Confirm or correct: “${claim.slice(0, 200) || "(an unnamed claim)"}” — no matching text was found in your ${typeof c.source === "string" ? c.source : "sources"}.`);
+    }
+    const text = `${resume}\n${coverLetter}`;
+    const sourceDigits = digits(sources.map((s) => s.text).join("\n"));
+    for (const y of new Set(text.match(YEAR) ?? []))
+        if (!all.includes(y))
+            flag(`Confirm the year ${y} — it does not appear in your sources.`);
+    for (const e of new Set(text.match(EMAIL) ?? []))
+        if (!all.includes(e.toLowerCase()))
+            flag("Confirm the email address in the draft — it does not appear in your sources.");
+    // Nine digits or more, so a year range ("2019 - 2021") is not read as a phone number.
+    for (const p of new Set(text.match(PHONE) ?? []))
+        if (digits(p).length >= 9 && !sourceDigits.includes(digits(p)))
+            flag("Confirm the phone number in the draft — it does not appear in your sources.");
+    if (unmatched)
+        return { ok: false, reason: "uncertain_claim", questions, claims: claims.length, unmatched };
+    return { ok: true, resume, coverLetter, claims: claims.length };
+}