@vendoai/vendo 0.4.0

package/dist/cli/extract/delegate.js

@@ -0,0 +1,77 @@
+import { staticFacts } 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 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 const EXTRACTION_DRAFT_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    additionalProperties: false,
+    required: ["brief", "tools"],
+    properties: {
+        brief: {
+            type: "string",
+            minLength: 1,
+            maxLength: 4000,
+            description: "One-paragraph product brief drafted from the codebase.",
+        },
+        tools: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["name", "description"],
+                properties: {
+                    name: { type: "string", minLength: 1 },
+                    description: { type: "string", minLength: 1, maxLength: 500 },
+                    risk: { enum: ["read", "write", "destructive"] },
+                    critical: { type: "boolean" },
+                    disabled: {
+                        type: "boolean",
+                        description: "false = wake a statically-unclassifiable tool (requires reasoning and risk).",
+                    },
+                    reasoning: { type: "string", maxLength: 500 },
+                },
+            },
+        },
+        missedSurfaces: {
+            type: "array",
+            items: { type: "string", maxLength: 300 },
+            description: "API surfaces the static extractor missed (path + one line). Surfaced to the dev, never written.",
+        },
+    },
+};
+/** 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 function composeDelegatedInstructions(tools, appName) {
+    return [
+        "You are Vendo's extraction agent. Read this codebase (Read/Glob/Grep only) and draft",
+        "judgment on the API tools a static extractor already found, plus the product brief.",
+        "",
+        `Product/package name: ${appName}`,
+        "Statically extracted tools (name, method+path when known, current risk, disabled state):",
+        staticFacts(tools),
+        "",
+        "Rules:",
+        "- Produce ONE json document matching the provided draftSchema:",
+        '  { "brief": string, "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }], "missedSurfaces"?: string[] }',
+        "- tools: include ONLY names from the list above. Rewrite each description so an agent choosing tools understands what it actually does (read the handler source). <= 200 chars each.",
+        "- risk: you may RAISE risk (read->write->destructive) when the handler is more dangerous than labeled; never lower it. Mark irreversible operations critical: true.",
+        "- A tool listed as disabled was statically unclassifiable. If you can read its handler and grade it, set disabled: false WITH a risk and one-line reasoning. Leave it out otherwise.",
+        "- missedSurfaces: API surfaces you found that the list is missing (path + one line). Do not invent tools for them.",
+        "- brief: one paragraph — what the product does, who uses it, the jobs the agent should help with. Written from the actual code, no marketing fluff.",
+        `- Save the draft to a json file and apply it with \`${APPLY_COMMAND}\` — deterministic guards validate every entry before anything lands in .vendo/.`,
+    ].join("\n");
+}

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

@@ -0,0 +1,65 @@
+import { parseDraft, type ExtractionHarness } from "./harness.js";
+import { type SelectOption } from "../pretty.js";
+import { type StagedExtractionInput, type StagedExtractionResult, type StaticTool } from "./stages.js";
+import { type Output } from "../shared.js";
+export { composeInstructions } from "./stages.js";
+export interface AppliedSummary {
+    described: number;
+    riskRaised: number;
+    critical: number;
+    woken: number;
+    briefWritten: boolean;
+    refused: string[];
+    missedSurfaces: string[];
+}
+/** Deterministic verification + application of a parsed draft. Exported for
+ *  tests; init uses runAiExtraction below. */
+export declare function applyDraft(input: {
+    root: string;
+    draft: ReturnType<typeof parseDraft>;
+    tools: StaticTool[];
+    force?: boolean;
+}): Promise<AppliedSummary>;
+/** The one applied-polish summary both init's built-in pass and
+ *  `vendo extract --apply` print — delegation must read identically. */
+export declare function reportApplied(input: {
+    output: Output;
+    applied: AppliedSummary;
+    briefDrafted: boolean;
+    artifactsNote?: string;
+    notes?: string[];
+}): void;
+/** Consent-style one-line prompt — shared machinery: the AI-polish consent
+    here and init's detected-auth confirm both use it. */
+export declare function askYesNo(question: string, defaultYes: boolean): Promise<boolean>;
+export interface AiExtractionOptions {
+    root: string;
+    output: Output;
+    env: Record<string, string | undefined>;
+    /** Non-interactive (--yes / no TTY): no consent possible — skip silently. */
+    yes: boolean;
+    /** --ai-polish: consent granted as a flag — skip the prompt and run even
+        when non-interactive (the flag IS the answer). */
+    consent?: boolean;
+    force?: boolean;
+    /** --engine: pin the rung family (claude | codex | npx) instead of
+        first-available. An unavailable pin skips loudly — never a fallback. */
+    engine?: string;
+    /** Seams (tests / future harnesses). */
+    harnesses?: ExtractionHarness[];
+    confirm?: (question: string, defaultYes: boolean) => Promise<boolean>;
+    /** The multi-engine consent select (init passes pretty.select); default is
+        the plain numbered select. Resolves to an option value or "skip". */
+    choose?: (question: string, options: SelectOption[], defaultIndex: number) => Promise<string>;
+    interactive?: boolean;
+    /** Optional theme-stage input (init's exact-only summary, projected) — see
+        `StagedExtractionInput.theme`. Omitted when init has no theme pass to
+        run this call (a pre-existing theme.json, e.g.). */
+    theme?: StagedExtractionInput["theme"];
+}
+/** init's AI extraction step. Never changes init's exit code. */
+export declare function runAiExtraction(options: AiExtractionOptions): Promise<{
+    ran: boolean;
+    engine?: "claude" | "codex" | "npx-engine";
+    theme?: StagedExtractionResult["theme"];
+}>;

