@vendoai/vendo 0.4.0

package/dist/cli/extract/apply.js

@@ -0,0 +1,123 @@
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { vendoSync } from "@vendoai/actions";
+import { detectDepVersions } from "../dep-versions.js";
+import { detectFramework } from "../framework.js";
+import { applyDraft, reportApplied } from "./extraction.js";
+import { parseDraft } from "./harness.js";
+import { staticToolSchema } from "./stages.js";
+import { consoleOutput, readOptional, withCommandRun, } from "../shared.js";
+function describeError(error) {
+    if (error instanceof z.ZodError) {
+        return error.issues
+            .slice(0, 5)
+            .map((issue) => `${issue.path.join(".") || "draft"}: ${issue.message}`)
+            .join("; ");
+    }
+    return error instanceof Error ? error.message : "unknown error";
+}
+export async function runExtractApply(options) {
+    const output = options.output ?? consoleOutput;
+    const root = resolve(options.targetDir);
+    const started = Date.now();
+    return withCommandRun({
+        command: "extract",
+        root,
+        ...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
+    }, (failure, telemetry) => extractApply(options, output, root, started, failure, telemetry));
+}
+async function extractApply(options, output, root, started, failure, telemetry) {
+    const toolsRaw = await readOptional(join(root, ".vendo", "tools.json"));
+    if (toolsRaw === null) {
+        failure.failedStep = "tools";
+        output.error("No .vendo/tools.json here — run `vendo init` first, then apply the draft.");
+        return 1;
+    }
+    let tools;
+    try {
+        tools = z.object({ tools: z.array(staticToolSchema) }).parse(JSON.parse(toolsRaw)).tools;
+    }
+    catch (error) {
+        failure.failedStep = "tools";
+        output.error(`.vendo/tools.json is unreadable (${describeError(error)}) — run \`vendo sync\` and try again.`);
+        return 1;
+    }
+    // readOptional only maps ENOENT to null — a directory (EISDIR) or a
+    // permission error must still exit honestly, not as an uncaught crash.
+    let draftRaw;
+    try {
+        draftRaw = await readOptional(resolve(options.apply));
+    }
+    catch (error) {
+        failure.failedStep = "draft";
+        output.error(`Draft file unreadable: ${options.apply} (${describeError(error)})`);
+        return 1;
+    }
+    if (draftRaw === null) {
+        failure.failedStep = "draft";
+        output.error(`Draft file not found: ${options.apply}`);
+        return 1;
+    }
+    let draft;
+    try {
+        draft = parseDraft(draftRaw);
+    }
+    catch (error) {
+        failure.failedStep = "draft";
+        output.error(`Draft rejected — it must match the aiPolish.draftSchema from \`vendo init --agent\` (${describeError(error)}).`);
+        return 1;
+    }
+    // applyDraft throws on a hand-edited overrides.json it cannot parse — the
+    // same honest-exit contract applies, never an unhandled stack trace.
+    let applied;
+    try {
+        applied = await applyDraft({
+            root,
+            draft,
+            tools,
+            ...(options.force === undefined ? {} : { force: options.force }),
+        });
+    }
+    catch (error) {
+        failure.failedStep = "apply";
+        output.error(`Could not apply the draft (${describeError(error)}) — check .vendo/overrides.json and re-apply.`);
+        return 1;
+    }
+    // Same as init's built-in pass: a successful apply re-syncs so tools.json
+    // reflects the polish immediately.
+    try {
+        const resynced = await (options.sync ?? vendoSync)({ root, out: join(root, ".vendo") });
+        for (const warning of resynced.warnings)
+            output.error(`warning: ${warning}`);
+    }
+    catch (error) {
+        failure.failedStep = "resync";
+        output.error(`Draft applied, but re-sync failed (${describeError(error)}) — run \`vendo sync\` to refresh tools.json.`);
+        return 1;
+    }
+    reportApplied({ output, applied, briefDrafted: applied.briefWritten });
+    // Result metrics (counts and enums only; TELEMETRY.md extract_completed).
+    // Guarded like the wrapper: telemetry can never change the exit code.
+    try {
+        const framework = await detectFramework(root);
+        // staticToolSchema strips bindings — count route tools off the raw file.
+        const bindings = JSON.parse(toolsRaw).tools ?? [];
+        const routeCount = bindings.filter((tool) => tool.binding?.kind === "route").length;
+        const versions = await detectDepVersions(root, framework);
+        await telemetry.track("extract_completed", {
+            framework,
+            // route-scan today; "zod" reserved for a future oracle-backed detect.
+            method: routeCount > 0 ? "route-scan" : "none",
+            routeCount,
+            toolCount: tools.length,
+            ok: true,
+            durationMs: Date.now() - started,
+            ...(versions.frameworkVersion === undefined ? {} : { frameworkVersion: versions.frameworkVersion }),
+            ...(versions.zodVersion === undefined ? {} : { zodVersion: versions.zodVersion }),
+        });
+    }
+    catch {
+        // Intentional silent failure.
+    }
+    return 0;
+}

