@bitmagic/cli 0.1.68-dev.3 → 0.1.68-dev.5

package/dist/event/launch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * How each agent is pointed at the event proxy.
+ *
+ * Nothing here writes a config file. The participant's agent is spawned with the environment
+ * already set, which is the only approach that works for both agents and leaves nothing behind
+ * when the proxy is torn down and the keys stop working:
+ *
+ *   - The CLI has never written to ~/.claude/ or ~/.codex/, and editing a participant's global
+ *     Codex config is not something a game SDK should do.
+ *   - A `.claude/settings.json` env block only takes effect once the directory is trusted, which
+ *     a freshly scaffolded project is not (cli/lab/drivers/claude-code.ts documents the same
+ *     trap and sidesteps it the same way).
+ *   - Codex config is TOML, and this repo has no TOML writer, dependency or merge precedent.
+ *
+ * The shape of "spawn an agent with a modified environment" is taken from cli/lab/drivers/ —
+ * `baseEnv()` in types.ts and the `-c key=value` overrides in codex.ts. That code is the lab
+ * harness and is never built into dist/, so this is a copied pattern rather than an import.
+ */
+/** Model aliases the event proxy serves. Anything else is a 400 — it knows only its own names. */
+export declare const OPUS_ALIAS = "claude-5.5-opus";
+/** Codex's model: GPT-6 Sol on Bedrock, the same sponsor account that serves Opus. */
+export declare const CODEX_MODEL = "bedrock-gpt-6-sol";
+/** The env var Codex is told to read the key from, via `env_key`. */
+export declare const CODEX_KEY_ENV = "BITMAGIC_EVENT_KEY";
+export type EventAgent = 'claude' | 'codex';
+export interface LaunchSpec {
+    bin: string;
+    argv: string[];
+    env: Record<string, string | undefined>;
+}
+/** The shells `bitmagic event env` can print for. */
+export type EnvShell = 'posix' | 'powershell' | 'cmd';
+/**
+ * The two clients want DIFFERENT forms of the same URL, and swapping them produces a 404 that
+ * reads like the proxy is down:
+ *
+ *   Claude Code  the bare host  — it appends /v1/messages itself
+ *   Codex        host + /v1     — an OpenAI-compatible base, no trailing slash
+ *
+ * docs/ci-ai-credentials.md warns about exactly this (and about reusing getLiteLLMProxyUrl(),
+ * which already ends in /v1). Both forms are derived here so no caller has to remember which.
+ */
+export declare function anthropicBaseUrl(baseUrl: string): string;
+export declare function openAiBaseUrl(baseUrl: string): string;
+/**
+ * Claude Code's environment: the block docs/ci-ai-credentials.md records and every Claude Code
+ * workflow proves daily.
+ *
+ * All three model pins are required, not just Opus. Claude Code makes background calls of its
+ * own with Anthropic-native model ids, and the proxy serves only its own aliases — so naming
+ * only the Opus default leaves those background calls 400ing. There is no Sonnet on the proxy,
+ * which is why Sonnet is pinned to Opus rather than to a Sonnet alias.
+ */
+export declare function claudeEnv(key: string, baseUrl: string, parentEnv?: Record<string, string | undefined>, platform?: string): Record<string, string | undefined>;
+/**
+ * Codex is configured through an isolated CODEX_HOME rather than `-c` overrides — see
+ * event/codex-home.ts for why overrides cannot work against a real installation.
+ */
+export declare function codexEnv(key: string, codexHome: string, parentEnv?: Record<string, string | undefined>): Record<string, string | undefined>;
+/**
+ * Everything needed to spawn one agent. Pure — the caller does the spawning, and for Codex the
+ * caller has already materialised `codexHome` (ensureCodexHome).
+ */
+export declare function launchSpec(agent: EventAgent, key: string, baseUrl: string, codexHome: string, passthrough?: string[], parentEnv?: Record<string, string | undefined>, platform?: string): LaunchSpec;
+/** Which shell `bitmagic event env` should print for when nobody said. */
+export declare function defaultEnvShell(platform?: string): EnvShell;
+/**
+ * The environment `bitmagic event env` prints, for anyone wiring it up by hand.
+ *
+ * Per-shell because this is the documented fallback for whoever the launcher failed, and a Windows
+ * participant is the likeliest person to reach it. POSIX `export` lines are a syntax error in both
+ * `cmd.exe` and PowerShell, so printing only those would send exactly the person who needs help
+ * somewhere that cannot work.
+ */
+export declare function exportLines(key: string, baseUrl: string, shell?: EnvShell): string[];