package/dist/cli/extract/extraction.js

@@ -0,0 +1,300 @@
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { z } from "zod";
+import { claudeCliHarness } from "./claude-cli-harness.js";
+import { claudeHarness } from "./claude-harness.js";
+import { codexCliHarness } from "./codex-cli-harness.js";
+import { npxEngineHarness } from "./npx-engine-harness.js";
+import { plainSelect } from "../pretty.js";
+import { BRIEF_TEMPLATE, runStagedExtraction, staticToolSchema, } from "./stages.js";
+import { readOptional, writeText } from "../shared.js";
+export { composeInstructions } from "./stages.js";
+/**
+ * The AI extraction pass (install-dx: staged pipeline + deterministic
+ * verification — see stages.ts for the survey / draft-per-surface /
+ * cross-check / brief orchestration). The agent reads the codebase and
+ * drafts judgment on top of the static facts: task-oriented tool
+ * descriptions, risk corrections, critical marks, waking unclassifiable
+ * tools, and the product brief.
+ *
+ * Output rides the channels that SURVIVE `vendo sync` regeneration:
+ * `.vendo/overrides.json` (per-tool description/risk/critical/disabled — the
+ * designed merge layer) and `.vendo/brief.md`. It never writes tools.json
+ * directly, so predev/prebuild re-extraction cannot clobber it.
+ *
+ * Deterministic guards (never cross fingers, PostHog lesson):
+ * - only tool names the static extraction produced are accepted;
+ * - risk may be RAISED, never lowered (fail-closed stays fail-closed);
+ * - waking a disabled tool requires reasoning and an explicit risk;
+ * - human decisions win: existing override fields are never overwritten, and
+ *   a hand-written brief is never replaced (only the init template is).
+ */
+const RISK_ORDER = { read: 0, write: 1, destructive: 2 };
+const overridesSchema = z.object({
+    format: z.literal("vendo/overrides@1"),
+    tools: z.record(z.object({
+        risk: z.enum(["read", "write", "destructive"]).optional(),
+        critical: z.boolean().optional(),
+        disabled: z.boolean().optional(),
+        description: z.string().optional(),
+    }).passthrough()),
+}).passthrough();
+/** Deterministic verification + application of a parsed draft. Exported for
+ *  tests; init uses runAiExtraction below. */
+export async function applyDraft(input) {
+    const byName = new Map(input.tools.map((tool) => [tool.name, tool]));
+    const overridesPath = join(input.root, ".vendo", "overrides.json");
+    const raw = await readOptional(overridesPath);
+    const overrides = raw === null
+        ? { format: "vendo/overrides@1", tools: {} }
+        : overridesSchema.parse(JSON.parse(raw));
+    const summary = {
+        described: 0, riskRaised: 0, critical: 0, woken: 0,
+        briefWritten: false, refused: [], missedSurfaces: input.draft.missedSurfaces ?? [],
+    };
+    for (const entry of input.draft.tools) {
+        const fact = byName.get(entry.name);
+        if (fact === undefined) {
+            summary.refused.push(`${entry.name}: not an extracted tool`);
+            continue;
+        }
+        const existing = overrides.tools[entry.name] ?? {};
+        const next = { ...existing };
+        if (existing.description === undefined && entry.description !== fact.description) {
+            next.description = entry.description;
+            summary.described += 1;
+        }
+        // Waking a statically-unclassifiable tool is its own path: the static
+        // "destructive, disabled" grade is a fail-closed PLACEHOLDER, not
+        // evidence, so a reasoned wake carries the model's grade without tripping
+        // the downgrade guard (Greptile P1 / Devin on #363). A human-set risk or
+        // disabled decision always wins.
+        const isWake = entry.disabled === false && fact.disabled === true;
+        if (isWake && existing.disabled === undefined) {
+            if (entry.reasoning === undefined || entry.risk === undefined) {
+                summary.refused.push(`${entry.name}: waking a disabled tool needs reasoning and a risk grade`);
+            }
+            else {
+                next.disabled = false;
+                if (existing.risk === undefined)
+                    next.risk = entry.risk;
+                summary.woken += 1;
+            }
+        }
+        else if (entry.risk !== undefined && existing.risk === undefined && fact.disabled !== true) {
+            const current = fact.risk ?? "destructive";
+            if (RISK_ORDER[entry.risk] > RISK_ORDER[current]) {
+                next.risk = entry.risk;
+                summary.riskRaised += 1;
+            }
+            else if (RISK_ORDER[entry.risk] < RISK_ORDER[current]) {
+                summary.refused.push(`${entry.name}: risk downgrade ${current}→${entry.risk} refused`);
+            }
+        }
+        if (entry.critical === true && existing.critical === undefined) {
+            next.critical = true;
+            summary.critical += 1;
+        }
+        if (JSON.stringify(next) !== JSON.stringify(existing))
+            overrides.tools[entry.name] = next;
+    }
+    await writeText(overridesPath, `${JSON.stringify(overrides, null, 2)}\n`);
+    const briefPath = join(input.root, ".vendo", "brief.md");
+    const currentBrief = ((await readOptional(briefPath)) ?? "").trim();
+    if (input.force === true || currentBrief === "" || currentBrief === BRIEF_TEMPLATE) {
+        await writeText(briefPath, `${input.draft.brief.trim()}\n`);
+        summary.briefWritten = true;
+    }
+    return summary;
+}
+/** The one applied-polish summary both init's built-in pass and
+ *  `vendo extract --apply` print — delegation must read identically. */
+export function reportApplied(input) {
+    const { output, applied } = input;
+    const parts = [
+        `${applied.described} descriptions`,
+        ...(applied.riskRaised > 0 ? [`${applied.riskRaised} risk raises`] : []),
+        ...(applied.critical > 0 ? [`${applied.critical} critical marks`] : []),
+        ...(applied.woken > 0 ? [`${applied.woken} tools woken`] : []),
+        ...(input.briefDrafted ? ["brief drafted"] : []),
+    ];
+    output.log(`AI polish applied: ${parts.join(" · ")} → .vendo/overrides.json, .vendo/brief.md${input.artifactsNote ?? ""}`);
+    for (const note of input.notes ?? [])
+        output.error(`  ${note}`);
+    for (const refused of applied.refused)
+        output.error(`  refused: ${refused}`);
+    for (const missed of applied.missedSurfaces)
+        output.log(`  missed surface (not extracted yet): ${missed}`);
+}
+/** Consent-style one-line prompt — shared machinery: the AI-polish consent
+    here and init's detected-auth confirm both use it. */
+export async function askYesNo(question, defaultYes) {
+    const prompt = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await prompt.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+        if (answer === "")
+            return defaultYes;
+        return ["y", "yes"].includes(answer);
+    }
+    finally {
+        prompt.close();
+    }
+}
+/** The telemetry `engine` enum value for each ladder rung (both Claude rungs
+    are the same engine reached two ways). Unlisted ids (test seams) map to
+    undefined — the caller's "none" default covers them. Distinct from
+    ENGINE_FAMILIES below: telemetry's closed enum says "npx-engine" while the
+    user-facing `--engine` family is "npx". */
+const ENGINE_BY_HARNESS_ID = {
+    "claude-agent-sdk": "claude",
+    "claude-cli": "claude",
+    "codex-cli": "codex",
+    "npx-engine": "npx-engine",
+};
+/** Rung id → user-facing engine family (`--engine` values). The Agent SDK and
+    the claude CLI are one family: same provider, same credential story. An
+    unknown id (test fakes, future rungs) is its own family. */
+const ENGINE_FAMILIES = {
+    "claude-agent-sdk": "claude",
+    "claude-cli": "claude",
+    "codex-cli": "codex",
+    "npx-engine": "npx",
+};
+/** init's AI extraction step. Never changes init's exit code. */
+export async function runAiExtraction(options) {
+    const { root, output, env } = options;
+    const toolsRaw = await readOptional(join(root, ".vendo", "tools.json"));
+    let tools = [];
+    // tools.json missing or unparseable degrades tool polish to a no-op — but
+    // must NOT also silently kill a requested theme pass (Task 4): the staged
+    // call below runs with an empty tool list, and only the tool-polish half
+    // (applyDraft/reportApplied) is skipped.
+    let toolsAvailable = false;
+    if (toolsRaw !== null) {
+        try {
+            tools = z.object({ tools: z.array(staticToolSchema) }).parse(JSON.parse(toolsRaw)).tools;
+            toolsAvailable = true;
+        }
+        catch {
+            // Unparseable tools.json — tool polish stays skipped below.
+        }
+    }
+    if (!toolsAvailable && options.theme === undefined)
+        return { ran: false };
+    const interactive = options.interactive ?? (Boolean(stdin.isTTY) && Boolean(stdout.isTTY));
+    if (options.consent !== true && (options.yes || !interactive)) {
+        output.log("AI polish (descriptions, risk review, brief, theme): skipped — needs an interactive run (`vendo init` in a terminal).");
+        return { ran: false };
+    }
+    // Ordered engine ladder (install-dx: init-selfcontained-engine, Task 2/4):
+    // Agent SDK -> claude CLI -> codex CLI -> npx-fetched engine. A rung whose
+    // availability() is null (binary missing or present-but-unauthenticated) is
+    // skipped; ladder order encodes preference (the npx rung is last on purpose:
+    // it's the only one with a real first-run cost, an npm fetch, so every rung
+    // that can run for free gets first refusal). Availability is checked across
+    // the WHOLE ladder (every check is local and cheap) so `--engine` can pin a
+    // family and the interactive consent can offer a choice when there is one;
+    // the first available rung of a family speaks for that family.
+    const harnesses = options.harnesses
+        ?? [claudeHarness(), claudeCliHarness(), codexCliHarness(), npxEngineHarness()];
+    const available = [];
+    for (const harness of harnesses) {
+        const family = ENGINE_FAMILIES[harness.id] ?? harness.id;
+        if (available.some((entry) => entry.family === family))
+            continue;
+        const credential = await harness.availability({ root, env });
+        if (credential !== null)
+            available.push({ harness, credential, family });
+    }
+    if (available.length === 0) {
+        output.log("AI polish: unavailable — needs Claude Code installed (`npm install -g @anthropic-ai/claude-code`) or @anthropic-ai/claude-agent-sdk resolvable, plus a Claude Code login or ANTHROPIC_API_KEY; or the `codex` CLI installed, plus a codex login (`codex login`) or OPENAI_API_KEY; or a VENDO_API_KEY (`vendo login`), which fetches Claude Code on the fly via npx. Extractor defaults stand; re-run `vendo init` once set up.");
+        return { ran: false };
+    }
+    // --engine pins a family. An unavailable pin never falls back to another
+    // provider (the pin is usually a privacy/policy choice about where source
+    // goes) — one loud line naming what IS available, exit code untouched.
+    let chosen;
+    if (options.engine !== undefined) {
+        const pinned = available.find((entry) => entry.family === options.engine);
+        if (pinned === undefined) {
+            const alternatives = available
+                .map((entry) => `\`--engine ${entry.family}\` (${entry.credential})`)
+                .join(", or ");
+            output.log(`AI polish: \`--engine ${options.engine}\` requested but that engine isn't available on this machine. Available: ${alternatives}. Extractor defaults stand; re-run \`vendo init\` once it's set up.`);
+            return { ran: false };
+        }
+        chosen = pinned;
+    }
+    else {
+        chosen = available[0];
+    }
+    if (options.consent !== true) {
+        if (options.engine === undefined && available.length > 1) {
+            // Several engines: the SAME single consent question, as a pick-with-
+            // default instead of yes/no — never a second question.
+            const choose = options.choose ?? plainSelect;
+            const picked = await choose("Let a coding agent read this codebase to draft tool descriptions, review risk, write the product brief, and fill unresolved theme slots? Source goes to the chosen provider under your account.", [
+                ...available.map((entry) => ({ value: entry.family, label: entry.credential, hint: `--engine ${entry.family}` })),
+                { value: "skip", label: "Skip — keep extractor defaults" },
+            ], 0);
+            const selected = available.find((entry) => entry.family === picked);
+            if (selected === undefined) {
+                output.log("Skipped — extractor defaults stand; re-run `vendo init` any time to add the AI polish.");
+                return { ran: false };
+            }
+            chosen = selected;
+        }
+        else {
+            const confirm = options.confirm ?? askYesNo;
+            const consented = await confirm(`Let ${chosen.credential} read this codebase to draft tool descriptions, review risk, write the product brief, and fill unresolved theme slots? Source goes to your model provider under your account.`, true);
+            if (!consented) {
+                output.log("Skipped — extractor defaults stand; re-run `vendo init` any time to add the AI polish.");
+                return { ran: false };
+            }
+        }
+    }
+    let appName = "app";
+    try {
+        appName = JSON.parse((await readOptional(join(root, "package.json"))) ?? "{}").name ?? "app";
+    }
+    catch {
+        // package.json is optional context
+    }
+    output.log(`\nReading your product (${chosen.credential})…`);
+    try {
+        const staged = await runStagedExtraction({
+            root,
+            env,
+            harness: chosen.harness,
+            tools,
+            appName,
+            onProgress: (line) => output.log(`  ${line}`),
+            ...(options.theme === undefined ? {} : { theme: options.theme }),
+        });
+        if (toolsAvailable) {
+            const applied = await applyDraft({ root, draft: staged.draft, tools, ...(options.force === undefined ? {} : { force: options.force }) });
+            reportApplied({
+                output,
+                applied,
+                briefDrafted: applied.briefWritten && staged.briefFromStage,
+                artifactsNote: " (stage artifacts: .vendo/data/extract/)",
+                notes: staged.notes,
+            });
+        }
+        else {
+            for (const note of staged.notes)
+                output.error(`  ${note}`);
+        }
+        const engine = ENGINE_BY_HARNESS_ID[chosen.harness.id];
+        return {
+            ran: true,
+            ...(engine === undefined ? {} : { engine }),
+            ...(staged.theme === undefined ? {} : { theme: staged.theme }),
+        };
+    }
+    catch (error) {
+        output.error(`AI polish did not complete (${error instanceof Error ? error.message : "unknown error"}); extractor defaults stand. Re-run \`vendo init\` to retry — stage artifacts in .vendo/data/extract/ show how far it got.`);
+        return { ran: false };
+    }
+}