package/dist/cli/extract/claude-cli-harness.d.ts

@@ -0,0 +1,18 @@
+import type { ExtractionHarness } from "./harness.js";
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+type Exec = (args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<ExecResult>;
+export interface ClaudeCliHarnessOptions {
+    /** Test seams. */
+    probeBinary?: () => Promise<boolean>;
+    probeLogin?: () => Promise<boolean>;
+    exec?: Exec;
+}
+export declare function claudeCliHarness(options?: ClaudeCliHarnessOptions): ExtractionHarness;
+export {};

package/dist/cli/extract/claude-cli-harness.js

@@ -0,0 +1,132 @@
+import { execFile } from "node:child_process";
+import { composeGatewayFuel, hasOwnAnthropicEnvOverride } from "./gateway-fuel.js";
+/**
+ * Fallback extraction harness: the `claude` CLI already on the dev's PATH,
+ * driven headless (`-p`/print mode) with READ-ONLY code tools (Read/Glob/
+ * Grep) over the host root. Credential = the dev's Claude Code login, or
+ * their ANTHROPIC_API_KEY — same model as the SDK harness, just spawned as a
+ * subprocess instead of imported as a module. This is the path that works
+ * without shipping the Claude Agent SDK's ~245MB bundled native binary
+ * (see claude-harness.ts) — most devs doing this already have Claude Code
+ * installed for their own use.
+ *
+ * Isolation: `--setting-sources ""` (never inherit the dev's personal Claude
+ * Code settings/hooks — same intent as claude-harness.ts's
+ * `settingSources: []`), read-only tool allowlist, no shell/web/write surface.
+ *
+ * Gateway fuel: when the dev has none of ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN,
+ * CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_BASE_URL (the corporate-gateway/custom-
+ * endpoint path), or a Claude Code login, but VENDO_API_KEY is set, the rung
+ * runs on Vendo Cloud's model gateway instead of degrading to unavailable
+ * (see gateway-fuel.ts). Own credential always wins — this never overrides a
+ * working ANTHROPIC_API_KEY, login, or any of those env vars.
+ */
+const ALLOWED_TOOLS = ["Read", "Glob", "Grep"];
+const DISALLOWED_TOOLS = [
+    "Bash", "Write", "Edit", "WebFetch", "WebSearch", "Task",
+    "TodoWrite", "NotebookEdit", "KillShell", "BashOutput",
+];
+const PROBE_TIMEOUT_MS = 5_000;
+// Extraction stages can run for minutes over a real codebase.
+const RUN_TIMEOUT_MS = 10 * 60 * 1_000;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+function execClaude(args, options) {
+    return new Promise((resolve) => {
+        execFile("claude", args, { cwd: options.cwd, env: options.env, timeout: RUN_TIMEOUT_MS, maxBuffer: MAX_BUFFER_BYTES }, (error, stdout, stderr) => {
+            const code = error === null ? 0 : typeof error.code === "number" ? error.code : 1;
+            resolve({ stdout, stderr, code });
+        });
+    });
+}
+/** Cheap presence check: does `claude` resolve and run at all? */
+function probeClaudeBinary() {
+    return new Promise((resolve) => {
+        execFile("claude", ["--version"], { timeout: PROBE_TIMEOUT_MS }, (error) => resolve(error === null));
+    });
+}
+/** `claude auth status` prints JSON with a `loggedIn` boolean. */
+function probeClaudeLogin() {
+    return new Promise((resolve) => {
+        execFile("claude", ["auth", "status"], { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+            if (error !== null)
+                return resolve(false);
+            try {
+                resolve(JSON.parse(stdout).loggedIn === true);
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    });
+}
+function isSet(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Gateway fuel only ever matters when VENDO_API_KEY is set — skip the
+ *  (async) login probe entirely otherwise, so the own-credential path never
+ *  pays for or is affected by this check. Env-based own-credential checks
+ *  (ANTHROPIC_API_KEY, then OWN_CREDENTIAL_ENV_VARS) run before the probe
+ *  too, since they're cheap and the probe is a subprocess spawn. */
+async function resolveGatewayFuelOverlay(env, probeLogin) {
+    const cloudKey = env["VENDO_API_KEY"];
+    if (!isSet(cloudKey))
+        return null;
+    const ownCredentialAvailable = isSet(env["ANTHROPIC_API_KEY"])
+        || hasOwnAnthropicEnvOverride(env)
+        || (await probeLogin());
+    return composeGatewayFuel({ env, ownCredentialAvailable });
+}
+export function claudeCliHarness(options = {}) {
+    const hasBinary = options.probeBinary ?? probeClaudeBinary;
+    const probe = options.probeLogin ?? probeClaudeLogin;
+    const exec = options.exec ?? execClaude;
+    return {
+        id: "claude-cli",
+        async availability({ env }) {
+            if (!(await hasBinary()))
+                return null;
+            // The child spawns with {...process.env, ...input.env} (see run()), so
+            // credential checks and labels must see that SAME merged view: a
+            // programmatic caller passing a partial env (say VENDO_API_KEY only)
+            // while ambient process.env carries an ANTHROPIC_AUTH_TOKEN really
+            // runs on that ambient token — labeling (or fueling) it as the Vendo
+            // Cloud key would lie about, or worse clobber, the dev's own endpoint.
+            const merged = { ...process.env, ...env };
+            if (isSet(merged["ANTHROPIC_API_KEY"]))
+                return "your ANTHROPIC_API_KEY";
+            if (isSet(merged["ANTHROPIC_AUTH_TOKEN"]))
+                return "your ANTHROPIC_AUTH_TOKEN";
+            if (isSet(merged["CLAUDE_CODE_OAUTH_TOKEN"]))
+                return "your CLAUDE_CODE_OAUTH_TOKEN";
+            if (isSet(merged["ANTHROPIC_BASE_URL"]))
+                return "your ANTHROPIC_BASE_URL";
+            if (await probe())
+                return "your Claude Code login";
+            if (isSet(merged["VENDO_API_KEY"]))
+                return "your Vendo Cloud key (managed inference)";
+            return null;
+        },
+        async run(input) {
+            const model = input.env["VENDO_EXTRACTION_MODEL"];
+            const args = [
+                "-p", input.instructions,
+                "--allowedTools", ...ALLOWED_TOOLS,
+                "--disallowedTools", ...DISALLOWED_TOOLS,
+                "--setting-sources", "",
+                ...(model === undefined ? [] : ["--model", model]),
+            ];
+            // Merge FIRST, then guard: the child is spawned with the caller's env
+            // over process.env, so the own-credential check and gateway fuel must
+            // evaluate that same merged env — guarding input.env alone would let
+            // the overlay clobber an ambient (process.env) BYO endpoint the child
+            // would otherwise have used. Gateway fuel (if applicable) wins last.
+            const merged = { ...process.env, ...input.env };
+            const overlay = await resolveGatewayFuelOverlay(merged, probe);
+            const result = await exec(args, { cwd: input.root, env: { ...merged, ...overlay } });
+            if (result.code !== 0) {
+                throw new Error(`claude exited with code ${result.code}: ${result.stderr.trim() || "(no stderr)"}`);
+            }
+            return result.stdout;
+        },
+    };
+}

package/dist/cli/extract/claude-harness.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractionHarness } from "./harness.js";
+interface SdkModule {
+    query(params: {
+        prompt: string;
+        options: Record<string, unknown>;
+    }): AsyncIterable<Record<string, unknown>>;
+}
+export interface ClaudeHarnessOptions {
+    /** Test seams. */
+    loadSdk?: (root: string) => Promise<SdkModule | null>;
+    probeLogin?: () => Promise<boolean>;
+}
+export declare function claudeHarness(options?: ClaudeHarnessOptions): ExtractionHarness;
+export {};

package/dist/cli/extract/claude-harness.js

@@ -0,0 +1,127 @@
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * V1 extraction harness: the Claude Agent SDK driven headless with READ-ONLY
+ * code tools (Read/Glob/Grep) over the host root. Credential = the dev's
+ * Claude Code login, or their ANTHROPIC_API_KEY. The SDK resolves from the
+ * CLI's own installation first, then the host app — it is never installed
+ * into the host app by init.
+ *
+ * Isolation: `settingSources: []` (never inherit the dev's personal Claude
+ * Code settings/hooks), read-only tool allowlist, no shell/web/write surface.
+ */
+const SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+const PROBE_TIMEOUT_MS = 5_000;
+/** Bundler-proof dynamic import (same pattern as dev-creds): the
+ *  Function body is a FIXED literal — the specifier is a parameter, never
+ *  interpolated into code — so there is no injection surface. */
+async function dynamicImport(url) {
+    try {
+        return await import(url);
+    }
+    catch (nativeError) {
+        try {
+            const escaped = new Function("specifier", "return import(specifier)");
+            return await escaped(url);
+        }
+        catch {
+            throw nativeError;
+        }
+    }
+}
+/** Resolve the SDK from the CLI package itself, then from the host app. */
+async function loadSdk(root) {
+    for (const base of [import.meta.url, pathToFileURL(join(root, "package.json")).href]) {
+        try {
+            const require = createRequire(base);
+            return await dynamicImport(pathToFileURL(require.resolve(SDK_PACKAGE)).href);
+        }
+        catch {
+            // try the next resolution base
+        }
+    }
+    return null;
+}
+/** `claude auth status` prints JSON with a `loggedIn` boolean. */
+function probeClaudeLogin() {
+    return new Promise((resolve) => {
+        execFile("claude", ["auth", "status"], { timeout: PROBE_TIMEOUT_MS }, (error, stdout) => {
+            if (error !== null)
+                return resolve(false);
+            try {
+                resolve(JSON.parse(stdout).loggedIn === true);
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    });
+}
+export function claudeHarness(options = {}) {
+    const load = options.loadSdk ?? loadSdk;
+    const probe = options.probeLogin ?? probeClaudeLogin;
+    return {
+        id: "claude-agent-sdk",
+        async availability({ root, env }) {
+            if ((await load(root)) === null)
+                return null;
+            const key = env["ANTHROPIC_API_KEY"];
+            if (typeof key === "string" && key.trim().length > 0)
+                return "your ANTHROPIC_API_KEY";
+            if (await probe())
+                return "your Claude Code login";
+            return null;
+        },
+        async run(input) {
+            const sdk = await load(input.root);
+            if (sdk === null)
+                throw new Error(`${SDK_PACKAGE} is not available`);
+            const model = input.env["VENDO_EXTRACTION_MODEL"];
+            const stream = sdk.query({
+                prompt: input.instructions,
+                options: {
+                    cwd: input.root,
+                    settingSources: [],
+                    allowedTools: ["Read", "Glob", "Grep"],
+                    disallowedTools: [
+                        "Bash", "Write", "Edit", "WebFetch", "WebSearch", "Task",
+                        "TodoWrite", "NotebookEdit", "KillShell", "BashOutput",
+                    ],
+                    permissionMode: "default",
+                    maxTurns: 40,
+                    // Forward the caller's env so a key present only in the passed map
+                    // (not process.env) still authenticates the SDK subprocess.
+                    env: { ...process.env, ...input.env },
+                    ...(model === undefined ? {} : { model }),
+                },
+            });
+            let finalText = "";
+            const assistantText = [];
+            for await (const message of stream) {
+                const type = message["type"];
+                if (type === "assistant") {
+                    const content = message["message"]?.content;
+                    for (const part of content ?? []) {
+                        if (part["type"] === "text" && typeof part["text"] === "string") {
+                            assistantText.push(part["text"]);
+                        }
+                        else if (part["type"] === "tool_use") {
+                            const name = part["name"];
+                            const file = part["input"];
+                            const target = typeof file?.file_path === "string" ? file.file_path
+                                : typeof file?.pattern === "string" ? file.pattern : "";
+                            if (typeof name === "string")
+                                input.onProgress?.(`${name.toLowerCase()} ${target}`.trim());
+                        }
+                    }
+                }
+                else if (type === "result" && typeof message["result"] === "string") {
+                    finalText = message["result"];
+                }
+            }
+            return finalText.length > 0 ? finalText : assistantText.join("\n");
+        },
+    };
+}

package/dist/cli/extract/codex-cli-harness.d.ts

@@ -0,0 +1,31 @@
+import type { ExtractionHarness } from "./harness.js";
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+type Exec = (args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<ExecResult>;
+/** Pure mapping from a completed `codex exec` subprocess (exit code/stderr)
+ *  plus the outcome of reading its `--output-last-message` file into the
+ *  harness's ExecResult. Pulled out of execCodex's callback and exported so
+ *  the missing-file fallback — codex exited 0 but somehow wrote nothing —
+ *  has direct unit coverage instead of living only behind the exec seam. */
+export declare function resolveCodexExecResult(code: number, processStdout: string, stderr: string, finalMessage: string | undefined): ExecResult;
+/** Insert `--output-last-message <file>` immediately before the free-text
+ *  instructions positional (always the last element of a codex exec argv)
+ *  rather than appending after it — a flag placed after a long, arbitrary
+ *  free-text argument is fragile (positional/option disambiguation, and any
+ *  prompt that happens to start with `-`). Exported and pure so the ordering
+ *  is unit-tested without spawning a real process. */
+export declare function insertOutputLastMessageFlag(args: string[], outputFile: string): string[];
+export interface CodexCliHarnessOptions {
+    /** Test seams. */
+    probeBinary?: () => Promise<boolean>;
+    probeLogin?: (env: Record<string, string | undefined>) => Promise<boolean>;
+    exec?: Exec;
+}
+export declare function codexCliHarness(options?: CodexCliHarnessOptions): ExtractionHarness;
+export {};

package/dist/cli/extract/codex-cli-harness.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Fallback extraction harness: the `codex` CLI already on the dev's PATH,
+ * driven headless (`codex exec`) with a READ-ONLY sandbox over the host
+ * root. Credential = the dev's ChatGPT login (`codex login`), or their
+ * OPENAI_API_KEY — this is the third rung of the ladder (after the Agent SDK
+ * and claude-cli-harness.ts), for devs whose daily driver is Codex instead of
+ * Claude Code and who don't want to install anything new.
+ *
+ * Isolation: `--sandbox read-only` (model-generated shell commands can only
+ * read, never write or reach the network), `--skip-git-repo-check` (the host
+ * root may not itself be a git repo — codex refuses to run outside one by
+ * default, and extraction has no business caring), `--ignore-user-config`
+ * (never load the dev's personal `~/.codex/config.toml` — same intent as
+ * claude-cli-harness.ts's `--setting-sources ""`: their own MCP servers,
+ * custom instructions, or notify hooks must not leak into extraction; auth
+ * still resolves via CODEX_HOME regardless of this flag), `-C <root>` pins
+ * the agent's working root explicitly.
+ */
+const PROBE_TIMEOUT_MS = 5_000;
+// Extraction stages can run for minutes over a real codebase.
+const RUN_TIMEOUT_MS = 10 * 60 * 1_000;
+// codex's stdout under `exec` is throwaway tool-call narration — the actual
+// payload comes back via --output-last-message and is read separately below.
+// A narration stream over 10MB still trips execFile's maxBuffer and throws;
+// that's a known, accepted failure mode (loud, not silent), not something
+// worth raising just to tolerate noisier runs.
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+/** Pure mapping from a completed `codex exec` subprocess (exit code/stderr)
+ *  plus the outcome of reading its `--output-last-message` file into the
+ *  harness's ExecResult. Pulled out of execCodex's callback and exported so
+ *  the missing-file fallback — codex exited 0 but somehow wrote nothing —
+ *  has direct unit coverage instead of living only behind the exec seam. */
+export function resolveCodexExecResult(code, processStdout, stderr, finalMessage) {
+    if (code !== 0)
+        return { stdout: processStdout, stderr, code };
+    if (finalMessage !== undefined)
+        return { stdout: finalMessage, stderr, code };
+    // codex exited 0 but wrote no final-message file — there is nothing for
+    // extraction.ts to parse; surface it as a failure through the same
+    // code-path run() already uses for errors.
+    return {
+        stdout: "",
+        stderr: "codex produced no final message (--output-last-message file missing)",
+        code: 1,
+    };
+}
+/** Insert `--output-last-message <file>` immediately before the free-text
+ *  instructions positional (always the last element of a codex exec argv)
+ *  rather than appending after it — a flag placed after a long, arbitrary
+ *  free-text argument is fragile (positional/option disambiguation, and any
+ *  prompt that happens to start with `-`). Exported and pure so the ordering
+ *  is unit-tested without spawning a real process. */
+export function insertOutputLastMessageFlag(args, outputFile) {
+    return [...args.slice(0, -1), "--output-last-message", outputFile, ...args.slice(-1)];
+}
+/** `codex exec` has no print-mode equivalent to claude's `-p` stdout capture
+ *  — the terminal stream is full of tool-call narration. `--output-last-
+ *  message <file>` is codex's own mechanism for isolating just the agent's
+ *  final text, so the real spawn writes it to a throwaway temp file and
+ *  reads it back once the process exits cleanly. */
+function execCodex(args, options) {
+    return (async () => {
+        const outDir = await mkdtemp(join(tmpdir(), "vendo-codex-extract-"));
+        const outputFile = join(outDir, "last-message.txt");
+        try {
+            return await new Promise((resolve) => {
+                execFile("codex", insertOutputLastMessageFlag(args, outputFile), { cwd: options.cwd, env: options.env, timeout: RUN_TIMEOUT_MS, maxBuffer: MAX_BUFFER_BYTES }, (error, stdout, stderr) => {
+                    const code = error === null ? 0 : typeof error.code === "number" ? error.code : 1;
+                    if (code !== 0) {
+                        resolve(resolveCodexExecResult(code, stdout, stderr, undefined));
+                        return;
+                    }
+                    readFile(outputFile, "utf8").then((finalMessage) => resolve(resolveCodexExecResult(code, stdout, stderr, finalMessage)), () => resolve(resolveCodexExecResult(code, stdout, stderr, undefined)));
+                });
+            });
+        }
+        finally {
+            await rm(outDir, { recursive: true, force: true });
+        }
+    })();
+}
+/** Cheap presence check: does `codex` resolve and run at all? */
+function probeCodexBinary() {
+    return new Promise((resolve) => {
+        execFile("codex", ["--version"], { timeout: PROBE_TIMEOUT_MS }, (error) => resolve(error === null));
+    });
+}
+/** Codex persists login state to `$CODEX_HOME/auth.json` (default
+ *  `~/.codex/auth.json`) — either a ChatGPT OAuth token pair (`auth_mode:
+ *  "chatgpt"`) or an API key saved via `codex login --with-api-key`.
+ *  `codex login status` has no machine-readable output, so this reads the
+ *  file directly: a plain fs read that's cheap and trivially fake-able in
+ *  tests without a real login. CODEX_HOME resolution mirrors run()'s own
+ *  env merge (the caller's env wins over process.env) so availability's
+ *  login check and the actual subprocess spawn never disagree about which
+ *  codex home is in play. */
+async function probeCodexLogin(env) {
+    const codexHome = env["CODEX_HOME"] ?? process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
+    const authPath = join(codexHome, "auth.json");
+    try {
+        const parsed = JSON.parse(await readFile(authPath, "utf8"));
+        if (typeof parsed.OPENAI_API_KEY === "string" && parsed.OPENAI_API_KEY.trim().length > 0)
+            return true;
+        if (typeof parsed.tokens?.id_token === "string" && parsed.tokens.id_token.trim().length > 0)
+            return true;
+        if (typeof parsed.tokens?.access_token === "string" && parsed.tokens.access_token.trim().length > 0)
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function codexCliHarness(options = {}) {
+    const hasBinary = options.probeBinary ?? probeCodexBinary;
+    const probe = options.probeLogin ?? probeCodexLogin;
+    const exec = options.exec ?? execCodex;
+    return {
+        id: "codex-cli",
+        async availability({ env }) {
+            if (!(await hasBinary()))
+                return null;
+            const key = env["OPENAI_API_KEY"];
+            if (typeof key === "string" && key.trim().length > 0)
+                return "your OPENAI_API_KEY";
+            if (await probe(env))
+                return "your ChatGPT login";
+            return null;
+        },
+        async run(input) {
+            const model = input.env["VENDO_EXTRACTION_MODEL"];
+            const args = [
+                "exec",
+                "--sandbox", "read-only",
+                "--skip-git-repo-check",
+                "--ignore-user-config",
+                "-C", input.root,
+                ...(model === undefined ? [] : ["--model", model]),
+                input.instructions,
+            ];
+            // Forward the caller's env so a key present only in the passed map
+            // (not process.env) still authenticates the subprocess.
+            const result = await exec(args, { cwd: input.root, env: { ...process.env, ...input.env } });
+            if (result.code !== 0) {
+                throw new Error(`codex exited with code ${result.code}: ${result.stderr.trim() || "(no stderr)"}`);
+            }
+            return result.stdout;
+        },
+    };
+}

package/dist/cli/extract/delegate.d.ts

@@ -0,0 +1,21 @@
+import { type StaticTool } from "./stages.js";
+/**
+ * The delegated-extraction contract (install-dx: external-agent delegation).
+ * Vendo's IP is the CONTRACT — the composed instructions, the draft schema,
+ * and the deterministic guards — not the reader: any competent coding agent
+ * (Claude Code, Cursor, Codex, …) can do the reading. `vendo init --agent`
+ * emits this contract in its plan; the dev's own agent reads the codebase,
+ * writes a draft, and `vendo extract --apply` runs it through the SAME
+ * applyDraft guards as init's built-in pass — delegation never becomes a
+ * second, weaker path into `.vendo/`.
+ */
+export declare const APPLY_COMMAND = "npx vendo extract --apply <draft.json>";
+/** JSON Schema mirror of extractionDraftSchema in harness.ts (hand-kept in
+ *  sync — zod v3 has no schema emitter). Stricter than parseDraft on unknown
+ *  keys, deliberately: the contract steers agents to the exact shape while
+ *  apply stays lenient. */
+export declare const EXTRACTION_DRAFT_JSON_SCHEMA: Record<string, unknown>;
+/** One-shot instructions for an external agent producing the FULL draft
+ *  (judgment on every tool plus the brief) — the same rules the staged
+ *  pipeline enforces per stage, phrased for a single delegated pass. */
+export declare function composeDelegatedInstructions(tools: StaticTool[], appName: string): string;