package/dist/event/launch.js

@@ -0,0 +1,188 @@
+/**
+ * How each agent is pointed at the event proxy.
+ *
+ * Nothing here writes a config file. The participant's agent is spawned with the environment
+ * already set, which is the only approach that works for both agents and leaves nothing behind
+ * when the proxy is torn down and the keys stop working:
+ *
+ *   - The CLI has never written to ~/.claude/ or ~/.codex/, and editing a participant's global
+ *     Codex config is not something a game SDK should do.
+ *   - A `.claude/settings.json` env block only takes effect once the directory is trusted, which
+ *     a freshly scaffolded project is not (cli/lab/drivers/claude-code.ts documents the same
+ *     trap and sidesteps it the same way).
+ *   - Codex config is TOML, and this repo has no TOML writer, dependency or merge precedent.
+ *
+ * The shape of "spawn an agent with a modified environment" is taken from cli/lab/drivers/ —
+ * `baseEnv()` in types.ts and the `-c key=value` overrides in codex.ts. That code is the lab
+ * harness and is never built into dist/, so this is a copied pattern rather than an import.
+ */
+/** Model aliases the event proxy serves. Anything else is a 400 — it knows only its own names. */
+export const OPUS_ALIAS = 'claude-5.5-opus';
+const HAIKU_ALIAS = 'claude-4.5-haiku';
+/** Codex's model: GPT-6 Sol on Bedrock, the same sponsor account that serves Opus. */
+export const CODEX_MODEL = 'bedrock-gpt-6-sol';
+/** The env var Codex is told to read the key from, via `env_key`. */
+export const CODEX_KEY_ENV = 'BITMAGIC_EVENT_KEY';
+/**
+ * Variables that select a model provider, and so OUTRANK the event key.
+ *
+ * Claude Code's documented credential precedence puts cloud-provider selection at rank 1 and
+ * `ANTHROPIC_AUTH_TOKEN` — what this launcher sets — at rank 2. A participant who already uses
+ * Claude Code against their employer's Bedrock has `CLAUDE_CODE_USE_BEDROCK=1` exported, and it
+ * would win: their session would run on their own AWS account, the event key would spend nothing,
+ * and no error would appear anywhere. The sponsor's credits go unused and the participant's
+ * employer gets the bill.
+ *
+ * At an AWS-sponsored event the people carrying this variable are not a rare case — they are the
+ * likeliest attendees.
+ *
+ * The lower-ranked credentials need no handling: `ANTHROPIC_API_KEY` (3), `apiKeyHelper` (4),
+ * `CLAUDE_CODE_OAUTH_TOKEN` (5), profiles (6) and a `/login` subscription (7) all lose to the
+ * bearer token on their own. ANTHROPIC_API_KEY is removed anyway because setting it alongside
+ * ANTHROPIC_AUTH_TOKEN is explicitly forbidden.
+ */
+const CLAUDE_PROVIDER_SELECTORS = ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'];
+/** Session-scoped variables a spawning Claude Code exports, which must not reach a fresh agent. */
+const CLAUDE_SESSION_MARKERS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_CODE_SESSION_ATTENDED',
+    'CLAUDE_CODE_MESSAGING_SOCKET',
+    'CLAUDE_CODE_MESSAGING_TOKEN',
+    'CLAUDE_CODE_EXECPATH',
+    'CLAUDE_PID',
+];
+/**
+ * Removes a variable from the child environment.
+ *
+ * Windows environment names are CASE-INSENSITIVE: `Anthropic_Api_Key` set through the System
+ * Properties dialog is the same variable Claude Code reads as `ANTHROPIC_API_KEY`, but
+ * `delete env.ANTHROPIC_API_KEY` does not remove it — so the one condition this code exists to
+ * prevent survives the launch. On POSIX the opposite is true and a case-insensitive sweep would
+ * delete unrelated variables, so the platform decides.
+ */
+function deleteEnvVar(env, name, platform) {
+    if (platform !== 'win32') {
+        delete env[name];
+        return;
+    }
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === lower)
+            delete env[key];
+    }
+}
+/**
+ * The two clients want DIFFERENT forms of the same URL, and swapping them produces a 404 that
+ * reads like the proxy is down:
+ *
+ *   Claude Code  the bare host  — it appends /v1/messages itself
+ *   Codex        host + /v1     — an OpenAI-compatible base, no trailing slash
+ *
+ * docs/ci-ai-credentials.md warns about exactly this (and about reusing getLiteLLMProxyUrl(),
+ * which already ends in /v1). Both forms are derived here so no caller has to remember which.
+ */
+export function anthropicBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+export function openAiBaseUrl(baseUrl) {
+    return `${anthropicBaseUrl(baseUrl)}/v1`;
+}
+/**
+ * Claude Code's environment: the block docs/ci-ai-credentials.md records and every Claude Code
+ * workflow proves daily.
+ *
+ * All three model pins are required, not just Opus. Claude Code makes background calls of its
+ * own with Anthropic-native model ids, and the proxy serves only its own aliases — so naming
+ * only the Opus default leaves those background calls 400ing. There is no Sonnet on the proxy,
+ * which is why Sonnet is pinned to Opus rather than to a Sonnet alias.
+ */
+export function claudeEnv(key, baseUrl, parentEnv = process.env, platform = process.platform) {
+    const env = { ...parentEnv };
+    // Setting ANTHROPIC_API_KEY alongside ANTHROPIC_AUTH_TOKEN is explicitly forbidden, and a
+    // participant who already uses Claude Code on their own key will have one exported. Removing
+    // it is the main thing this launcher can do that a copied export block cannot.
+    deleteEnvVar(env, 'ANTHROPIC_API_KEY', platform);
+    // ANTHROPIC_MODEL, if the participant has pinned one for their own use, wins over the
+    // DEFAULT_* vars below and names a model the proxy does not serve — a 400 on every call.
+    deleteEnvVar(env, 'ANTHROPIC_MODEL', platform);
+    // Session markers from a Claude Code that spawned us — participants really do ask their agent
+    // to run the setup for them. cli/lab/drivers/types.ts drops the first two so a nested agent
+    // does not think it is inside another session; the rest are handles (sockets, tokens, pids)
+    // that name a process this one is not. CLAUDE_CONFIG_DIR is deliberately left alone: that one
+    // is a standing preference rather than session state.
+    //
+    // Note this is NOT what causes Claude Code's `unrecognized_model: claude-5.5-opus[1m]` line —
+    // that appears with a clean environment and no launcher at all, because Claude Code's own
+    // model registry does not know the proxy's aliases. It is cosmetic; the call succeeds.
+    // A provider selector outranks the event key outright — see CLAUDE_PROVIDER_SELECTORS. Removing
+    // these is the difference between the sponsor paying for the session and the participant's own
+    // employer paying for it without either of them being told.
+    for (const selector of CLAUDE_PROVIDER_SELECTORS)
+        deleteEnvVar(env, selector, platform);
+    for (const marker of CLAUDE_SESSION_MARKERS)
+        deleteEnvVar(env, marker, platform);
+    env.ANTHROPIC_BASE_URL = anthropicBaseUrl(baseUrl);
+    env.ANTHROPIC_AUTH_TOKEN = key;
+    env.ANTHROPIC_DEFAULT_OPUS_MODEL = OPUS_ALIAS;
+    env.ANTHROPIC_DEFAULT_SONNET_MODEL = OPUS_ALIAS;
+    env.ANTHROPIC_DEFAULT_HAIKU_MODEL = HAIKU_ALIAS;
+    env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = '1';
+    return env;
+}
+/**
+ * Codex is configured through an isolated CODEX_HOME rather than `-c` overrides — see
+ * event/codex-home.ts for why overrides cannot work against a real installation.
+ */
+export function codexEnv(key, codexHome, parentEnv = process.env) {
+    const env = { ...parentEnv };
+    env[CODEX_KEY_ENV] = key;
+    env.CODEX_HOME = codexHome;
+    return env;
+}
+/**
+ * Everything needed to spawn one agent. Pure — the caller does the spawning, and for Codex the
+ * caller has already materialised `codexHome` (ensureCodexHome).
+ */
+export function launchSpec(agent, key, baseUrl, codexHome, passthrough = [], parentEnv = process.env, platform = process.platform) {
+    if (agent === 'claude') {
+        return { bin: 'claude', argv: [...passthrough], env: claudeEnv(key, baseUrl, parentEnv, platform) };
+    }
+    // No argv configuration at all: the generated config.toml in CODEX_HOME carries the provider.
+    return { bin: 'codex', argv: [...passthrough], env: codexEnv(key, codexHome, parentEnv) };
+}
+/** Which shell `bitmagic event env` should print for when nobody said. */
+export function defaultEnvShell(platform = process.platform) {
+    return platform === 'win32' ? 'powershell' : 'posix';
+}
+/**
+ * The environment `bitmagic event env` prints, for anyone wiring it up by hand.
+ *
+ * Per-shell because this is the documented fallback for whoever the launcher failed, and a Windows
+ * participant is the likeliest person to reach it. POSIX `export` lines are a syntax error in both
+ * `cmd.exe` and PowerShell, so printing only those would send exactly the person who needs help
+ * somewhere that cannot work.
+ */
+export function exportLines(key, baseUrl, shell = defaultEnvShell()) {
+    const vars = [
+        ['ANTHROPIC_BASE_URL', anthropicBaseUrl(baseUrl)],
+        ['ANTHROPIC_AUTH_TOKEN', key],
+        ['ANTHROPIC_DEFAULT_OPUS_MODEL', OPUS_ALIAS],
+        ['ANTHROPIC_DEFAULT_SONNET_MODEL', OPUS_ALIAS],
+        ['ANTHROPIC_DEFAULT_HAIKU_MODEL', HAIKU_ALIAS],
+        ['CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS', '1'],
+        [CODEX_KEY_ENV, key],
+    ];
+    switch (shell) {
+        case 'powershell':
+            return vars.map(([name, value]) => `$env:${name} = "${value}"`);
+        case 'cmd':
+            // No quotes: cmd.exe would make them part of the value.
+            return vars.map(([name, value]) => `set ${name}=${value}`);
+        default:
+            return vars.map(([name, value]) => `export ${name}=${value}`);
+    }
+}
+//# sourceMappingURL=launch.js.map

