@orcareplay/adapters 0.1.0

package/dist/contract.js

@@ -0,0 +1,373 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { PLACEHOLDER_KEY, readEnv } from './env.js';
+/**
+ * The adapter contract: the behaviour every adapter must have for capture to work at all.
+ *
+ * Adapters break silently. A harness renames the variable it reads for its API origin, the adapter
+ * keeps setting the old one, and every run still *looks* fine — the agent answers, the exit code is
+ * zero, and the trace is empty. Each check below exists because breaking it produces exactly that
+ * shape of failure: nothing to see until a user files a confusing bug.
+ */
+/** Every check, in the order they run. A failing check never stops the others. */
+export const CONTRACT_CHECKS = [
+    'id-format',
+    'detect-resolves',
+    'prepare-shape',
+    'redirects-model-traffic',
+    'no-invented-keys',
+    'no-ctx-mutation',
+    'deterministic',
+    'no-foreign-paths',
+    'harness-versions',
+];
+/** At least one of these must be redirected, or the proxy sees nothing at all. */
+export const MODEL_BASE_URL_VARS = [
+    'ANTHROPIC_BASE_URL',
+    'OPENAI_BASE_URL',
+    'OPENAI_API_BASE',
+];
+/** Anything shaped like an API origin, including variables no harness reads yet. */
+const BASE_URL_LIKE = /(?:_BASE_URL|_API_BASE)$/;
+/** Anything shaped like a credential. Over-matching here only ever costs a clearer error. */
+const CREDENTIAL_LIKE = /(?:KEY|TOKEN|SECRET|PASSWORD)$/;
+const ID_FORMAT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A port no adapter would plausibly hardcode: the checks must follow `ctx.proxyUrl`. */
+const CONTRACT_PROXY = 'http://127.0.0.1:49831';
+const PROBE_KEY = 'orca-contract-probe';
+/** Returned by a check that does not apply to this adapter, so it is neither passed nor failed. */
+const SKIP = Symbol('skip');
+/**
+ * Runs one adapter through the contract. Never throws: a runner that dies on a broken adapter is
+ * the same class of bug it is trying to catch, and callers batch this over a whole registry.
+ */
+export async function checkAdapterContract(adapter, opts = {}) {
+    const root = await mkdtemp(join(tmpdir(), 'orca-contract-'));
+    const passed = [];
+    const failed = [];
+    try {
+        const base = await baseContext(root, opts.ctx ?? {});
+        const primary = await attempt(adapter, base);
+        const runners = [
+            ['id-format', async () => idFormat(adapter)],
+            ['detect-resolves', () => detectResolves(adapter, base, join(root, 'missing-workspace'))],
+            ['prepare-shape', async () => prepareShape(primary)],
+            ['redirects-model-traffic', async () => redirectsModelTraffic(primary, base)],
+            ['no-invented-keys', () => noInventedKeys(adapter, base)],
+            ['no-ctx-mutation', () => noCtxMutation(adapter, base)],
+            ['deterministic', () => deterministic(adapter, base)],
+            ['no-foreign-paths', async () => noForeignPaths(primary, base)],
+            ['harness-versions', async () => harnessVersions(adapter)],
+        ];
+        for (const [check, run] of runners) {
+            let outcome;
+            try {
+                outcome = await run();
+            }
+            catch (err) {
+                outcome = `the check itself threw: ${describeError(err)}`;
+            }
+            if (outcome === SKIP)
+                continue;
+            if (outcome === undefined)
+                passed.push(check);
+            else
+                failed.push({ check, detail: outcome });
+        }
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+    return { adapter: adapter.id, passed, failed, ok: failed.length === 0 };
+}
+/** One line for a pass, one line per failure otherwise — the shape a CI log wants. */
+export function formatContractResult(result) {
+    if (result.ok)
+        return `${result.adapter}: ok (${result.passed.length} checks)`;
+    const total = result.passed.length + result.failed.length;
+    const lines = result.failed.map((f) => `  - ${f.check}: ${f.detail}`);
+    return [`${result.adapter}: ${result.failed.length}/${total} checks failed`, ...lines].join('\n');
+}
+async function attempt(adapter, base) {
+    try {
+        return { launch: await adapter.prepare(clone(base)) };
+    }
+    catch (err) {
+        return { error: describeError(err) };
+    }
+}
+async function baseContext(root, over) {
+    const cwd = over.cwd ?? join(root, 'work');
+    const runDir = over.runDir ?? join(root, 'run');
+    // Only create the directories we invented: a caller-supplied path is theirs to manage.
+    if (over.cwd === undefined)
+        await mkdir(cwd, { recursive: true });
+    if (over.runDir === undefined)
+        await mkdir(runDir, { recursive: true });
+    return {
+        runId: 'run_contract',
+        proxyUrl: CONTRACT_PROXY,
+        // An adapter that takes its command from argv (generic-openai) gets one without special-casing.
+        userArgs: ['orca-contract-agent', '--task', 'contract check'],
+        env: {},
+        ...over,
+        cwd,
+        runDir,
+    };
+}
+function clone(ctx) {
+    return structuredClone(ctx);
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function notVerified(check) {
+    return `not verified: prepare() rejected (see ${check})`;
+}
+function idFormat(adapter) {
+    const { id } = adapter;
+    if (typeof id !== 'string' || id.trim() === '') {
+        return ('id is empty; it is how a user names the adapter on the command line and how a trace ' +
+            'records which adapter produced it');
+    }
+    if (!ID_FORMAT.test(id)) {
+        return `id '${id}' is not lowercase kebab-case; ids appear in 'orca record <id>', in run manifests and in URLs, so mixed case and underscores turn into support questions`;
+    }
+    return undefined;
+}
+async function detectResolves(adapter, base, missing) {
+    const probes = [
+        ['a directory that exists', base.cwd],
+        ['a path that does not exist', missing],
+    ];
+    for (const [label, dir] of probes) {
+        let value;
+        try {
+            value = await adapter.detect(dir);
+        }
+        catch (err) {
+            return `detect() rejected for ${label}: ${describeError(err)}. AdapterRegistry treats a throwing detector as "no", so this adapter would silently never be auto-selected — and any caller that does not guard loses detection for every other adapter too. Answer false instead`;
+        }
+        if (typeof value !== 'boolean') {
+            return `detect() resolved ${JSON.stringify(value)} for ${label}; callers write 'if (await adapter.detect(cwd))', so any truthy value silently claims the workspace`;
+        }
+    }
+    return undefined;
+}
+function prepareShape(primary) {
+    if ('error' in primary)
+        return `prepare() rejected: ${primary.error}`;
+    const { launch } = primary;
+    const problems = [];
+    if (typeof launch?.command !== 'string' || launch.command === '') {
+        problems.push('command must be a non-empty string — it is what gets spawned');
+    }
+    if (!Array.isArray(launch?.args) || !launch.args.every((a) => typeof a === 'string')) {
+        problems.push('args must be an array of strings, never a pre-joined command line');
+    }
+    if (!isStringRecord(launch?.env)) {
+        problems.push('env must be an object of string values, which is all a child process can carry');
+    }
+    return problems.length > 0 ? problems.join('; ') : undefined;
+}
+/**
+ * The check that catches adapter rot. If the harness moves to a new variable and nobody updates
+ * the adapter, capture returns nothing while every other signal — exit code, output, the agent's
+ * own answers — still says the run worked.
+ */
+function redirectsModelTraffic(primary, base) {
+    if ('error' in primary)
+        return notVerified('prepare-shape');
+    const env = primary.launch.env;
+    if (!isStringRecord(env))
+        return notVerified('prepare-shape');
+    // Any base-URL-shaped variable counts, not only the three orca happens to know: a harness with
+    // its own spelling — grok-cli reads `GROK_BASE_URL` — is redirected just as effectively. So is
+    // an adapter that installs the fetch hook instead, for a harness that reads no variable at all.
+    // Narrowing this to three names would have failed both of those for setting the wrong thing,
+    // when what they set is the only thing that works.
+    //
+    // This never detected adapter *rot* on its own — an adapter still setting a variable the harness
+    // renamed sets a base-URL variable too. The harness fixtures are what catch that, by recording
+    // the exact names. What this catches is an adapter that redirects nothing whatsoever.
+    const redirected = Object.entries(env).filter(([name, value]) => BASE_URL_LIKE.test(name) && value !== '');
+    const hooked = readEnv(env, 'ORCA_PROXY_URL') !== undefined;
+    if (redirected.length === 0 && !hooked) {
+        return `prepare() set no base-url variable (none of ${MODEL_BASE_URL_VARS.join(', ')}, nor anything else ending _BASE_URL or _API_BASE) and installed no fetch hook, so nothing points the harness at the proxy and the run records no model traffic at all`;
+    }
+    const host = hostOf(base.proxyUrl) ?? base.proxyUrl;
+    const wrong = Object.entries(env)
+        .filter(([name]) => BASE_URL_LIKE.test(name))
+        .filter(([, value]) => !pointsAtHost(value, host));
+    if (wrong.length > 0) {
+        const names = wrong.map(([name, value]) => `${name}=${value}`).join(', ');
+        return `${names} does not point at the proxy (${base.proxyUrl}); traffic on that origin goes straight to the provider and never reaches the trace`;
+    }
+    return undefined;
+}
+/**
+ * An invented credential is not a convenience: harnesses pick a provider from which credentials
+ * are present, so fabricating one can change which model the run calls. `passKey` substitutes an
+ * obviously-fake placeholder for the provider the harness actually speaks; anything beyond that
+ * has to come from the user's own environment.
+ */
+async function noInventedKeys(adapter, base) {
+    const bare = await attempt(adapter, { ...base, env: {} });
+    if ('error' in bare)
+        return notVerified('prepare-shape');
+    if (!isStringRecord(bare.launch.env))
+        return notVerified('prepare-shape');
+    const invented = Object.entries(bare.launch.env).filter(([name]) => CREDENTIAL_LIKE.test(name));
+    const fabricated = invented
+        .filter(([, value]) => value !== PLACEHOLDER_KEY)
+        .map(([name]) => name);
+    if (fabricated.length > 0) {
+        // Never echo the value: it may be a real credential read from somewhere unexpected.
+        return `prepare() set ${fabricated.join(', ')} to a value ctx.env did not contain. If the harness refuses to start without a credential use passKey(), which substitutes the recognisable placeholder '${PLACEHOLDER_KEY}'`;
+    }
+    const families = [...new Set(invented.map(([name]) => providerFamily(name)))];
+    if (families.length < 2)
+        return undefined;
+    // With one provider's credential already in hand, inventing the other's is what flips the
+    // harness's provider auto-selection — and a recorded run then answers from a different model
+    // than the same command would without recording.
+    for (const family of families) {
+        const donor = invented.find(([name]) => providerFamily(name) === family)?.[0];
+        if (donor === undefined)
+            continue;
+        const probeEnv = { [donor]: PROBE_KEY };
+        const probe = await attempt(adapter, { ...base, env: probeEnv });
+        if ('error' in probe)
+            return notVerified('prepare-shape');
+        const stillInvented = Object.keys(probe.launch.env).filter((name) => CREDENTIAL_LIKE.test(name) &&
+            providerFamily(name) !== family &&
+            readEnv(probeEnv, name) === undefined);
+        if (stillInvented.length > 0) {
+            return `with only ${donor} in ctx.env, prepare() still invents ${stillInvented.join(', ')}; a harness that picks its provider from the credentials it can see will pick a different one under recording. Use passThrough() for a second provider`;
+        }
+    }
+    return undefined;
+}
+/**
+ * `orca record` hands the adapter `process.env` itself as `ctx.env` and the parsed argv as
+ * `ctx.userArgs`, so a mutation edits the recorder's own environment and the argv it writes into
+ * the manifest — which is then replayed.
+ */
+async function noCtxMutation(adapter, base) {
+    const ctx = clone(base);
+    const before = structuredClone(ctx);
+    try {
+        await adapter.prepare(ctx);
+    }
+    catch {
+        return notVerified('prepare-shape');
+    }
+    if (isDeepStrictEqual(ctx, before))
+        return undefined;
+    const fields = Object.keys(before).filter((key) => !isDeepStrictEqual(ctx[key], before[key]));
+    return `prepare() mutated ctx.${fields.join(', ctx.')}; the caller owns that object and reuses it — copy instead, e.g. args: [...ctx.userArgs]`;
+}
+/** Replay prepares the same context again. Anything that drifts turns into a false divergence. */
+async function deterministic(adapter, base) {
+    const first = await attempt(adapter, base);
+    const second = await attempt(adapter, base);
+    if ('error' in first || 'error' in second)
+        return notVerified('prepare-shape');
+    const drifted = ['command', 'args', 'env'].filter((key) => !isDeepStrictEqual(first.launch[key], second.launch[key]));
+    if (drifted.length === 0)
+        return undefined;
+    return `two prepare() calls on the same ctx disagreed on ${drifted.join(', ')}; replay prepares the same context again, so anything random or time-based here reads as a divergence`;
+}
+/**
+ * Cheap leak check. Launch env is written into the run manifest and shared with bug reports, so an
+ * absolute path from outside the run is both a privacy leak and a value nobody else can reproduce.
+ */
+function noForeignPaths(primary, base) {
+    if ('error' in primary)
+        return notVerified('prepare-shape');
+    const env = primary.launch.env;
+    if (!isStringRecord(env))
+        return notVerified('prepare-shape');
+    for (const [name, value] of Object.entries(env)) {
+        for (const candidate of absolutePaths(value)) {
+            if (isInside(candidate, base.runDir) || isInside(candidate, base.cwd))
+                continue;
+            return `env ${name} contains ${candidate}, which is outside ctx.runDir and ctx.cwd; write scratch config under ctx.runDir so the launch is reproducible on a machine that is not yours`;
+        }
+    }
+    return undefined;
+}
+function harnessVersions(adapter) {
+    const range = adapter.harnessVersions;
+    if (range === undefined)
+        return SKIP;
+    if (typeof range !== 'string' || range.trim() === '') {
+        return 'harnessVersions is set but empty; leave it off entirely rather than declaring a range that matches nothing';
+    }
+    return isSemverRange(range)
+        ? undefined
+        : `harnessVersions '${range}' is not a semver range; it is the field that says which harness versions this adapter was actually verified against, so 'latest' or a date says nothing`;
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === 'string'));
+}
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pointsAtHost(value, host) {
+    const valueHost = hostOf(value);
+    return valueHost !== undefined ? valueHost === host : value.includes(host);
+}
+/** `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are one provider; `OPENAI_API_KEY` is another. */
+function providerFamily(name) {
+    return name.split('_')[0] ?? name;
+}
+const URL_LIKE = /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi;
+const ABSOLUTE_PATH = /(?:^|[\s:;,"'=])((?:[A-Za-z]:[\\/]|\/)[^\s:;,"'=]*)/g;
+/** Absolute-looking paths in a value, ignoring the path component of any URL inside it. */
+function absolutePaths(value) {
+    const withoutUrls = value.replace(URL_LIKE, ' ');
+    const found = [];
+    for (const match of withoutUrls.matchAll(ABSOLUTE_PATH)) {
+        const path = match[1];
+        // One segment (`/v1`, `/tmp`) is not a leak; a leak has a directory in it.
+        if (path !== undefined && path.split(/[\\/]/).filter(Boolean).length > 1)
+            found.push(path);
+    }
+    return found;
+}
+function isInside(path, base) {
+    if (base === '')
+        return false;
+    const prefix = base.endsWith('/') ? base : `${base}/`;
+    return path === base || path.startsWith(prefix);
+}
+const SEMVER_COMPARATOR = /^(?:[<>]=?|=|[~^])?v?(?:\d+|[xX*])(?:\.(?:\d+|[xX*]))?(?:\.(?:\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Shape check only — no semver dependency, and a range that parses is not a range anyone verified.
+ * It exists to catch `latest`, `1.0` typoed as `v1,0`, and dates.
+ */
+function isSemverRange(range) {
+    const parts = range.split('||');
+    return parts.every((part) => {
+        const tokens = part
+            .replace(/([<>=~^]+)\s+/g, '$1')
+            .trim()
+            .split(/\s+/)
+            .filter((t) => t !== '');
+        if (tokens.length === 0)
+            return false;
+        return tokens.every((token) => token === '*' || token === '-' || SEMVER_COMPARATOR.test(token));
+    });
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/detect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Detection runs before every recording, and a detector that throws would take the whole run with
+ * it. Every helper here answers false instead of failing.
+ */
+export declare function hasBinary(name: string): Promise<boolean>;
+/**
+ * The path a launcher must actually spawn, or undefined when the name is not on PATH.
+ *
+ * Detection and launching have to agree. On Windows an npm-installed agent is three shims —
+ * `claude`, `claude.cmd`, `claude.ps1` — and only the `.cmd` is something `CreateProcess` will
+ * run. `spawn` does no PATHEXT resolution of its own, so a launcher handed the bare name finds
+ * the extensionless shell script, cannot execute it, and reports ENOENT for an agent that
+ * `orca doctor` had just called present. Resolving here, against the same PATHEXT walk detection
+ * uses, is what keeps the two answers the same.
+ *
+ * Not `shell: true`: that would hand the agent's own arguments to a command interpreter.
+ */
+export declare function resolveBinary(name: string): Promise<string | undefined>;
+/** What `spawn` must actually be given to launch `command` with `args`. */
+export interface LaunchTarget {
+    file: string;
+    args: string[];
+    /** True only for a Windows batch shim, which `spawn` refuses to run any other way. */
+    shell: boolean;
+}
+/**
+ * Resolve a command to something `spawn` can launch on this platform.
+ *
+ * Windows makes this three cases rather than one. An npm-installed agent is a set of shims —
+ * `claude`, `claude.cmd`, `claude.ps1` — and `spawn` does no PATHEXT resolution, so the bare name
+ * finds the extensionless shell script and fails ENOENT. Resolving to the `.cmd` then hits the
+ * second wall: since the batch-injection fix, Node refuses to spawn `.cmd` or `.bat` without a
+ * shell and answers EINVAL. Only a batch shim needs that shell, and only then do the arguments
+ * have to survive cmd.exe, which is what the quoting is for. A real `.exe` still spawns directly.
+ */
+export declare function resolveLaunch(command: string, args: string[]): Promise<LaunchTarget>;
+/**
+ * The home directory as the *child process* will see it. A host that hands us a rebuilt env object
+ * detaches `process.env` from the OS environment, and `os.homedir()` then answers for a home the
+ * agent will never be launched with — so the JS-visible value wins where it is set.
+ */
+export declare function homeDir(): string;
+/** True when `~/<relative>` exists — the cheap "this agent has been run here before" signal. */
+export declare function homeDirHas(relative: string): boolean;
+/** True when any of the given binaries or home-relative config paths is present. */
+export declare function detectAgent(binaries: string[], homePaths: string[]): Promise<boolean>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK7E;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sFAAsF;IACtF,KAAK,EAAE,OAAO,CAAC;CAChB;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAK1F;AAwBD;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED,oFAAoF;AACpF,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAM3F"}

package/dist/detect.js

@@ -0,0 +1,123 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, extname, join } from 'node:path';
+/**
+ * Detection runs before every recording, and a detector that throws would take the whole run with
+ * it. Every helper here answers false instead of failing.
+ */
+export async function hasBinary(name) {
+    if (process.platform === 'win32') {
+        return (await resolveWindowsBinary(name, process.env.PATH ?? '')) !== undefined;
+    }
+    return new Promise((resolve) => {
+        // execFile, never a shell: `name` reaches the lookup as one argv element, so an agent id
+        // carrying shell metacharacters cannot become a command.
+        execFile('which', [name], { timeout: 5_000 }, (err, stdout) => {
+            resolve(!err && stdout.trim().length > 0);
+        });
+    });
+}
+/**
+ * The path a launcher must actually spawn, or undefined when the name is not on PATH.
+ *
+ * Detection and launching have to agree. On Windows an npm-installed agent is three shims —
+ * `claude`, `claude.cmd`, `claude.ps1` — and only the `.cmd` is something `CreateProcess` will
+ * run. `spawn` does no PATHEXT resolution of its own, so a launcher handed the bare name finds
+ * the extensionless shell script, cannot execute it, and reports ENOENT for an agent that
+ * `orca doctor` had just called present. Resolving here, against the same PATHEXT walk detection
+ * uses, is what keeps the two answers the same.
+ *
+ * Not `shell: true`: that would hand the agent's own arguments to a command interpreter.
+ */
+export async function resolveBinary(name) {
+    if (process.platform !== 'win32')
+        return name;
+    // An explicit path is already the answer; PATH does not enter into it.
+    if (name.includes('/') || name.includes('\\'))
+        return name;
+    return resolveWindowsBinary(name, process.env.PATH ?? '');
+}
+/** cmd.exe reads these before the program does, so they have to be escaped for it first. */
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/**
+ * Quote one argument so that cmd.exe hands the program back exactly the string we started with.
+ *
+ * Two parsers run in sequence: cmd.exe strips `^` escapes, then the program's own CommandLineToArgv
+ * splits what is left. So the backslash-before-quote doubling has to happen first, and the `^`
+ * escaping of everything — the quotes we just added included — second.
+ */
+function quoteForCmd(arg) {
+    let quoted = arg.replace(/(\\*)"/g, '$1$1\\"');
+    quoted = quoted.replace(/(\\*)$/, '$1$1');
+    return `"${quoted}"`.replace(CMD_META, '^$&');
+}
+/**
+ * Resolve a command to something `spawn` can launch on this platform.
+ *
+ * Windows makes this three cases rather than one. An npm-installed agent is a set of shims —
+ * `claude`, `claude.cmd`, `claude.ps1` — and `spawn` does no PATHEXT resolution, so the bare name
+ * finds the extensionless shell script and fails ENOENT. Resolving to the `.cmd` then hits the
+ * second wall: since the batch-injection fix, Node refuses to spawn `.cmd` or `.bat` without a
+ * shell and answers EINVAL. Only a batch shim needs that shell, and only then do the arguments
+ * have to survive cmd.exe, which is what the quoting is for. A real `.exe` still spawns directly.
+ */
+export async function resolveLaunch(command, args) {
+    if (process.platform !== 'win32')
+        return { file: command, args, shell: false };
+    const file = (await resolveBinary(command)) ?? command;
+    if (!/\.(cmd|bat)$/i.test(file))
+        return { file, args, shell: false };
+    return { file: quoteForCmd(file), args: args.map(quoteForCmd), shell: true };
+}
+async function resolveWindowsBinary(name, pathVar) {
+    const extensions = extname(name) !== ''
+        ? ['']
+        : (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+    for (const entry of pathVar.split(delimiter)) {
+        if (entry === '')
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(entry, `${name}${extension.toLowerCase()}`);
+            try {
+                if ((await stat(candidate)).isFile()) {
+                    await access(candidate);
+                    return candidate;
+                }
+            }
+            catch {
+                // Keep searching the rest of PATH. Detection must never take the CLI down.
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * The home directory as the *child process* will see it. A host that hands us a rebuilt env object
+ * detaches `process.env` from the OS environment, and `os.homedir()` then answers for a home the
+ * agent will never be launched with — so the JS-visible value wins where it is set.
+ */
+export function homeDir() {
+    return process.env['HOME'] || process.env['USERPROFILE'] || homedir();
+}
+/** True when `~/<relative>` exists — the cheap "this agent has been run here before" signal. */
+export function homeDirHas(relative) {
+    try {
+        return existsSync(join(homeDir(), relative));
+    }
+    catch {
+        return false;
+    }
+}
+/** True when any of the given binaries or home-relative config paths is present. */
+export async function detectAgent(binaries, homePaths) {
+    if (homePaths.some(homeDirHas))
+        return true;
+    for (const bin of binaries) {
+        if (await hasBinary(bin))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Placeholder key for runs where the user has no credential in the environment. The proxy is
+ * holding the real one (or serving from a trace), but SDK clients refuse to start without
+ * *something* — so an obviously-fake value beats an empty string that looks like a real key.
+ */
+export declare const PLACEHOLDER_KEY = "orca-recorded";
+/** An env var set to the empty string is unset for our purposes: an empty key breaks clients. */
+export declare function readEnv(env: Record<string, string | undefined>, name: string): string | undefined;
+/** Joins a path onto the proxy url without producing `//`, whether or not the base ends in `/`. */
+export declare function proxyBase(proxyUrl: string, path?: string): string;
+/** Copies `name` from the run environment into the launch overlay, or a placeholder if unset. */
+export declare function passKey(target: Record<string, string>, env: Record<string, string | undefined>, name: string): void;
+/** Copies `name` only if it is actually set — used for optional tokens we must not invent. */
+export declare function passThrough(target: Record<string, string>, env: Record<string, string | undefined>, name: string): void;
+/**
+ * Point base-URL variables orca does not know about at the proxy.
+ *
+ * Read from `ORCA_BASE_URL_VARS`: a comma-separated list of variable names, each optionally with
+ * `=<path>` when the origin is not OpenAI-shaped. `/v1` is the default suffix because that is what
+ * an OpenAI-compatible override wants, and it is what every example in the wild ends in.
+ *
+ * This exists because enumerating them is hopeless. Hermes alone overrides per provider —
+ * `NOVITA_BASE_URL`, `GLM_BASE_URL`, `KIMI_BASE_URL`, `MINIMAX_BASE_URL`, `HF_BASE_URL`,
+ * `NEBIUS_BASE_URL` and a dozen more in one `.env.example` — and a list of names baked in here
+ * would be stale the week after it was written. A harness the author has never heard of is the
+ * normal case, so it gets a mechanism rather than a pull request.
+ *
+ * The variable is consumed, never forwarded: it names other variables and means nothing downstream.
+ */
+export declare function applyNamedBaseUrls(target: Record<string, string>, env: Record<string, string | undefined>, proxyUrl: string): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C,iGAAiG;AACjG,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjG;AAED,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CAG7D;AAED,iGAAiG;AACjG,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,IAAI,CAEN;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,IAAI,CAGN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,QAAQ,EAAE,MAAM,GACf,IAAI,CAUN"}