@addai/node 0.30.12 → 0.30.14

package/dist/auto-update.d.ts

@@ -103,6 +103,9 @@ type ProbeShape = Partial<Record<HarnessId, {
     available?: boolean;
 }>>;
 export interface AutoUpdateDeps {
+    /** Optional admission gate for direct sessions. Legacy callers keep the existing update path. */
+    quiesceDirect?: () => Promise<boolean>;
+    releaseDirect?: () => void;
     /** The daemon token — only used to derive this node's slot. */
     token: () => string | null;
     /** True while this node holds a child process for a live run. */

package/dist/auto-update.js

@@ -143,6 +143,21 @@ function installedHarnesses(probe) {
 /** One pass. Exported so `ainode` can be made to do it on demand later, and
  *  so a test can drive it without waiting an hour. */
 async function runOnce(d) {
+    if (!d.quiesceDirect || shouldRun({ enabled: d.enabled(), busy: d.isBusy(), breakerOpen: d.breakerOpen() })) {
+        return runUpdate(d);
+    }
+    if (!await d.quiesceDirect()) {
+        state = { ...state, last_result: 'skipped', skipped_reason: 'busy' };
+        return;
+    }
+    try {
+        await runUpdate(d);
+    }
+    finally {
+        d.releaseDirect?.();
+    }
+}
+async function runUpdate(d) {
     const skip = shouldRun({ enabled: d.enabled(), busy: d.isBusy(), breakerOpen: d.breakerOpen() });
     if (skip) {
         state = { ...state, last_checked_at: new Date().toISOString(), last_result: 'skipped', skipped_reason: skip };

package/dist/capabilities.d.ts

@@ -1,4 +1,7 @@
+import { entityboxFileCapabilities } from './entitybox-file-session';
 import type { EngineInfo } from './desktop/provider';
+import { type ClaudeModelEntry } from './claude-models';
+import { type CodexModelEntry } from './codex-models';
 import { type AutostartState } from './autostart';
 import { type AutoUpdateState } from './auto-update';
 import { type MachineSample } from './machine-metrics';
@@ -38,16 +41,15 @@ interface FlowsCapability {
     max_concurrent: number;
 }
 interface CapabilitiesShape {
+    entitybox?: {
+        files: NonNullable<ReturnType<typeof entityboxFileCapabilities>>;
+    };
     /** Version of @addai/node running. Lets the studio / CodeFlows
      *  UIs show "outdated daemon" hints and helps us debug field issues
      *  ("which version was this row produced by?"). */
     daemon_version?: string;
-    claude: BinaryProbe & {
-        models?: string[];
-    };
-    codex: BinaryProbe & {
-        models?: string[];
-    };
+    claude: BinaryProbe & ClaudeModelFields;
+    codex: BinaryProbe & CodexModelFields;
     kimi: BinaryProbe & {
         models?: string[];
     };
@@ -80,6 +82,29 @@ interface CapabilitiesShape {
      *  version silently changes with no explanation. */
     auto_update?: AutoUpdateState;
 }
+/** What the heartbeat says about claude's models. `models` keeps its old
+ *  shape — plain ids — because Studio and Flows read it as strings; the
+ *  newer fields sit beside it and older readers simply never look. */
+interface ClaudeModelFields {
+    models?: string[];
+    /** The CLI's own entries with their names ('Opus 5.5') and alias flags.
+     *  Built-in extras in `models` have none, and are shown by id. */
+    model_catalog?: ClaudeModelEntry[];
+    /** 'cli' when the list came from the CLI, 'builtin' when it is the
+     *  fallback above — so a stale picker can be told apart from a live one. */
+    models_source?: 'cli' | 'builtin';
+}
+interface CodexModelFields {
+    /** Asked of codex's app-server (codex-models.ts); empty until it answers.
+     *  There is no built-in list: a blank model — codex's own default — is the
+     *  one choice that always runs. */
+    models?: string[];
+    model_catalog?: CodexModelEntry[];
+    models_source?: 'cli' | 'builtin';
+    /** 'account' when the list is what this node's login can run, 'bundled'
+     *  when the login was left alone and it is what the CLI ships with. */
+    models_scope?: 'account' | 'bundled';
+}
 /** Codex's credential store: $CODEX_HOME (or ~/.codex) + /auth.json. */
 export declare function codexHome(): string;
 /**

package/dist/capabilities.js

@@ -42,11 +42,14 @@ exports.codexHome = codexHome;
 exports.codexAuthFromStore = codexAuthFromStore;
 exports.probeCapabilities = probeCapabilities;
 const engine_1 = require("./desktop/engine");
+const entitybox_file_session_1 = require("./entitybox-file-session");
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const claude_binary_1 = require("./claude-binary");
+const claude_models_1 = require("./claude-models");
+const codex_models_1 = require("./codex-models");
 const kimi_binary_1 = require("./kimi-binary");
 const gemini_binary_1 = require("./gemini-binary");
 const grok_binary_1 = require("./grok-binary");
@@ -92,25 +95,21 @@ function runCmd(cmd, args, timeoutMs = 5000) {
         }
     });
 }
-// Curated model lists baked into the daemon. The CLIs still expose no
-// non-interactive "list models" command, so this stays a constant — but
-// WHAT goes in it is what decides whether the UI's dropdown rots.
+// Curated model lists baked into the daemon.
 //
-// Do not "fix" this by probing the CLI. Checked against Claude Code
-// 2.1.266: there is no `claude models` subcommand and no `claude config
-// list`. Both strings are read as a PROMPT — the CLI starts a billed
-// session and answers in prose. Probing that on every heartbeat would
-// spend money several times a minute and still return nothing parseable.
+// Claude's is now the FLOOR, not the source: the CLI itself is asked which
+// models it offers (claude-models.ts, over the SDK control protocol), so a new
+// Claude model reaches the pickers when a node's CLI updates, not when someone
+// edits this file. This list is what a node reports until that answer arrives
+// or when its CLI cannot give one — and its older pinned ids are kept beside
+// the CLI's answer, which (asked without a login) lists only the aliases.
 //
-// `claude --help` documents the real contract instead: --model takes
-// "an alias for the latest model (e.g. 'fable', 'opus', or 'sonnet') or
-// a model's full name (e.g. 'claude-fable-5')".
+// Do not "fix" the fallback by running `claude models` or `claude config
+// list`. Neither exists (checked to 2.1.304): both strings are read as a
+// PROMPT — the CLI starts a billed session and answers in prose.
 //
-// So the ALIASES lead the list. They are the only entries that cannot go
-// stale — the CLI resolves each to whatever is current in its tier — and
-// staleness is exactly what went wrong before: this list was still
-// offering claude-opus-4-1 and claude-sonnet-4-5 long after they were
-// superseded, and no amount of heartbeating fixes a wrong constant.
+// The ALIASES lead the list. They are the only entries that cannot go
+// stale — the CLI resolves each to whatever is current in its tier.
 // Pinned ids follow, newest first, for anyone who must hold one model.
 //
 // Availability is plan-gated (these nodes sign in with claude.ai
@@ -124,20 +123,17 @@ const CLAUDE_MODELS = [
     'haiku',
     'fable',
     // Pinned ids, newest first.
+    'claude-opus-5-5',
+    'claude-sonnet-5-5',
+    'claude-haiku-5-5',
+    'claude-fable-5-1',
     'claude-opus-5',
     'claude-sonnet-5',
-    'claude-fable-5-1',
     'claude-opus-4-8',
     'claude-opus-4-7',
     'claude-sonnet-4-6',
     'claude-haiku-4-5',
 ];
-const CODEX_MODELS = [
-    'gpt-5',
-    'gpt-5-mini',
-    'o4',
-    'o4-mini',
-];
 const KIMI_MODELS = [
     'kimi-k2-instruct',
     'kimi-k2-base',
@@ -178,7 +174,19 @@ async function probeClaude() {
         }
         catch { /* fall through unauthed */ }
     }
-    return { available: true, version, models: CLAUDE_MODELS, ...authShape };
+    // Asked once per binary and version — the probe never sees the login, so
+    // an account change cannot move its answer. Never waits; see
+    // claude-models.ts. No default model is reported: a CLI asked without a
+    // login cannot say what this node's account defaults to.
+    const live = (0, claude_models_1.claudeModelsFor)(bin, `${bin}|${version ?? ''}`);
+    return {
+        available: true,
+        version,
+        models: live ? (0, claude_models_1.withBuiltin)(live, CLAUDE_MODELS).models : CLAUDE_MODELS,
+        ...(live ? { model_catalog: live.catalog } : {}),
+        models_source: live ? 'cli' : 'builtin',
+        ...authShape,
+    };
 }
 /** Codex's credential store: $CODEX_HOME (or ~/.codex) + /auth.json. */
 function codexHome() {
@@ -245,7 +253,18 @@ async function probeCodex() {
     else {
         authShape = codexAuthFromStore(codexHome());
     }
-    return { available: true, version: ver.stdout, models: CODEX_MODELS, ...authShape };
+    // Asked once per binary and version, in the background; see codex-models.ts.
+    // Its efforts replace the registry's when it answers — they are per model,
+    // and newer codex takes xhigh and max.
+    const live = (0, codex_models_1.codexModelsFor)(bin, `${bin}|${ver.stdout}`);
+    return {
+        available: true,
+        version: ver.stdout,
+        models: live?.models ?? [],
+        ...(live ? { model_catalog: live.catalog, models_scope: live.scope, efforts: (0, codex_models_1.offeredEfforts)(live) } : {}),
+        models_source: live ? 'cli' : 'builtin',
+        ...authShape,
+    };
 }
 async function probeKimi() {
     const bin = (0, kimi_binary_1.findKimiBinary)();
@@ -475,7 +494,8 @@ async function probeCapabilities() {
     // login strategy) so Studio and the TUI render from one source of truth.
     const deco = (id, probe) => ({
         ...probe,
-        efforts: harness_registry_1.HARNESSES[id].efforts,
+        // A list the CLI gave itself (codex) beats the registry's.
+        efforts: probe.efforts?.length ? probe.efforts : harness_registry_1.HARNESSES[id].efforts,
         installable: (0, harness_registry_1.isInstallable)(id),
         login_strategy: harness_registry_1.HARNESSES[id].login.strategy,
         login_methods: [
@@ -483,7 +503,9 @@ async function probeCapabilities() {
             ...(harness_registry_1.HARNESSES[id].extraLogins ?? []).map(m => m.method),
         ],
     });
+    const fileCapability = (0, entitybox_file_session_1.entityboxFileCapabilities)(claude);
     return {
+        ...(fileCapability ? { entitybox: { files: fileCapability } } : {}),
         daemon_version: readDaemonVersion(),
         autostart: (0, autostart_1.status)(),
         container_engine: containerEngine,

package/dist/claude-models.d.ts

@@ -0,0 +1,71 @@
+import { type ModelProbeResult } from './model-cache';
+import { type CliInvocation } from './win';
+export interface ClaudeModelEntry {
+    /** What goes to `--model`: an alias ('opus') or a full id. */
+    id: string;
+    /** What the CLI runs for it today — the same as `id` for a full id. */
+    resolved: string;
+    /** The CLI's own label, e.g. 'Opus 5.5'. */
+    name: string;
+    /** An alias names a tier, not a version, and moves when the CLI updates. */
+    alias: boolean;
+    /** Effort levels this model takes, when the CLI says. */
+    efforts?: string[];
+}
+export interface ClaudeModelReport {
+    /** Plain ids, aliases first — the shape `capabilities.claude.models` has
+     *  always had. Studio and Flows read it as strings; keep it that way. */
+    models: string[];
+    /** The same models with names, for the UIs that know this field. */
+    catalog: ClaudeModelEntry[];
+    /** What a run with no model set gets — for a logged-OUT CLI, which is all
+     *  the probe ever sees, so it is not reported as this node's default. */
+    defaultModel?: string;
+}
+export type ProbeResult = ModelProbeResult<ClaudeModelReport>;
+/**
+ * Turn the `models` array of an initialize response into a report.
+ *
+ * Every alias also gets a pinned entry for what it resolves to. The CLI lists
+ * `opus` → claude-opus-5-5 but no `claude-opus-5-5` of its own, and without one
+ * nobody could hold an entity on Opus 5.5 once `opus` moves on.
+ *
+ * `default` is left out of `models`: a blank model already means the default,
+ * and nobody has tested what `--model default` does.
+ *
+ * Returns null when nothing usable is in there.
+ */
+export declare function parseInitializeModels(raw: unknown): ClaudeModelReport | null;
+/**
+ * What the heartbeat reports: the CLI's models first, then any built-in id it
+ * did not mention. A logged-out CLI lists only its aliases, and dropping the
+ * older pinned ids (Opus 4.8, Sonnet 4.6, …) from every picker would take
+ * options away from people who use them. The built-in extras carry no catalog
+ * entry — a UI shows them by id, exactly as it always has.
+ */
+export declare function withBuiltin(report: ClaudeModelReport, builtin: readonly string[]): ClaudeModelReport;
+/**
+ * Ask one Claude binary for its models. Never throws; resolves within
+ * `timeoutMs` however the CLI behaves, and leaves no process behind.
+ */
+export declare function probeClaudeModels(bin: string, opts?: {
+    timeoutMs?: number;
+    /** Tests only: run something else in place of the CLI. */
+    resolve?: (bin: string, args: string[]) => CliInvocation;
+    /** Tests only: where the throwaway folder goes. */
+    dir?: string;
+}): Promise<ProbeResult>;
+/** Tests only. */
+export declare function __resetIsolationForTests(): void;
+export interface ModelCacheDeps {
+    probe: (bin: string) => Promise<ProbeResult>;
+    now: () => number;
+    log: (line: string) => void;
+}
+/** Refreshed every 6h, retried 30 min after a failure — see model-cache.ts. */
+export declare function createClaudeModelCache(deps: ModelCacheDeps): {
+    get(bin: string, key: string): ClaudeModelReport | null;
+    last(): ClaudeModelReport | null;
+};
+/** What capabilities.ts reports for claude's models. */
+export declare function claudeModelsFor(bin: string, key: string): ClaudeModelReport | null;

package/dist/claude-models.js

@@ -0,0 +1,330 @@
+"use strict";
+// Which models the installed Claude Code offers — asked of the CLI itself.
+//
+// Until 0.30.13 this was only the CLAUDE_MODELS constant in capabilities.ts,
+// and a constant is only as current as the last release: Opus 5.5 shipped and
+// every node went on offering Opus 5, because nobody had edited the list.
+//
+// The CLI has no `claude models` command (still true in 2.1.304, and anything
+// it does not recognise is read as a PROMPT, which is billed). But it does
+// answer the SDK control protocol: start it in stream-json mode, send the
+// `initialize` control request, and the response carries `models` — the list
+// its own /model picker shows, with what each alias resolves to today. No user
+// message is ever sent, so nothing is billed.
+//
+// ⚠️ THE PROBE MUST NEVER SEE THE NODE'S LOGIN. A Claude process that starts
+// with an expired access token refreshes it, which rotates the refresh token;
+// one that exits a second later — as a probe does — can lose the rotated token,
+// and the next process finds a dead login and wipes it. That logged popadom's
+// Claude out on 2026-10-20 while this was being built. So the probe runs with
+// a throwaway CLAUDE_CONFIG_DIR, `--bare` (no keychain reads — the macOS
+// login lives there, not in the config dir), and no credential env vars. The
+// CLI then reports `tokenSource: "none"` and still answers, with the
+// account-independent list: the aliases and what they resolve to.
+//
+//   2.1.278  `opus[1m]` → claude-opus-5[1m], `sonnet` → claude-sonnet-5
+//   2.1.304  `opus` → claude-opus-5-5, `sonnet` → claude-sonnet-5-5
+//
+// If a CLI ever answers WITH a login despite all that, isolation has failed:
+// this process stops probing for good and says so in the log.
+//
+// A probe costs a CLI start (~1s) and the heartbeat runs every 30s, so the
+// answer is cached per (binary, version) and the heartbeat never waits for it:
+// the first beat after an install or upgrade still reports what it had, kicks
+// the probe off in the background, and the next beat carries the answer. A
+// probe that fails — an old CLI, a protocol change — leaves the built-in list
+// in place (or the last answer that same binary gave) and is not retried for
+// RETRY_AFTER_FAIL_MS, so a broken CLI never costs a spawn every 30 seconds.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseInitializeModels = parseInitializeModels;
+exports.withBuiltin = withBuiltin;
+exports.probeClaudeModels = probeClaudeModels;
+exports.__resetIsolationForTests = __resetIsolationForTests;
+exports.createClaudeModelCache = createClaudeModelCache;
+exports.claudeModelsFor = claudeModelsFor;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const model_cache_1 = require("./model-cache");
+const win_1 = require("./win");
+// What a model id may look like before it is passed on: `claude-opus-5-5`,
+// `opus[1m]`, `claude-haiku-4-5-20251001`. Anything else is dropped rather
+// than shipped to every picker.
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:[\]-]{0,119}$/;
+const MAX_ENTRIES = 64;
+/** An alias carries no version number: `opus`, `sonnet`, `opus[1m]`. */
+function isAlias(id) {
+    return !/\d/.test(id.replace(/\[[^\]]*\]$/, ''));
+}
+/**
+ * Turn the `models` array of an initialize response into a report.
+ *
+ * Every alias also gets a pinned entry for what it resolves to. The CLI lists
+ * `opus` → claude-opus-5-5 but no `claude-opus-5-5` of its own, and without one
+ * nobody could hold an entity on Opus 5.5 once `opus` moves on.
+ *
+ * `default` is left out of `models`: a blank model already means the default,
+ * and nobody has tested what `--model default` does.
+ *
+ * Returns null when nothing usable is in there.
+ */
+function parseInitializeModels(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    const aliases = [];
+    const pinned = [];
+    const derived = [];
+    let defaultModel;
+    for (const item of raw.slice(0, MAX_ENTRIES)) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const o = item;
+        const id = typeof o.value === 'string' ? o.value.trim() : '';
+        if (!SAFE_ID.test(id))
+            continue;
+        const resolved = typeof o.resolvedModel === 'string' && SAFE_ID.test(o.resolvedModel.trim())
+            ? o.resolvedModel.trim() : id;
+        const name = typeof o.displayName === 'string' && o.displayName.trim()
+            ? o.displayName.trim().slice(0, 80) : id;
+        const efforts = Array.isArray(o.supportedEffortLevels)
+            ? o.supportedEffortLevels.filter((e) => typeof e === 'string' && /^[a-z]{1,20}$/.test(e))
+            : [];
+        if (id === 'default') {
+            if (resolved !== 'default')
+                defaultModel = resolved;
+            continue;
+        }
+        const entry = { id, resolved, name, alias: isAlias(id), ...(efforts.length ? { efforts } : {}) };
+        (entry.alias ? aliases : pinned).push(entry);
+        if (entry.alias && resolved !== id) {
+            derived.push({ id: resolved, resolved, name, alias: false, ...(efforts.length ? { efforts } : {}) });
+        }
+    }
+    // Aliases first (they never go stale), then what they point at (the newest
+    // models), then the CLI's own pinned list in its order.
+    const seen = new Set();
+    const catalog = [];
+    for (const e of [...aliases, ...derived, ...pinned]) {
+        if (seen.has(e.id))
+            continue;
+        seen.add(e.id);
+        catalog.push(e);
+    }
+    if (catalog.length === 0)
+        return null;
+    return { models: catalog.map(e => e.id), catalog, ...(defaultModel ? { defaultModel } : {}) };
+}
+/**
+ * What the heartbeat reports: the CLI's models first, then any built-in id it
+ * did not mention. A logged-out CLI lists only its aliases, and dropping the
+ * older pinned ids (Opus 4.8, Sonnet 4.6, …) from every picker would take
+ * options away from people who use them. The built-in extras carry no catalog
+ * entry — a UI shows them by id, exactly as it always has.
+ */
+function withBuiltin(report, builtin) {
+    const have = new Set(report.models);
+    return { ...report, models: [...report.models, ...builtin.filter(id => !have.has(id))] };
+}
+/** Never read a login: the CLI must not see, refresh or clear one. */
+const CREDENTIAL_ENV = [
+    'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN',
+    'CLAUDE_CODE_OAUTH_REFRESH_TOKEN', 'CLAUDE_CONFIG_DIR',
+];
+const PROBE_ARGS = [
+    '--print', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+    // No keychain reads (the macOS login), no hooks, no plugin sync, no
+    // background prefetches. A CLI too old to know --bare refuses to start,
+    // and that node keeps the built-in list — the safe way to be wrong.
+    '--bare',
+    // No MCP servers: the handshake needs none.
+    '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}',
+];
+const MAX_LINE = 2 * 1024 * 1024;
+/** Set once a CLI answers with a login despite the isolation above. */
+let isolationBroken = false;
+/**
+ * Ask one Claude binary for its models. Never throws; resolves within
+ * `timeoutMs` however the CLI behaves, and leaves no process behind.
+ */
+function probeClaudeModels(bin, opts = {}) {
+    return new Promise(done => {
+        if (isolationBroken) {
+            done({ ok: false, reason: 'probing is off: a CLI saw a login despite the isolation' });
+            return;
+        }
+        let settled = false;
+        let inv;
+        try {
+            inv = (opts.resolve ?? win_1.resolveCliInvocation)(bin, PROBE_ARGS);
+        }
+        catch (err) {
+            done({ ok: false, reason: err.message || String(err) });
+            return;
+        }
+        // Both the probe's cwd and its CLAUDE_CONFIG_DIR, so no project's
+        // settings or CLAUDE.md are read and nothing the CLI writes lands in the
+        // real ~/.claude.
+        const dir = opts.dir ?? (0, model_cache_1.makeProbeDir)();
+        if (!dir) {
+            done({ ok: false, reason: 'no folder to probe from' });
+            return;
+        }
+        const cleanup = () => {
+            if (opts.dir)
+                return;
+            try {
+                fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+            }
+            catch { /* swept later */ }
+        };
+        const env = { ...process.env, TERM: 'dumb' };
+        for (const k of CREDENTIAL_ENV)
+            delete env[k];
+        env.CLAUDE_CONFIG_DIR = dir;
+        // A probe is read-only: it must never start a self-update of the CLI.
+        env.DISABLE_AUTOUPDATER = '1';
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(inv.file, inv.args, { cwd: dir, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        }
+        catch (err) {
+            cleanup();
+            done({ ok: false, reason: err.message || String(err) });
+            return;
+        }
+        child.once('close', cleanup);
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // EOF first — in stream-json mode the CLI exits on its own when its
+            // input ends. The kill is the backstop for one that does not.
+            try {
+                child.stdin?.end();
+            }
+            catch { /* already closed */ }
+            const reap = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    (0, win_1.killProcessTree)(child);
+            }, 3000);
+            reap.unref();
+            child.once('exit', () => clearTimeout(reap));
+            done(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ ok: false, reason: `no answer within ${opts.timeoutMs ?? 30000}ms` });
+            (0, win_1.killProcessTree)(child);
+        }, opts.timeoutMs ?? 30000);
+        timer.unref();
+        child.on('error', err => finish({ ok: false, reason: err.message || String(err) }));
+        // 'close', not 'exit': close waits for stdout to drain, so an answer the
+        // CLI wrote just before exiting is read rather than reported missing.
+        child.on('close', (code, signal) => {
+            finish({ ok: false, reason: `exited ${code ?? signal} before answering${stderr ? `: ${stderr.trim().slice(0, 200)}` : ''}` });
+        });
+        child.stdin?.on('error', () => { });
+        let stderr = '';
+        child.stderr?.on('data', (d) => { if (stderr.length < 4096)
+            stderr += d.toString('utf8'); });
+        const requestId = `models-${process.pid}-${Date.now()}`;
+        let buf = '';
+        child.stdout?.on('data', (d) => {
+            buf += d.toString('utf8');
+            if (buf.length > MAX_LINE) {
+                finish({ ok: false, reason: 'oversized output' });
+                return;
+            }
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line.startsWith('{'))
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.type !== 'control_response')
+                    continue;
+                const res = msg.response ?? {};
+                if (res.request_id && res.request_id !== requestId)
+                    continue;
+                if (res.subtype === 'error') {
+                    finish({ ok: false, reason: `initialize refused: ${String(res.error ?? 'unknown').slice(0, 200)}` });
+                    return;
+                }
+                const tokenSource = res.response?.account?.tokenSource;
+                if (typeof tokenSource === 'string' && tokenSource !== 'none') {
+                    isolationBroken = true;
+                    finish({ ok: false, reason: `isolation failed — the CLI saw a login (${tokenSource}); probing is now off on this node` });
+                    return;
+                }
+                const report = parseInitializeModels(res.response?.models);
+                finish(report ? { ok: true, report } : { ok: false, reason: 'initialize answered without a model list' });
+                return;
+            }
+        });
+        try {
+            child.stdin?.write(JSON.stringify({
+                type: 'control_request', request_id: requestId, request: { subtype: 'initialize' },
+            }) + '\n');
+        }
+        catch { /* reported via 'close' / 'error' */ }
+    });
+}
+/** Tests only. */
+function __resetIsolationForTests() { isolationBroken = false; }
+/** Refreshed every 6h, retried 30 min after a failure — see model-cache.ts. */
+function createClaudeModelCache(deps) {
+    return (0, model_cache_1.createModelCache)({
+        ...deps,
+        agent: 'claude',
+        describe: report => report.catalog.filter(e => e.alias && e.resolved !== e.id)
+            .map(e => `${e.id} → ${e.resolved}`).join(', '),
+    });
+}
+const sharedCache = createClaudeModelCache({
+    probe: bin => probeClaudeModels(bin),
+    now: () => Date.now(),
+    log: line => console.log(line),
+});
+/** What capabilities.ts reports for claude's models. */
+function claudeModelsFor(bin, key) {
+    return sharedCache.get(bin, key);
+}

package/dist/claude-print.d.ts

@@ -2,6 +2,8 @@ import type { RuntimeEvent, RuntimePermissionMode, RuntimeEffortLevel } from './
 export interface ClaudePrintInput {
     workingDirectory: string;
     prompt: string;
+    /** Verified original file blocks for explicitly marked EntityBox chat. */
+    inputBlocks?: readonly ClaudePrintInputBlock[];
     permissionMode?: RuntimePermissionMode;
     effortLevel?: RuntimeEffortLevel;
     model?: string;
@@ -13,6 +15,19 @@ export interface ClaudePrintInput {
     /** Restrict to a specific set of tools (claude only). null/undefined = inherit. */
     allowedTools?: string[];
 }
+export type ClaudePrintInputBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image' | 'document';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+/** Stream JSON reaches stdin only; files never become command-line arguments. */
+export declare function claudePrintInputMessage(prompt: string, blocks: readonly ClaudePrintInputBlock[]): string;
 /**
  * The text to emit for one flushed block, given what came before.
  *