package/dist/event/launch.js.map

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

package/dist/event/preflight.d.ts

@@ -0,0 +1,10 @@
+import { type EventAgent } from './launch.js';
+export interface PreflightResult {
+    /** What the proxy actually served, from `x-litellm-model-name`. */
+    servedModel: string;
+    /** Cost of this call in USD, from `x-litellm-response-cost`. Present once pricing resolves. */
+    cost: number | undefined;
+    /** Cumulative spend on this key in USD, from `x-litellm-key-spend`. */
+    keySpend: number | undefined;
+}
+export declare function preflight(key: string, baseUrl: string, agent?: EventAgent): Promise<PreflightResult>;

package/dist/event/preflight.js

@@ -0,0 +1,104 @@
+/**
+ * One tiny call against the event proxy, before the participant starts working.
+ *
+ * This is the same assertion every Claude Code workflow makes before it runs
+ * (.github/workflows/code-simplifier.yml, the "Verify Bedrock gateway" step): a 200 is not
+ * enough, because the proxy can serve a different model behind a perfectly healthy response.
+ * The only tell is the `x-litellm-model-name` header.
+ *
+ * The point is timing. Every failure here — dead proxy, mistyped key, exhausted budget, silent
+ * downgrade — otherwise shows up ten minutes into a session as something that reads like the
+ * agent being broken. Catching it at `setup` and at each launch costs one token and turns it
+ * into a sentence the participant can act on.
+ */
+import { CliError } from '../errors.js';
+import { CODEX_MODEL, OPUS_ALIAS, anthropicBaseUrl, openAiBaseUrl } from './launch.js';
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+/**
+ * Each agent is probed on the model and wire API it will actually use, so a proxy that serves
+ * Opus but not GPT (or the reverse) is caught before that agent starts, not after.
+ *
+ * Codex goes through the Responses API because that is what `wire_api = "responses"` makes it
+ * call; 16 is the smallest `max_output_tokens` the Responses API accepts.
+ */
+const PROBES = {
+    claude: {
+        label: 'Opus 5.5',
+        url: (baseUrl) => `${anthropicBaseUrl(baseUrl)}/v1/messages`,
+        headers: { 'anthropic-version': '2023-06-01' },
+        // One token: enough to prove the whole path works, cheap enough to run on every launch.
+        body: { model: OPUS_ALIAS, max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] },
+        served: ['opus-5-5', 'opus-5.5'],
+    },
+    codex: {
+        label: 'GPT-6 Sol',
+        url: (baseUrl) => `${openAiBaseUrl(baseUrl)}/responses`,
+        headers: {},
+        body: { model: CODEX_MODEL, max_output_tokens: 16, input: 'hi' },
+        served: ['gpt-6-sol'],
+    },
+};
+function numberHeader(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Maps the proxy's refusals onto advice. Anything unmapped keeps its status and body so a new
+ * failure mode is never silently rephrased as one of these.
+ */
+function refusal(status, body) {
+    if (status === 401 || status === 403) {
+        return new CliError('The event proxy rejected this key.\n' +
+            'Check it matches the card exactly — it starts with "sk-" and has no spaces.\n' +
+            'Re-run: bitmagic event setup --key sk-…', 1, 'event_key_rejected');
+    }
+    if (status === 429 && body.includes('budget')) {
+        return new CliError('This key has reached its spending limit.\n' +
+            'Your work is safe. Find one of the organisers — raising it takes a minute.', 1, 'event_budget_exceeded');
+    }
+    if (status === 429) {
+        return new CliError('The event proxy is rate-limiting this key. Wait a moment and try again.', 1, 'event_rate_limited');
+    }
+    return new CliError(`The event proxy returned HTTP ${status}.\n${body.slice(0, 300)}`, 1, 'event_proxy_error');
+}
+export async function preflight(key, baseUrl, agent = 'claude') {
+    const probe = PROBES[agent];
+    let response;
+    try {
+        response = await fetch(probe.url(baseUrl), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${key}`,
+                'content-type': 'application/json',
+                ...probe.headers,
+            },
+            body: JSON.stringify(probe.body),
+            signal: AbortSignal.timeout(PREFLIGHT_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new CliError(`Cannot reach the event proxy at ${anthropicBaseUrl(baseUrl)}.\n` +
+            'Check your network connection. If you are on event wifi, ask an organiser.\n' +
+            `(${error instanceof Error ? error.message : String(error)})`, 1, 'event_proxy_unreachable');
+    }
+    if (!response.ok) {
+        throw refusal(response.status, await response.text().catch(() => ''));
+    }
+    const servedModel = response.headers.get('x-litellm-model-name') ?? '';
+    if (!probe.served.some((name) => servedModel.includes(name))) {
+        // A 200 that did not come from the intended model means a fallback served it. Refusing here rather than
+        // warning is deliberate: the participant would otherwise spend their budget on a weaker
+        // model without ever being told, and the spend accounting would be wrong too.
+        throw new CliError(`The event proxy answered with "${servedModel || 'an unknown model'}" instead of ${probe.label}.\n` +
+            'That usually means the proxy is degraded. Tell an organiser before continuing.', 1, 'event_model_downgrade');
+    }
+    return {
+        servedModel,
+        cost: numberHeader(response.headers, 'x-litellm-response-cost'),
+        keySpend: numberHeader(response.headers, 'x-litellm-key-spend'),
+    };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/event/preflight.js.map

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

package/dist/event/resolve-agent.d.ts

@@ -0,0 +1,8 @@
+export type Exists = (candidate: string) => boolean;
+/**
+ * The absolute path of `name` on PATH, or `null` when it is not there.
+ *
+ * On anything but Windows the name is returned unchanged: `spawn` does the PATH search itself, and
+ * resolving it here would only add a way to disagree with the thing that actually launches it.
+ */
+export declare function resolveAgentBinary(name: string, env?: Record<string, string | undefined>, platform?: string, exists?: Exists): string | null;

package/dist/event/resolve-agent.js

@@ -0,0 +1,68 @@
+/**
+ * Finding the participant's `claude` / `codex` executable before spawning it.
+ *
+ * On POSIX this is not a problem worth solving: the name goes to `spawn`, which searches PATH and
+ * executes whatever it finds. On Windows it is the whole problem. `CreateProcess` — which is where
+ * a non-shell spawn ends up — does not consult PATHEXT and cannot execute a batch file at all, so
+ * `spawn('claude')` fails for every installation that is not literally a file named `claude`:
+ *
+ *   - `npm install -g @anthropic-ai/claude-code` writes `claude.cmd`. That is a batch shim, and
+ *     since the CVE-2024-27980 fix (Node 18.20.2 / 20.12.2) spawning one without `shell: true`
+ *     throws EINVAL rather than running it.
+ *   - The agents' own native installers write `claude.exe`, which runs fine — but only once
+ *     something has resolved the name to the file, extension included.
+ *
+ * So this module answers "which file", and `project/spawn-bin.ts` answers "how to run it". Keeping
+ * them apart is what lets a real `.exe` spawn directly, with no `cmd.exe` wrapped around an
+ * interactive terminal UI, while a `.cmd` shim still gets the shell it cannot run without.
+ *
+ * Pure, with PATH, PATHEXT and the existence probe injected, so the Windows behaviour is a test
+ * table rather than a machine we do not have — the same approach `binInvocation` and `openerFor`
+ * already take.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** What Windows uses when PATHEXT is unset. Only the executable kinds an agent could ship as. */
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+const realExists = (candidate) => {
+    try {
+        return fs.statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The absolute path of `name` on PATH, or `null` when it is not there.
+ *
+ * On anything but Windows the name is returned unchanged: `spawn` does the PATH search itself, and
+ * resolving it here would only add a way to disagree with the thing that actually launches it.
+ */
+export function resolveAgentBinary(name, env = process.env, platform = process.platform, exists = realExists) {
+    if (platform !== 'win32')
+        return name;
+    const pathValue = env.PATH ?? env.Path ?? '';
+    if (pathValue === '')
+        return null;
+    // An empty PATHEXT entry stands for the name exactly as given, which is how a extensionless
+    // executable (or one the participant typed with its extension) is still found.
+    const extensions = ['', ...(env.PATHEXT ?? DEFAULT_PATHEXT).split(';').filter((ext) => ext !== '')];
+    for (const dir of pathValue.split(';')) {
+        if (dir === '')
+            continue;
+        for (const ext of extensions) {
+            // `path.win32`, not `path.join`: the latter uses the separator of the machine running the
+            // code, so building a Windows path on a developer's Mac would produce `C:\dir/claude.exe`.
+            // The tests are the only place that happens, which is exactly where it would go unnoticed.
+            //
+            // Windows paths are case-insensitive, so the casing PATHEXT uses (`.EXE`) does not have to
+            // match the file's (`claude.exe`) — but the extension must be ON the candidate, because
+            // `statSync('…/claude')` does not find `claude.exe`.
+            const candidate = path.win32.join(dir, `${name}${ext}`);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-agent.js.map

package/dist/event/resolve-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-agent.js","sourceRoot":"","sources":["../../src/event/resolve-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,iGAAiG;AACjG,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAI9C,MAAM,UAAU,GAAW,CAAC,SAAS,EAAE,EAAE;IACvC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,MAA0C,OAAO,CAAC,GAAG,EACrD,WAAmB,OAAO,CAAC,QAAQ,EACnC,SAAiB,UAAU;IAE3B,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAEtC,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IAC7C,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAElC,4FAA4F;IAC5F,+EAA+E;IAC/E,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;IAEpG,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,GAAG,KAAK,EAAE;YAAE,SAAS;QACzB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,0FAA0F;YAC1F,2FAA2F;YAC3F,2FAA2F;YAC3F,EAAE;YACF,2FAA2F;YAC3F,wFAAwF;YACxF,qDAAqD;YACrD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC;YACxD,IAAI,MAAM,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/event/store.d.ts

@@ -0,0 +1,13 @@
+export interface EventKey {
+    /** Host root of the event proxy, no trailing slash and no `/v1`. See launch.ts. */
+    baseUrl: string;
+    key: string;
+    /** Epoch ms, for `bitmagic event status` to report when the key was stored. */
+    savedAt: number;
+}
+export declare function defaultBaseDir(): string;
+export declare function eventKeyPath(baseDir?: string): string;
+export declare function readEventKey(baseDir?: string): EventKey | null;
+export declare function writeEventKey(entry: EventKey, baseDir?: string): void;
+/** Returns false when there was nothing to forget, so `clear` can say so rather than imply it acted. */
+export declare function clearEventKey(baseDir?: string): boolean;

package/dist/event/store.js

@@ -0,0 +1,86 @@
+/**
+ * Where the sponsored-event API key lives on a participant's machine.
+ *
+ * Deliberately a SEPARATE file from credentials.json rather than another field in it. This is
+ * disposable state that stops working when the event proxy is torn down, and a participant
+ * deleting it afterwards — or us telling them to — must carry no risk to their login.
+ *
+ * File discipline is copied from config/credentials.ts: 0600 inside a 0700 directory, written
+ * through a temp file and renamed, chmod'd before and after because writeFileSync's `mode` only
+ * applies when it creates the file. A corrupt file is treated as absent, not as an error: the fix
+ * is always `bitmagic event setup` again, and a parse failure must not wedge the command that
+ * would repair it.
+ *
+ * Those modes are POSIX-only. Windows `chmod` toggles nothing but the read-only bit, so the file
+ * there is protected by the user profile's ACL and not by anything this module does — which is why
+ * `bitmagic event setup` does not claim otherwise on that platform.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+export function defaultBaseDir() {
+    return path.join(os.homedir(), '.bitmagic');
+}
+export function eventKeyPath(baseDir = defaultBaseDir()) {
+    return path.join(baseDir, 'event.json');
+}
+function isEventKey(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.baseUrl === 'string' &&
+        v.baseUrl.length > 0 &&
+        typeof v.key === 'string' &&
+        v.key.length > 0 &&
+        typeof v.savedAt === 'number' &&
+        Number.isFinite(v.savedAt));
+}
+export function readEventKey(baseDir = defaultBaseDir()) {
+    const filePath = eventKeyPath(baseDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        // A real filesystem problem must not be reported as "no key" — that sends the participant
+        // through setup again, which cannot fix a permissions error.
+        throw new CliError(`Cannot read ${filePath}: ${code ?? String(err)}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return isEventKey(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeEventKey(entry, baseDir = defaultBaseDir()) {
+    fs.mkdirSync(baseDir, { recursive: true, mode: DIR_MODE });
+    const filePath = eventKeyPath(baseDir);
+    const tmpPath = path.join(baseDir, `.event.json.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmpPath, `${JSON.stringify(entry, null, 2)}\n`, { mode: FILE_MODE });
+    fs.chmodSync(tmpPath, FILE_MODE);
+    fs.renameSync(tmpPath, filePath);
+    fs.chmodSync(filePath, FILE_MODE);
+    fs.chmodSync(baseDir, DIR_MODE);
+}
+/** Returns false when there was nothing to forget, so `clear` can say so rather than imply it acted. */
+export function clearEventKey(baseDir = defaultBaseDir()) {
+    try {
+        fs.unlinkSync(eventKeyPath(baseDir));
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw new CliError(`Cannot remove ${eventKeyPath(baseDir)}: ${code ?? String(err)}`);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/event/store.js.map

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

package/dist/project/reference.d.ts

@@ -1,34 +1,15 @@
+import { isSafeCandidateId, newCandidateId, type AcceptedReference as SharedAcceptedReference, type CandidateRecord } from '@bitmagic/asset-core/reference-record';
 export declare const REFERENCE_DIR: string;
 export declare function referenceDirPath(root: string): string;
 export declare function acceptedReferencePath(root: string): string;
 export declare function candidateImagePath(root: string, id: string): string;
-/** One generated candidate — a picture the creator may accept, iterate from, or ignore. */
-export interface CandidateRecord {
-    id: string;
-    /** The Asset Forger URL the generation returned. Short-lived; the accept re-hosts it. */
-    url: string;
-    /** The prompt actually sent, truncated — enough to recognise a candidate in a list. */
-    prompt: string;
-    /** The candidate this one was iterated from (`--from`), if any. */
-    from?: string;
-    /** An explicit `--reference-image-url` this candidate was steered by, if any. */
-    referenceImageUrl?: string;
-    createdAt: string;
-}
-/** The accepted reference — what every generator and forge inherits. */
-export interface AcceptedReference {
-    /** The URL generators are given: the re-hosted public URL, or the source URL when re-hosting failed. */
-    url: string;
-    /** False when re-hosting failed and `url` is the (expiring) source URL — worth re-accepting. */
-    hosted: boolean;
-    /** What was accepted, before any re-hosting. */
-    sourceUrl: string;
-    /** Absent when a bare URL was accepted rather than a generated candidate. */
-    candidateId?: string;
+/** The CLI keeps a local copy of the accepted bytes; the shared record has no such field. */
+export type AcceptedReference = SharedAcceptedReference & {
     /** The local copy, when bytes were available to keep. */
     imagePath?: string;
-    acceptedAt: string;
-}
+};
+export type { CandidateRecord };
+export { isSafeCandidateId, newCandidateId };
 export declare function readAcceptedReference(root: string): AcceptedReference | null;
 export declare function writeAcceptedReference(root: string, accepted: AcceptedReference): void;
 /** Remove the accepted reference. Candidates stay — clearing a decision is not deleting the work. */
@@ -37,10 +18,6 @@ export declare function readCandidate(root: string, id: string): CandidateRecord
 export declare function writeCandidate(root: string, record: CandidateRecord): void;
 /** Every readable candidate, newest first (ids sort chronologically by construction). */
 export declare function listCandidates(root: string): CandidateRecord[];
-/** `ref-<yyyymmdd-hhmmss>-<4 rand>` — short enough to type, sortable by creation time. */
-export declare function newCandidateId(now?: Date): string;
-/** Candidate ids become file names, so anything path-shaped is refused, never sanitised. */
-export declare function isSafeCandidateId(id: string): boolean;
 /** The two flags every reference-aware command declares (see REFERENCE_IMAGE_FLAG / NO_REFERENCE_FLAG). */
 export interface ReferenceFlagArgs {
     'reference-image-url'?: string;