@celestea/runtime 2.7.1

package/dist/pricing.js

@@ -0,0 +1,167 @@
+/**
+ * Pricing snapshot for the usage ledger (iteration E §3.2.2, W728 P0).
+ *
+ * The engine converts tokens into money with EXACTLY one rule:
+ * `tokens / 1e6 × unit price`. It deliberately does NOT re-implement the
+ * platform's billing (group multipliers, expressions, cache discounts):
+ * `newapi` owns the price of record (LTS `biz/newapi.md` I1–I3), so a snapshot
+ * here is an engine-side ESTIMATE, never a second source of truth (§3.5 R3-2).
+ *
+ * `pricing.json` is operator/ops supplied (§3.5 R3-1: P0 does not depend on the
+ * newapi sync script). A model absent from the table is NOT priced as 0:
+ * [priceFor] returns null and the caller must mark the record `unpriced`.
+ * A missing or unreadable file is an empty table (every model unpriced) — it is
+ * reported on stderr and never throws, because a pricing problem must not break
+ * a turn.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** `<data dir>/pricing.json` (§3.2.2). */
+export const PRICING_FILE = "pricing.json";
+/** Path override (`CELESTEA_PRICING_FILE`). */
+export const ENV_PRICING_FILE = "CELESTEA_PRICING_FILE";
+/** The only unit the ledger understands (per million tokens). */
+export const PRICING_UNIT = "per_mtok";
+/** A table with no models: every lookup is `unpriced` (never 0). */
+export function emptyPricing(path = null) {
+    return { version: "none", currency: "CNY", unit: PRICING_UNIT, models: {}, effective_from: null, path };
+}
+/** `<data dir>/pricing.json`, overridable with `CELESTEA_PRICING_FILE`. */
+export function pricingPath(dataDir, env = process.env) {
+    const override = env[ENV_PRICING_FILE];
+    return override === undefined || override.trim() === "" ? join(dataDir, PRICING_FILE) : override;
+}
+/** Price of `model`, or null when the snapshot does not cover it. */
+export function priceFor(table, model) {
+    if (model === null)
+        return null;
+    const price = table.models[model];
+    return price === undefined ? null : price;
+}
+/**
+ * `uncached_in × in + completion × out + cache_read × cache_read`, rounded
+ * to 6 decimals.
+ *
+ * The provider's `prompt_tokens` ALREADY CONTAINS the cache-hit region (host
+ * turn-usage: `total - output === input + cacheRead + cacheWrite`; the LLM seam
+ * reads `prompt_tokens` as that total and the cache counters separately), so
+ * the hit region must be billed ONCE, at the cache price:
+ * `billableIn = max(0, prompt_tokens - cache_read)` is the input the provider
+ * did NOT serve from cache. Charging the whole prompt at the input price AND
+ * the cache counter on top would bill the hit region twice; that reading was
+ * rejected by the product, so this function never does it.
+ *
+ * `max(0, ...)` guards anomalous data (`cache_read > prompt_tokens`, which the
+ * provider should never report): the input component floors at 0 instead of
+ * going negative. The cache component still charges what was reported.
+ */
+export function costOf(usage, price) {
+    const billableIn = Math.max(0, usage.prompt_tokens - usage.cache_read);
+    const inCost = round6((billableIn / 1e6) * price.in);
+    const outCost = round6((usage.completion_tokens / 1e6) * price.out);
+    const cacheCost = round6((usage.cache_read / 1e6) * price.cache_read);
+    return { in: inCost, out: outCost, cache: cacheCost, total: round6(inCost + outCost + cacheCost) };
+}
+/** Sum of two costs, component-wise (so the total cannot drift from the parts). */
+export function costAdd(a, b) {
+    const inCost = round6(a.in + b.in);
+    const outCost = round6(a.out + b.out);
+    const cacheCost = round6(a.cache + b.cache);
+    return { in: inCost, out: outCost, cache: cacheCost, total: round6(inCost + outCost + cacheCost) };
+}
+/** `price` field of a priced ledger row. */
+export function priceSnapshot(table, price) {
+    return {
+        version: table.version,
+        currency: table.currency,
+        unit: table.unit,
+        in: price.in,
+        out: price.out,
+        cache_read: price.cache_read,
+    };
+}
+/** Parse a pricing.json document; null = malformed (caller falls back to empty). */
+export function parsePricing(input, path = null) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const rec = input;
+    const models = parseModels(rec["models"]);
+    if (models === null)
+        return null;
+    const effective = rec["effective_from"];
+    return {
+        version: text(rec["version"]) ?? "unknown",
+        currency: text(rec["currency"]) ?? "CNY",
+        unit: PRICING_UNIT,
+        models,
+        effective_from: typeof effective === "number" && Number.isFinite(effective) ? effective : null,
+        path,
+    };
+}
+/**
+ * Read the snapshot. A missing file is an empty table (everything unpriced). A
+ * file that exists but does not parse is ALSO an empty table, reported on
+ * stderr: pricing half the fleet by a half-read table would under-report cost
+ * silently (G3-7).
+ */
+export function loadPricingFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return emptyPricing(path);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        warn(`pricing file ${path} is not valid JSON (${errorText(e)}) — every model is unpriced`);
+        return emptyPricing(path);
+    }
+    const table = parsePricing(parsed, path);
+    if (table === null) {
+        warn(`pricing file ${path} has no usable "models" map — every model is unpriced`);
+        return emptyPricing(path);
+    }
+    return table;
+}
+/** The `models` map, or null when the document has no usable shape at all. */
+function parseModels(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const out = {};
+    for (const [model, value] of Object.entries(input)) {
+        const price = parsePrice(value);
+        if (price !== null)
+            out[model] = price;
+    }
+    return out;
+}
+/** One table row; `in`/`out` are required, `cache_read` defaults to 0. */
+function parsePrice(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const rec = value;
+    const inCost = asPrice(rec["in"]);
+    const outCost = asPrice(rec["out"]);
+    if (inCost === null || outCost === null)
+        return null;
+    return { in: inCost, out: outCost, cache_read: asPrice(rec["cache_read"]) ?? 0 };
+}
+function asPrice(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+}
+function text(v) {
+    return typeof v === "string" && v !== "" ? v : null;
+}
+function round6(v) {
+    return Math.round(v * 1e6) / 1e6;
+}
+function warn(message) {
+    process.stderr.write(`usage ledger: ${message}\n`);
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/profile.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runtime compose seam (P3 placeholder).
+ *
+ * P0 freezes the profile key set (12 keys) and the three key-resolution paths
+ * so P3 cannot invent new ones.
+ */
+export interface Profile {
+    model: string;
+    base_url: string;
+    api_key_env: string;
+    api_key_file: string | null;
+    max_steps: number;
+    max_parallel_tool_calls: number;
+    reasoning_effort: string | null;
+    max_output_tokens: number | null;
+    context_window_tokens: number;
+    system_prompt: string;
+    request_format: "chat_completions" | "responses" | "anthropic_messages";
+    temperature: number | null;
+}
+export declare const PROFILE_KEYS: readonly ["model", "base_url", "api_key_env", "api_key_file", "max_steps", "max_parallel_tool_calls", "reasoning_effort", "max_output_tokens", "context_window_tokens", "system_prompt", "request_format", "temperature"];
+/** resolve_api_key order: env -> api_key_file -> ~/.celestea config. */
+export type KeySource = "env" | "api_key_file" | "home_config" | "provider_store" | "borrowed_engine_key" | "none";
+export declare const COMPOSE_STEPS: readonly ["load_dotenv", "load_workspaces_registry", "restore_active_session", "resolve_profile", "raise_max_steps", "load_providers", "apply_startup_default", "build_gen", "assemble_system_prompt", "runtime_compose", "build_app_state", "spawn_autowake", "register_routes", "serve", "shutdown"];
+export declare const DEFAULT_BIND = "127.0.0.1:3777";
+export declare const CONTEXT_WINDOW = 1000000;

package/dist/profile.js

@@ -0,0 +1,39 @@
+/**
+ * Runtime compose seam (P3 placeholder).
+ *
+ * P0 freezes the profile key set (12 keys) and the three key-resolution paths
+ * so P3 cannot invent new ones.
+ */
+export const PROFILE_KEYS = [
+    "model",
+    "base_url",
+    "api_key_env",
+    "api_key_file",
+    "max_steps",
+    "max_parallel_tool_calls",
+    "reasoning_effort",
+    "max_output_tokens",
+    "context_window_tokens",
+    "system_prompt",
+    "request_format",
+    "temperature",
+];
+export const COMPOSE_STEPS = [
+    "load_dotenv",
+    "load_workspaces_registry",
+    "restore_active_session",
+    "resolve_profile",
+    "raise_max_steps",
+    "load_providers",
+    "apply_startup_default",
+    "build_gen",
+    "assemble_system_prompt",
+    "runtime_compose",
+    "build_app_state",
+    "spawn_autowake",
+    "register_routes",
+    "serve",
+    "shutdown",
+];
+export const DEFAULT_BIND = "127.0.0.1:3777";
+export const CONTEXT_WINDOW = 1_000_000;

package/dist/recovery.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Boot recovery — "close the turn the previous process died inside" (§1.3 P0 ③).
+ *
+ * This is the ONLY caller of the §1.2.3 decision table that owns a session
+ * DIRECTORY: it checks that a log exists at all (a session that never ran must
+ * not gain an empty `cli-main.jsonl` because the host scanned it), opens the log
+ * through the persistent implementation — so a torn tail left by the crash is
+ * truncated exactly like it would be on the next turn — and then lets the pure
+ * decision function in `@celestea/session` do the (append-only) repair.
+ *
+ * Layering: runtime -> session is a downward edge (L2 -> L1) and already the
+ * package's own dependency; the DECISION itself stays in the session package
+ * because it is about the log + sidecar contract, not about assembly.
+ *
+ * The report is the observability channel of P0 (§5.2 ①): the host logs it, and
+ * the sidecar's `repaired[]` keeps the durable record. P0 adds no endpoint.
+ */
+import type { SessionLog } from "@celestea/core";
+import { type CheckpointIdentity, type CheckpointRead, type RecoveryAction } from "@celestea/session";
+import { SESSION_LOG_ID } from "./host/engine-session.js";
+/**
+ * The engine's log file name / id inside a session directory (contract).
+ *
+ * W747: single source — `host/engine-session.ts` owns the session log id/name
+ * (it opens the log); this module imports and re-exports it instead of keeping a
+ * second declaration of the same literal. Public name and value are unchanged.
+ */
+export { SESSION_LOG_ID };
+/** `<dir>/cli-main.jsonl` — the log this orchestrator may repair. */
+export declare function sessionLogPath(dir: string, sessionId?: string): string;
+export type BootRecoveryAction = RecoveryAction | "skipped_absent_log";
+export interface BootRecoveryOptions {
+    /** Session directory (`<workspace>/<session>`). */
+    dir: string;
+    /** Self-description of the sidecar (`<workspace>/<session>`). */
+    session: string;
+    identity?: CheckpointIdentity;
+    now?: () => number;
+    warn?: (message: string) => void;
+    /** Log opener override (tests); default = the persistent JSONL log. */
+    open?: (dir: string) => SessionLog;
+}
+export interface BootRecoveryReport {
+    session: string;
+    dir: string;
+    action: BootRecoveryAction;
+    turn_id: string | null;
+    /** True when exactly one `turn_end: interrupted` row was appended. */
+    appended: boolean;
+    dangling_before: string[];
+    dangling_after: string[];
+    checkpoint: CheckpointRead["kind"];
+    warnings: string[];
+}
+/** Recover ONE session directory. Never throws; nothing is created for a session that never ran. */
+export declare function recoverSessionOnBoot(opts: BootRecoveryOptions): BootRecoveryReport;

package/dist/recovery.js

@@ -0,0 +1,91 @@
+/**
+ * Boot recovery — "close the turn the previous process died inside" (§1.3 P0 ③).
+ *
+ * This is the ONLY caller of the §1.2.3 decision table that owns a session
+ * DIRECTORY: it checks that a log exists at all (a session that never ran must
+ * not gain an empty `cli-main.jsonl` because the host scanned it), opens the log
+ * through the persistent implementation — so a torn tail left by the crash is
+ * truncated exactly like it would be on the next turn — and then lets the pure
+ * decision function in `@celestea/session` do the (append-only) repair.
+ *
+ * Layering: runtime -> session is a downward edge (L2 -> L1) and already the
+ * package's own dependency; the DECISION itself stays in the session package
+ * because it is about the log + sidecar contract, not about assembly.
+ *
+ * The report is the observability channel of P0 (§5.2 ①): the host logs it, and
+ * the sidecar's `repaired[]` keeps the durable record. P0 adds no endpoint.
+ */
+import { existsSync } from "node:fs";
+import { CheckpointStore, checkpointPathFor, filePathFor, PersistentSessionLog, recoverOpenTurn, writeErrorCountOf, } from "@celestea/session";
+import { SESSION_LOG_ID } from "./host/engine-session.js";
+/**
+ * The engine's log file name / id inside a session directory (contract).
+ *
+ * W747: single source — `host/engine-session.ts` owns the session log id/name
+ * (it opens the log); this module imports and re-exports it instead of keeping a
+ * second declaration of the same literal. Public name and value are unchanged.
+ */
+export { SESSION_LOG_ID };
+/** `<dir>/cli-main.jsonl` — the log this orchestrator may repair. */
+export function sessionLogPath(dir, sessionId = SESSION_LOG_ID) {
+    return filePathFor(dir, sessionId);
+}
+/** Recover ONE session directory. Never throws; nothing is created for a session that never ran. */
+export function recoverSessionOnBoot(opts) {
+    const logPath = sessionLogPath(opts.dir);
+    const exists = existsSync(logPath);
+    const store = new CheckpointStore({
+        dir: opts.dir,
+        session: opts.session,
+        ...(opts.identity === undefined ? {} : { identity: opts.identity }),
+        ...(opts.now === undefined ? {} : { now: opts.now }),
+        ...(opts.warn === undefined ? {} : { warn: opts.warn }),
+    });
+    const checkpoint = store.load();
+    const base = { opts, checkpoint, before: [], after: [] };
+    if (!exists)
+        return report({ ...base, action: "skipped_absent_log", turnId: null, appended: false, warnings: store.warnings() });
+    const log = (opts.open ?? defaultOpen)(opts.dir);
+    try {
+        const outcome = recoverOpenTurn(log, store);
+        return report({
+            opts,
+            action: outcome.action,
+            turnId: outcome.turn_id,
+            appended: outcome.appended,
+            before: outcome.dangling_before,
+            after: outcome.dangling_after,
+            checkpoint: store.load(),
+            warnings: outcome.warnings,
+        });
+    }
+    finally {
+        closeLog(log);
+    }
+}
+function defaultOpen(dir) {
+    return PersistentSessionLog.open(dir, SESSION_LOG_ID);
+}
+function report(parts) {
+    const all = [...parts.warnings];
+    if (parts.checkpoint.kind === "invalid") {
+        all.push(`checkpoint invalid at ${checkpointPathFor(parts.opts.dir)}: ${parts.checkpoint.error}`);
+    }
+    return {
+        session: parts.opts.session,
+        dir: parts.opts.dir,
+        action: parts.action,
+        turn_id: parts.turnId,
+        appended: parts.appended,
+        dangling_before: parts.before,
+        dangling_after: parts.after,
+        checkpoint: parts.checkpoint.kind,
+        warnings: all,
+    };
+}
+/** Release the descriptor a persistent log owns (no-op for any other log). */
+function closeLog(log) {
+    const close = log?.close;
+    if (typeof close === "function")
+        close.call(log);
+}

package/dist/retention.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-side half of tool-result retention (W855): WHERE the spilled bytes go.
+ *
+ * The policy (thresholds, head/tail window, the "spill and replace" decision)
+ * lives in \@celestea/agent-loop (L1, core-only). This module owns the
+ * persistence: full text -> <session-dir>/spills/<call>-<n>.txt, a locator the
+ * model can read back, and a tool-shaped retrieval hint.
+ *
+ * Fail-soft by construction: no session dir, an unwritable dir or a write error
+ * all return null, and the loop then keeps the full result inline. A successful
+ * tool call is never turned into an error by a failed spill.
+ */
+import { type ToolResultRetention } from "@celestea/agent-loop";
+/** Single-result threshold override (bytes). */
+export declare const SINGLE_RESULT_ENV = "CELESTEA_TOOL_RESULT_MAX_BYTES";
+/** Per-step cumulative threshold override (bytes). */
+export declare const STEP_RESULT_ENV = "CELESTEA_STEP_TOOL_RESULT_MAX_BYTES";
+/** Inline head window override (bytes). */
+export declare const PREVIEW_HEAD_ENV = "CELESTEA_TOOL_RESULT_PREVIEW_HEAD_BYTES";
+/** Inline tail window override (bytes). */
+export declare const PREVIEW_TAIL_ENV = "CELESTEA_TOOL_RESULT_PREVIEW_TAIL_BYTES";
+/** Spill age override (ms); 0 disables the startup sweep entirely. */
+export declare const SPILL_TTL_ENV = "CELESTEA_SPILL_TTL_MS";
+/** Default spill age: `<session>/spills/*.txt` older than this are reaped at compose. */
+export declare const DEFAULT_SPILL_TTL_MS: number;
+export interface RetentionSettings {
+    /** Session directory; null = nothing can be spilled (retention is inert). */
+    dir: string | null;
+    singleResultBytes: number;
+    stepResultBytes: number;
+    previewHeadBytes: number;
+    previewTailBytes: number;
+    /** Age after which a spilled file is reaped at writer creation (0 = never). */
+    spillTtlMs: number;
+}
+/** Thresholds from the environment, with the built-in defaults. */
+export declare function retentionSettingsFromEnv(dir: string | null, env?: NodeJS.ProcessEnv): RetentionSettings;
+/**
+ * Reap spilled files older than `ttlMs` from `<dir>/spills` (W855 #8a).
+ *
+ * Policy: an AGE threshold, not "delete everything" — a fresh spill is the
+ * model's retrieval target and must survive a same-day recompose; only files a
+ * full TTL old are removed, so the directory cannot grow without bound across
+ * restarts. Synchronous and fail-soft: a missing/unreadable directory or one
+ * failed unlink never fails a compose. Returns the number of files removed.
+ */
+export declare function sweepSpills(dir: string | null, ttlMs: number, now?: number): number;
+/** Build the session-scoped spill writer. */
+export declare function createToolResultRetention(settings: RetentionSettings): ToolResultRetention;

package/dist/retention.js

@@ -0,0 +1,119 @@
+/**
+ * Host-side half of tool-result retention (W855): WHERE the spilled bytes go.
+ *
+ * The policy (thresholds, head/tail window, the "spill and replace" decision)
+ * lives in \@celestea/agent-loop (L1, core-only). This module owns the
+ * persistence: full text -> <session-dir>/spills/<call>-<n>.txt, a locator the
+ * model can read back, and a tool-shaped retrieval hint.
+ *
+ * Fail-soft by construction: no session dir, an unwritable dir or a write error
+ * all return null, and the loop then keeps the full result inline. A successful
+ * tool call is never turned into an error by a failed spill.
+ */
+import { readdirSync, statSync, unlinkSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_PREVIEW_HEAD_BYTES, DEFAULT_PREVIEW_TAIL_BYTES, DEFAULT_SINGLE_RESULT_BYTES, DEFAULT_STEP_RESULT_BYTES, } from "@celestea/agent-loop";
+/** Single-result threshold override (bytes). */
+export const SINGLE_RESULT_ENV = "CELESTEA_TOOL_RESULT_MAX_BYTES";
+/** Per-step cumulative threshold override (bytes). */
+export const STEP_RESULT_ENV = "CELESTEA_STEP_TOOL_RESULT_MAX_BYTES";
+/** Inline head window override (bytes). */
+export const PREVIEW_HEAD_ENV = "CELESTEA_TOOL_RESULT_PREVIEW_HEAD_BYTES";
+/** Inline tail window override (bytes). */
+export const PREVIEW_TAIL_ENV = "CELESTEA_TOOL_RESULT_PREVIEW_TAIL_BYTES";
+/** Spill age override (ms); 0 disables the startup sweep entirely. */
+export const SPILL_TTL_ENV = "CELESTEA_SPILL_TTL_MS";
+/** Default spill age: `<session>/spills/*.txt` older than this are reaped at compose. */
+export const DEFAULT_SPILL_TTL_MS = 7 * 24 * 60 * 60 * 1_000;
+/** Non-negative integer from the environment, else the frozen default. */
+function envBytes(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** Thresholds from the environment, with the built-in defaults. */
+export function retentionSettingsFromEnv(dir, env = process.env) {
+    return {
+        dir,
+        singleResultBytes: envBytes(env, SINGLE_RESULT_ENV, DEFAULT_SINGLE_RESULT_BYTES),
+        stepResultBytes: envBytes(env, STEP_RESULT_ENV, DEFAULT_STEP_RESULT_BYTES),
+        previewHeadBytes: envBytes(env, PREVIEW_HEAD_ENV, DEFAULT_PREVIEW_HEAD_BYTES),
+        previewTailBytes: envBytes(env, PREVIEW_TAIL_ENV, DEFAULT_PREVIEW_TAIL_BYTES),
+        spillTtlMs: envBytes(env, SPILL_TTL_ENV, DEFAULT_SPILL_TTL_MS),
+    };
+}
+/**
+ * Reap spilled files older than `ttlMs` from `<dir>/spills` (W855 #8a).
+ *
+ * Policy: an AGE threshold, not "delete everything" — a fresh spill is the
+ * model's retrieval target and must survive a same-day recompose; only files a
+ * full TTL old are removed, so the directory cannot grow without bound across
+ * restarts. Synchronous and fail-soft: a missing/unreadable directory or one
+ * failed unlink never fails a compose. Returns the number of files removed.
+ */
+export function sweepSpills(dir, ttlMs, now = Date.now()) {
+    if (dir === null || dir === "" || ttlMs <= 0)
+        return 0;
+    const spills = join(dir, "spills");
+    let names;
+    try {
+        names = readdirSync(spills);
+    }
+    catch {
+        return 0; // ENOENT (nothing spilled yet) or unreadable: nothing to do.
+    }
+    let removed = 0;
+    for (const name of names) {
+        if (!name.endsWith(".txt"))
+            continue;
+        const full = join(spills, name);
+        try {
+            if (now - statSync(full).mtimeMs > ttlMs) {
+                unlinkSync(full);
+                removed += 1;
+            }
+        }
+        catch {
+            // A file that vanished or cannot be stat'ed/unlinked is left alone.
+        }
+    }
+    return removed;
+}
+/** Build the session-scoped spill writer. */
+export function createToolResultRetention(settings) {
+    // W855 #8a: reap stale spills once per session generation (startup sweep).
+    sweepSpills(settings.dir, settings.spillTtlMs);
+    let seq = 0;
+    return {
+        singleResultBytes: settings.singleResultBytes,
+        stepResultBytes: settings.stepResultBytes,
+        previewHeadBytes: settings.previewHeadBytes,
+        previewTailBytes: settings.previewTailBytes,
+        async spill(text, meta) {
+            if (settings.dir === null || settings.dir === "")
+                return null;
+            try {
+                const dir = join(settings.dir, "spills");
+                await mkdir(dir, { recursive: true });
+                seq += 1;
+                const safe = meta.callId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 48) || "call";
+                const locator = join(dir, safe + "-" + String(seq) + ".txt");
+                await writeFile(locator, text, "utf8");
+                return {
+                    locator,
+                    bytes: Buffer.byteLength(text, "utf8"),
+                    retrievalHint: 'read_file path="' + locator + '"',
+                };
+            }
+            catch (e) {
+                // Best-effort: a failed spill must never fail the tool call. Record it
+                // and let the loop keep the full result inline.
+                process.stderr.write("[celestea-runtime] tool-result spill failed: " + (e instanceof Error ? e.message : String(e)) + "\n");
+                return null;
+            }
+        },
+    };
+}