@proagentstore/cli 0.4.77 → 0.4.78

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 };
+}

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

@@ -0,0 +1,418 @@
+/**
+ * Local artifact generation on the runner (#956) — the Application Tailor's hands.
+ *
+ * One run = one Codex or Claude Code process, signed in on this machine, that turns ONE approved
+ * job lead plus the owner's own source files into a tailored résumé and cover letter. No browser,
+ * no repository, no provider API key. The runtime, not the CLI, does every read and every write:
+ *
+ *  - reads: only the configured source files, each resolved on the real disk inside the workspace
+ *    (`..`, absolute paths and symlinks out are refused), and never under `applications/`, where
+ *    generated material — this instance's or another's — lives;
+ *  - writes: only new files in a fresh `<workspace>/applications/<leadId>/<runId>/`, created
+ *    exclusively (`wx`), so a master source is never rewritten and two runs never share a folder;
+ *  - the trace carries handles (role, owner-visible path, sha256, byte count), never content.
+ *
+ * A missing source, an unusable workspace, a CLI that is not signed in, an API key in the env, a
+ * malformed lead or a draft whose claims do not check out ends the run `needs_human` — a pause
+ * the owner resolves — never a plausible guess written to disk.
+ *
+ * Runs live in memory, like local browser runs: a restart loses them and `status` answers 404,
+ * which PAGS reads as "the runner lost this run". Generated folders carry a manifest with their
+ * retention date; a later run on the same workspace removes those past it.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { RunnerInputError } from "../errors.js";
+import { redactText, secretEnvValues } from "../local-browser/contract.js";
+import { resolveWorkspacePath } from "../local-browser/runtime.js";
+import { LOCAL_ARTIFACT_AUTH_MODES, LOCAL_ARTIFACT_CAPS, LOCAL_ARTIFACT_ENGINES, LOCAL_ARTIFACT_SOURCE_ROLES, LOCAL_ARTIFACT_TASK_TYPE, PATH_SEGMENT, REQUIRED_SOURCE_ROLES, isHomeRelative, isWorkspaceRelative, parseLocalArtifactLead, } from "./contract.js";
+import { buildArtifactEngineSpec, checkDraft, finalText, missingLogin, observedArtifactAuth, parseDraft, tailorPrompt } from "./engine.js";
+/** The manifest in every generated folder — what retention reads, and proof the folder is ours. */
+export const ARTIFACT_MANIFEST = ".pags-artifact.json";
+const MAX_EVENTS = 200;
+const OUTPUT_LINES = 400;
+const SAFE_ID = /^[A-Za-z0-9_.:-]{1,300}$/;
+const DAY_MS = 86_400_000;
+const intIn = (v, min, max) => (typeof v === "number" && Number.isInteger(v) && v >= min && v <= max ? v : null);
+/** The envelope, validated at the runner's boundary. A bad LEAD is not thrown: it pauses the run. */
+export function parseArtifactEnvelope(raw) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    const bad = (what) => new RunnerInputError(`Invalid local artifact task: ${what}`);
+    if (o.type !== LOCAL_ARTIFACT_TASK_TYPE)
+        throw bad(`type must be ${LOCAL_ARTIFACT_TASK_TYPE}`);
+    if (typeof o.runId !== "string" || !PATH_SEGMENT.test(o.runId))
+        throw bad("runId is required");
+    for (const k of ["requestId", "instanceId"])
+        if (typeof o[k] !== "string" || !SAFE_ID.test(o[k]))
+            throw bad(`${k} is required`);
+    if (!LOCAL_ARTIFACT_ENGINES.includes(o.engine))
+        throw bad("engine must be claude or codex");
+    if (!LOCAL_ARTIFACT_AUTH_MODES.includes(o.authMode))
+        throw bad("authMode must be machine or subscription — a provider API key is never used");
+    if (typeof o.workspace !== "string" || !isHomeRelative(o.workspace))
+        throw bad('workspace must be a folder written "~/…"');
+    if (!Array.isArray(o.sources) || o.sources.length > LOCAL_ARTIFACT_CAPS.sources)
+        throw bad("sources must be a list");
+    const sources = [];
+    for (const s of o.sources) {
+        const r = (s && typeof s === "object" ? s : {});
+        if (!LOCAL_ARTIFACT_SOURCE_ROLES.includes(r.role) || typeof r.path !== "string" || !isWorkspaceRelative(r.path))
+            throw bad("each source needs a role and a path inside the workspace");
+        if (r.path.split("/")[0] === "applications")
+            throw bad("a source may not be inside applications/, where generated material lives");
+        if (sources.some((x) => x.role === r.role))
+            throw bad(`source ${String(r.role)} is listed twice`);
+        sources.push({ role: r.role, path: r.path });
+    }
+    const p = (o.policy && typeof o.policy === "object" ? o.policy : {});
+    const retainDays = intIn(p.retainDays, 0, 3650);
+    const maxMinutes = intIn(p.maxMinutes, 1, 60);
+    const maxConcurrent = intIn(p.maxConcurrent, 1, 3);
+    if (retainDays === null || maxMinutes === null || maxConcurrent === null)
+        throw bad("policy limits are out of range");
+    const lead = parseLocalArtifactLead(o.lead);
+    return {
+        type: LOCAL_ARTIFACT_TASK_TYPE,
+        runId: o.runId,
+        requestId: o.requestId,
+        instanceId: o.instanceId,
+        engine: o.engine,
+        authMode: o.authMode,
+        workspace: o.workspace,
+        sources,
+        policy: { retainDays, maxMinutes, maxConcurrent },
+        ...("lead" in lead ? { lead: lead.lead } : { lead: null, leadError: lead.error }),
+    };
+}
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/** A source file resolved on the real disk, strictly inside the workspace. */
+function resolveSource(workspace, rel) {
+    const real = realpathSync(resolve(workspace, rel));
+    if (!real.startsWith(workspace + sep))
+        throw new Error("outside the workspace");
+    if (real.slice(workspace.length + 1).split(sep)[0] === "applications")
+        throw new Error("inside applications/");
+    if (!statSync(real).isFile())
+        throw new Error("not a file");
+    return real;
+}
+class Pause extends Error {
+    reason;
+    questions;
+    constructor(reason, questions) {
+        super(reason);
+        this.reason = reason;
+        this.questions = questions;
+    }
+}
+export class LocalArtifactRuntime {
+    deps;
+    runs = new Map();
+    root;
+    now;
+    spawn;
+    retentionMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.root = join(deps.dataDir, "local-artifact");
+        this.now = deps.now ?? Date.now;
+        this.spawn = deps.spawn ?? nodeSpawn;
+        this.retentionMs = deps.retentionMs ?? DAY_MS;
+    }
+    /** Start a run. A requestId already held for the instance returns that run instead. */
+    start(raw) {
+        const envelope = parseArtifactEnvelope(raw);
+        this.sweep();
+        const same = [...this.runs.values()].find((r) => r.envelope.instanceId === envelope.instanceId && r.envelope.requestId === envelope.requestId);
+        if (same)
+            return { runId: same.envelope.runId, taskId: same.envelope.runId, status: same.state, existing: true };
+        if (this.runs.has(envelope.runId))
+            throw new RunnerInputError(`Run ${envelope.runId} already exists with another requestId`, 409);
+        const active = [...this.runs.values()].filter((r) => r.envelope.instanceId === envelope.instanceId && r.state !== "ended").length;
+        if (active >= envelope.policy.maxConcurrent)
+            throw new RunnerInputError(`This machine is already tailoring ${active} application(s) for this agent (limit ${envelope.policy.maxConcurrent}).`, 409);
+        const scratch = join(this.root, envelope.instanceId.replace(/[^A-Za-z0-9_-]/g, "_"), envelope.runId);
+        mkdirSync(scratch, { recursive: true });
+        const run = { envelope, scratch, state: "running", events: [], seq: 0, output: [], secrets: secretEnvValues(process.env), engineAuth: "unknown", cancelled: false, timedOut: false };
+        this.runs.set(envelope.runId, run);
+        void this.launch(run).catch((err) => {
+            if (err instanceof Pause)
+                this.pauseEnd(run, err.reason, err.questions);
+            else
+                this.end(run, { outcome: "failed", error: err instanceof Error ? err.message : String(err) });
+        });
+        return { runId: envelope.runId, taskId: envelope.runId, status: run.state, existing: false };
+    }
+    async launch(run) {
+        const e = run.envelope;
+        if (!e.lead)
+            throw new Pause("malformed_lead", [`The approved lead could not be read (${e.leadError ?? "malformed"}). Re-approve it from the Scout.`]);
+        const lead = e.lead;
+        let workspace;
+        try {
+            workspace = resolveWorkspacePath(e.workspace, this.deps.homeDir ?? homedir());
+        }
+        catch (err) {
+            throw new Pause("workspace_unavailable", [`The workspace ${e.workspace} cannot be used: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        this.sweepArtifacts(run, workspace);
+        // Sources: read by the runtime, hashed, handed to the CLI in its prompt. Content never leaves this function except into the prompt.
+        const texts = [];
+        const hashes = [];
+        const missing = [];
+        for (const s of e.sources) {
+            const shown = `${e.workspace}/${s.path}`;
+            try {
+                const file = resolveSource(workspace, s.path);
+                const buf = readFileSync(file);
+                if (buf.length > LOCAL_ARTIFACT_CAPS.sourceBytes)
+                    throw new Error(`larger than ${LOCAL_ARTIFACT_CAPS.sourceBytes / 1024} KB`);
+                if (!buf.length)
+                    throw new Error("empty");
+                texts.push({ role: s.role, text: buf.toString("utf8") });
+                const hash = { role: s.role, path: shown, sha256: sha256(buf), bytes: buf.length };
+                hashes.push(hash);
+                this.emit(run, { type: "source.read", detail: hash });
+            }
+            catch (err) {
+                this.emit(run, { type: "source.missing", detail: { role: s.role, path: shown } });
+                missing.push(`Your ${s.role} at ${shown} could not be read (${err instanceof Error && !/ENOENT/.test(err.message) ? err.message : "not found"}). Add it, or choose another file in the Application Tailor settings.`);
+            }
+        }
+        for (const role of REQUIRED_SOURCE_ROLES) {
+            if (!e.sources.some((s) => s.role === role))
+                missing.push(`No ${role} source is configured. Choose one in the Application Tailor settings.`);
+        }
+        if (missing.length)
+            throw new Pause("missing_source", missing);
+        const outRel = `applications/${lead.leadId}/${e.runId}`;
+        const outDir = join(workspace, "applications", lead.leadId, e.runId);
+        try {
+            mkdirSync(join(workspace, "applications", lead.leadId), { recursive: true });
+            mkdirSync(outDir); // exclusive: a run never writes into a folder it did not create
+            if (!realpathSync(outDir).startsWith(workspace + sep))
+                throw new Error("the output folder resolves outside the workspace");
+        }
+        catch (err) {
+            throw new Pause("workspace_unavailable", [`Cannot create ${e.workspace}/${outRel}: ${err instanceof Error ? err.message : String(err)}`]);
+        }
+        const spec = buildArtifactEngineSpec({ engine: e.engine, authMode: e.authMode, prompt: tailorPrompt(lead, texts) });
+        run.secrets = secretEnvValues({ ...process.env, ...spec.env });
+        run.engineAuth = observedArtifactAuth(e.engine, spec.env);
+        this.emit(run, { type: "engine.auth_checked", detail: { engine: e.engine, authMode: e.authMode, engineAuth: run.engineAuth } });
+        if (run.engineAuth === "api-key") {
+            rmdirSync(outDir);
+            throw new Pause("api_key_refused", ["A provider API key would reach the CLI. The Application Tailor runs on your machine's sign-in only — remove the key from the runner's environment."]);
+        }
+        const child = this.spawn(spec.command, spec.args, { cwd: run.scratch, env: spec.env, stdio: ["ignore", "pipe", "pipe"] });
+        run.child = child;
+        this.emit(run, { type: "engine.started", detail: { engine: e.engine } });
+        let buf = "";
+        const keep = (chunk) => {
+            buf += chunk.toString();
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            for (const line of lines)
+                if (line.trim())
+                    run.output.push(line.slice(0, 200_000));
+            if (run.output.length > OUTPUT_LINES)
+                run.output.splice(0, run.output.length - OUTPUT_LINES);
+        };
+        child.stdout?.on("data", keep);
+        child.stderr?.on("data", keep);
+        child.on("error", (err) => {
+            this.removeIfEmpty(outDir);
+            this.end(run, { outcome: "failed", error: err.code === "ENOENT" ? `The ${e.engine === "claude" ? "Claude Code" : "Codex"} CLI is not installed on this machine (\`${spec.command}\` was not found).` : err.message });
+        });
+        child.on("close", (code) => {
+            if (buf.trim())
+                run.output.push(buf);
+            this.emit(run, { type: "engine.ended", detail: { exitCode: code ?? -1 } });
+            try {
+                this.finish(run, code ?? -1, { workspace, outDir, outRel, lead, hashes, texts });
+            }
+            catch (err) {
+                this.removeIfEmpty(outDir);
+                this.end(run, { outcome: "failed", error: err instanceof Error ? err.message : String(err) });
+            }
+        });
+        run.timer = setTimeout(() => {
+            run.timedOut = true;
+            this.kill(run);
+        }, e.policy.maxMinutes * 60_000);
+        run.timer.unref?.();
+    }
+    /** The CLI exited: check its draft against the sources, and only then write the artifacts. */
+    finish(run, code, ctx) {
+        if (run.state === "ended")
+            return;
+        const e = run.envelope;
+        const output = run.output.join("\n");
+        if (run.cancelled || run.timedOut) {
+            this.removeIfEmpty(ctx.outDir);
+            this.end(run, { outcome: "failed", error: run.cancelled ? "Cancelled by the owner" : `Stopped at the ${e.policy.maxMinutes}-minute limit.` });
+            return;
+        }
+        const text = finalText(e.engine, run.output);
+        if (!text && missingLogin(e.engine, output)) {
+            this.removeIfEmpty(ctx.outDir);
+            run.engineAuth = "missing_login";
+            this.pauseEnd(run, "engine_not_signed_in", [e.engine === "claude" ? "Sign in to Claude Code on this machine (run `claude`, then /login), then retry." : "Sign in to Codex on this machine (`codex login`), then retry."]);
+            return;
+        }
+        if (code !== 0 && !text) {
+            this.removeIfEmpty(ctx.outDir);
+            this.end(run, { outcome: "failed", error: `The ${e.engine} CLI exited with code ${code}: ${run.output.slice(-5).join("\n").slice(-800)}` });
+            return;
+        }
+        const check = checkDraft(parseDraft(text), ctx.texts);
+        this.emit(run, { type: "claims.checked", detail: { total: check.claims, unmatched: check.ok ? 0 : check.unmatched } });
+        if (!check.ok) {
+            this.removeIfEmpty(ctx.outDir);
+            this.pauseEnd(run, check.reason, check.questions);
+            return;
+        }
+        const at = new Date(this.now()).toISOString();
+        const artifacts = [];
+        for (const [kind, name, body] of [
+            ["resume", "resume.md", check.resume],
+            ["cover_letter", "cover-letter.md", check.coverLetter],
+        ]) {
+            const content = `${body}\n`;
+            writeFileSync(join(ctx.outDir, name), content, { flag: "wx", mode: 0o600 });
+            const file = { kind, path: `${e.workspace}/${ctx.outRel}/${name}`, sha256: sha256(content), bytes: Buffer.byteLength(content) };
+            artifacts.push(file);
+            this.emit(run, { type: "artifact.written", detail: { ...file } });
+        }
+        const profileVersion = sha256(ctx.hashes.map((h) => `${h.role}:${h.sha256}`).sort().join("\n")).slice(0, 16);
+        const retainUntil = e.policy.retainDays > 0 ? this.now() + e.policy.retainDays * DAY_MS : null;
+        writeFileSync(join(ctx.outDir, ARTIFACT_MANIFEST), JSON.stringify({ runId: e.runId, instanceId: e.instanceId, leadId: ctx.lead.leadId, eventId: ctx.lead.eventId, generatedAt: at, retainUntil, profileVersion, artifacts, sources: ctx.hashes }, null, 2), { flag: "wx", mode: 0o600 });
+        this.end(run, { outcome: "completed", artifacts, sourceHashes: ctx.hashes, profileVersion, generatedAt: at });
+    }
+    /** Retention: remove generated folders whose manifest says they are past their date. Only ours — a folder without a manifest is the owner's. */
+    sweepArtifacts(run, workspace) {
+        const apps = join(workspace, "applications");
+        if (!existsSync(apps))
+            return;
+        let removed = 0;
+        for (const lead of readdirSync(apps)) {
+            const leadDir = join(apps, lead);
+            if (!statSync(leadDir).isDirectory())
+                continue;
+            for (const runId of readdirSync(leadDir)) {
+                const manifest = join(leadDir, runId, ARTIFACT_MANIFEST);
+                if (!existsSync(manifest))
+                    continue;
+                try {
+                    const m = JSON.parse(readFileSync(manifest, "utf8"));
+                    if (typeof m.retainUntil === "number" && m.retainUntil < this.now()) {
+                        rmSync(join(leadDir, runId), { recursive: true, force: true });
+                        removed++;
+                    }
+                }
+                catch {
+                    // An unreadable manifest is left alone: deleting on a guess is the one thing retention must not do.
+                }
+            }
+            this.removeIfEmpty(leadDir);
+        }
+        if (removed)
+            this.emit(run, { type: "retention.swept", detail: { removed } });
+    }
+    removeIfEmpty(dir) {
+        try {
+            if (existsSync(dir) && readdirSync(dir).length === 0)
+                rmdirSync(dir);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    emit(run, ev) {
+        if (run.events.length >= MAX_EVENTS)
+            return;
+        run.events.push({ ...ev, at: new Date(this.now()).toISOString(), seq: ++run.seq });
+    }
+    pauseEnd(run, reason, questions) {
+        this.emit(run, { type: "run.needs_human", detail: { reason, count: questions.length } });
+        this.end(run, { outcome: "needs_human", blockReason: reason, questions });
+    }
+    end(run, r) {
+        if (run.state === "ended")
+            return;
+        if (run.timer)
+            clearTimeout(run.timer);
+        run.state = "ended";
+        run.endedAt = this.now();
+        run.result = {
+            runId: run.envelope.runId,
+            outcome: r.outcome,
+            artifacts: r.artifacts ?? [],
+            sourceHashes: r.sourceHashes ?? [],
+            profileVersion: r.profileVersion ?? null,
+            engineAuth: run.engineAuth,
+            traceId: run.envelope.runId,
+            ...(r.generatedAt ? { generatedAt: r.generatedAt } : {}),
+            ...(r.outcome === "needs_human" ? { blockReason: r.blockReason, questions: (r.questions ?? []).map((q) => redactText(q, run.secrets)) } : {}),
+            // CLI output becomes this text, and a CLI prints whatever it was given: redacted before it is kept.
+            ...(r.outcome === "failed" ? { error: redactText((r.error ?? "The run failed without a reason.").slice(0, 1000), run.secrets) } : {}),
+        };
+        if (run.child && run.child.exitCode === null)
+            this.kill(run);
+    }
+    kill(run) {
+        const child = run.child;
+        if (!child || child.exitCode !== null)
+            return;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+        }, 5_000).unref?.();
+    }
+    get(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new RunnerInputError(`No local artifact run ${runId} on this runner (it may have restarted)`, 404);
+        return run;
+    }
+    status(raw) {
+        const o = (raw && typeof raw === "object" ? raw : {});
+        const run = this.get(String(o.runId ?? ""));
+        const after = typeof o.afterSeq === "number" && o.afterSeq > 0 ? o.afterSeq : 0;
+        return { runId: run.envelope.runId, state: run.state, events: run.events.filter((e) => e.seq > after), lastSeq: run.seq, ...(run.result ? { result: run.result } : {}) };
+    }
+    cancel(raw) {
+        const runId = String(raw?.runId ?? "");
+        const run = this.get(runId);
+        if (run.state !== "ended") {
+            run.cancelled = true;
+            if (run.child && run.child.exitCode === null)
+                this.kill(run);
+            else
+                this.end(run, { outcome: "failed", error: "Cancelled by the owner" });
+        }
+        return { runId, state: run.state };
+    }
+    /** Drop ended runs past retention with their scratch folders. Generated artifacts are swept by their own manifest, not here. */
+    sweep() {
+        const cutoff = this.now() - this.retentionMs;
+        for (const [id, run] of this.runs) {
+            if (run.state === "ended" && (run.endedAt ?? 0) < cutoff) {
+                rmSync(run.scratch, { recursive: true, force: true });
+                this.runs.delete(id);
+            }
+        }
+    }
+    closeAll() {
+        for (const run of this.runs.values()) {
+            if (run.state !== "ended") {
+                run.cancelled = true;
+                this.end(run, { outcome: "failed", error: "The runner shut down during the run" });
+            }
+        }
+    }
+}