package/dist/cli/extract/gateway-fuel.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gateway fuel: the env overlay that makes Claude Code (any rung that reads
+ * ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_CUSTOM_HEADERS — the
+ * PATH `claude` binary today, the npx-fetched engine package tomorrow, per
+ * `docs/superpowers/plans/2026-07-20-init-selfcontained-engine.md` Task 3/4)
+ * speak to the Vendo Cloud model gateway instead of Anthropic directly, when
+ * the dev has no Anthropic credential of their own but does have
+ * VENDO_API_KEY. Own credential always wins — this module never overrides
+ * it, and callers must never call it when one is available.
+ *
+ * INVARIANT: a non-blank ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, or
+ * ANTHROPIC_BASE_URL in the passed env IS an own credential (the corporate-
+ * gateway / custom-endpoint path Claude Code also supports, none of which
+ * show up in a `claude auth status` login probe) and always wins, even if a
+ * caller mistakenly passes `ownCredentialAvailable: false`. Overwriting a
+ * dev's already-configured BYO endpoint would silently redirect their
+ * inference through Vendo's gateway and bill their org's meter — this
+ * module checks it directly rather than trusting callers to remember.
+ *
+ * The gateway must be able to refuse this traffic for free-plan orgs
+ * (spec's free-plan policy), so every request gets tagged with the
+ * INIT_PURPOSE_HEADER — a plain "name: value" line via Claude Code's
+ * ANTHROPIC_CUSTOM_HEADERS mechanism. The constant is the single source of
+ * truth; the console mirrors the literal in its own tests (plan Task 7).
+ */
+export declare const INIT_PURPOSE_HEADER_NAME = "x-vendo-purpose";
+export declare const INIT_PURPOSE_HEADER_VALUE = "init";
+/** Env vars that Claude Code itself accepts as an own credential besides
+ *  ANTHROPIC_API_KEY and a CLI login: a corporate-gateway auth token, a
+ *  device-flow OAuth token, or a custom base URL with no token at all
+ *  (mTLS/proxy auth). None of these are visible to a `claude auth status`
+ *  probe, so any caller folding "own credential" into its own predicate
+ *  (claude-cli-harness.ts's availability()/run()) must check these three
+ *  directly rather than relying solely on the login probe. Exported so
+ *  every harness checks the identical set. */
+export declare const OWN_CREDENTIAL_ENV_VARS: readonly ["ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_BASE_URL"];
+/** True when the env alone (no async probe needed) already carries one of
+ *  Claude Code's own-credential env vars (see OWN_CREDENTIAL_ENV_VARS). */
+export declare function hasOwnAnthropicEnvOverride(env: Record<string, string | undefined>): boolean;
+export interface GatewayFuelOverlay {
+    ANTHROPIC_BASE_URL: string;
+    ANTHROPIC_AUTH_TOKEN: string;
+    ANTHROPIC_CUSTOM_HEADERS: string;
+}
+export interface GatewayFuelOptions {
+    /** The CHILD'S real env — i.e. the same merged {...process.env,
+     *  ...input.env} the harness is about to spawn with, never the caller's
+     *  partial input env alone. The INVARIANT above is only worth anything if
+     *  it is checked against the env the subprocess will actually read: an
+     *  ambient (process.env) ANTHROPIC_AUTH_TOKEN/ANTHROPIC_BASE_URL is a
+     *  live BYO endpoint that an overlay composed from input.env alone would
+     *  silently clobber. */
+    env: Record<string, string | undefined>;
+    /** True when the rung already has a working credential of its own (its
+     *  own ANTHROPIC_API_KEY, a satisfied Claude Code login, ...). Each
+     *  harness computes this itself — an env check, an async login probe,
+     *  whatever its rung needs — and passes the verdict in, so this module
+     *  stays a pure, harness-agnostic composition step reusable by every
+     *  Claude-Code-shaped rung (claude-cli-harness.ts today; the future
+     *  npx-engine harness reuses the same function). This module additionally
+     *  checks OWN_CREDENTIAL_ENV_VARS itself regardless of this flag — see
+     *  the module-level INVARIANT note. */
+    ownCredentialAvailable: boolean;
+}
+/** Compose the gateway-fuel env overlay for a Claude-Code-shaped rung, or
+ *  null when gateway fuel does not apply: own credential wins (either the
+ *  caller's verdict or a directly-detected env override), or there is no
+ *  VENDO_API_KEY to fuel with. */
+export declare function composeGatewayFuel(options: GatewayFuelOptions): GatewayFuelOverlay | null;

package/dist/cli/extract/gateway-fuel.js

@@ -0,0 +1,69 @@
+import { resolveCloudBaseUrl } from "../cloud/client.js";
+/**
+ * Gateway fuel: the env overlay that makes Claude Code (any rung that reads
+ * ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_CUSTOM_HEADERS — the
+ * PATH `claude` binary today, the npx-fetched engine package tomorrow, per
+ * `docs/superpowers/plans/2026-07-20-init-selfcontained-engine.md` Task 3/4)
+ * speak to the Vendo Cloud model gateway instead of Anthropic directly, when
+ * the dev has no Anthropic credential of their own but does have
+ * VENDO_API_KEY. Own credential always wins — this module never overrides
+ * it, and callers must never call it when one is available.
+ *
+ * INVARIANT: a non-blank ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, or
+ * ANTHROPIC_BASE_URL in the passed env IS an own credential (the corporate-
+ * gateway / custom-endpoint path Claude Code also supports, none of which
+ * show up in a `claude auth status` login probe) and always wins, even if a
+ * caller mistakenly passes `ownCredentialAvailable: false`. Overwriting a
+ * dev's already-configured BYO endpoint would silently redirect their
+ * inference through Vendo's gateway and bill their org's meter — this
+ * module checks it directly rather than trusting callers to remember.
+ *
+ * The gateway must be able to refuse this traffic for free-plan orgs
+ * (spec's free-plan policy), so every request gets tagged with the
+ * INIT_PURPOSE_HEADER — a plain "name: value" line via Claude Code's
+ * ANTHROPIC_CUSTOM_HEADERS mechanism. The constant is the single source of
+ * truth; the console mirrors the literal in its own tests (plan Task 7).
+ */
+export const INIT_PURPOSE_HEADER_NAME = "x-vendo-purpose";
+export const INIT_PURPOSE_HEADER_VALUE = "init";
+/** Env vars that Claude Code itself accepts as an own credential besides
+ *  ANTHROPIC_API_KEY and a CLI login: a corporate-gateway auth token, a
+ *  device-flow OAuth token, or a custom base URL with no token at all
+ *  (mTLS/proxy auth). None of these are visible to a `claude auth status`
+ *  probe, so any caller folding "own credential" into its own predicate
+ *  (claude-cli-harness.ts's availability()/run()) must check these three
+ *  directly rather than relying solely on the login probe. Exported so
+ *  every harness checks the identical set. */
+export const OWN_CREDENTIAL_ENV_VARS = [
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+];
+function nonBlank(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** True when the env alone (no async probe needed) already carries one of
+ *  Claude Code's own-credential env vars (see OWN_CREDENTIAL_ENV_VARS). */
+export function hasOwnAnthropicEnvOverride(env) {
+    return OWN_CREDENTIAL_ENV_VARS.some((name) => nonBlank(env[name]));
+}
+/** Compose the gateway-fuel env overlay for a Claude-Code-shaped rung, or
+ *  null when gateway fuel does not apply: own credential wins (either the
+ *  caller's verdict or a directly-detected env override), or there is no
+ *  VENDO_API_KEY to fuel with. */
+export function composeGatewayFuel(options) {
+    if (options.ownCredentialAvailable)
+        return null;
+    if (hasOwnAnthropicEnvOverride(options.env))
+        return null;
+    const key = options.env["VENDO_API_KEY"];
+    if (!nonBlank(key))
+        return null;
+    const base = resolveCloudBaseUrl({ env: options.env });
+    const baseURL = base.endsWith("/api/v1") ? base : `${base}/api/v1`;
+    return {
+        ANTHROPIC_BASE_URL: baseURL,
+        ANTHROPIC_AUTH_TOKEN: key.trim(),
+        ANTHROPIC_CUSTOM_HEADERS: `${INIT_PURPOSE_HEADER_NAME}: ${INIT_PURPOSE_HEADER_VALUE}`,
+    };
+}