package/dist/browser-runner/runner.js

@@ -14,6 +14,8 @@ import { RunnerStore } from "./store.js";
 import { CodingRuntime } from "./coding/runtime.js";
 import { LocalBrowserRuntime } from "./local-browser/runtime.js";
 import { LOCAL_BROWSER_TASK_TYPE } from "./local-browser/contract.js";
+import { LocalArtifactRuntime } from "./local-artifact/runtime.js";
+import { LOCAL_ARTIFACT_TASK_TYPE } from "./local-artifact/contract.js";
 import { WORKFLOW_DRIVEN_TASKS } from "./task-types.js";
 /** True for a plain object. */
 function isRecord(value) {
@@ -77,6 +79,8 @@ export class LocalRunner {
     coding;
     /** Local CLI browser research (#944): a signed-in Codex / Claude Code CLI researching through the policy bridge. */
     localBrowser;
+    /** Local artifact generation (#956): the Application Tailor's résumé + cover letter, from the owner's own files. */
+    localArtifact;
     /** This runner's own local URL, once the server listens — the bridge forwarder calls back to it. */
     selfUrl = null;
     /** Live human-takeover sessions, keyed by task id (the page is kept alive). */
@@ -99,6 +103,7 @@ export class LocalRunner {
                 return { tools: mcp, stop: () => mcp.stop() };
             },
         });
+        this.localArtifact = new LocalArtifactRuntime({ dataDir: config.dataDir });
         // Tasks paused/running on a previous process are orphaned now — their
         // pages and takeover sessions are gone. Fail them so the board is clean.
         const expired = this.store.expireInFlightTasks();
@@ -113,7 +118,7 @@ export class LocalRunner {
             runtimePlane: "pags",
             runnerRole: "tool-executor",
             capabilities: [...CAPABILITIES, ...CodingRuntime.capabilities()],
-            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", LOCAL_BROWSER_TASK_TYPE, ...CodingRuntime.taskTypes()],
+            taskTypes: ["echo", "browser.open", "job.apply_agent", "site_builder_runtime", LOCAL_BROWSER_TASK_TYPE, LOCAL_ARTIFACT_TASK_TYPE, ...CodingRuntime.taskTypes()],
             approvalRequiredFor: [...APPROVAL_REQUIRED_TASKS],
         };
     }
@@ -250,6 +255,7 @@ export class LocalRunner {
      */
     async close() {
         this.localBrowser.closeAll();
+        this.localArtifact.closeAll();
         try {
             this.coding.closeAll();
         }

package/dist/browser-runner/server.js

@@ -177,6 +177,16 @@ async function route(runner, req, res) {
     if (req.method === "POST" && path === "/local-browser/cancel") {
         return json(res, 200, runner.localBrowser.cancel(await readJson(req)));
     }
+    // Local artifact generation (#956) — the same PULL shape: run, status, cancel.
+    if (req.method === "POST" && path === "/local-artifact/run") {
+        return json(res, 202, runner.localArtifact.start(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-artifact/status") {
+        return json(res, 200, runner.localArtifact.status(await readJson(req)));
+    }
+    if (req.method === "POST" && path === "/local-artifact/cancel") {
+        return json(res, 200, runner.localArtifact.cancel(await readJson(req)));
+    }
     if (req.method === "POST" && path === "/coding/start") {
         const b = await readJson(req);
         return json(res, 200, runner.coding.start(b));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.77",
+  "version": "0.4.78",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",