@celestea/runtime 2.7.1

package/dist/runtime.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The composed runtime engine: one generation's services, wired and ready.
+ *
+ * A [Runtime] is deliberately thin — it owns the handles and the lifecycle and
+ * delegates turn driving to [TurnRunner]:
+ *
+ *   - **turn driving**  `runTurn(input, {signal, sink})`, single concurrency slot;
+ *   - **statusline**    `statusline()` reads the live tracker + usage accounting;
+ *   - **rebinding**     `rebind(binding)` re-opens the SAME session directory;
+ *   - **shutdown**      idempotent, re-entrant teardown (drivers, host process
+ *                       hooks, mailbox, registries): calling it twice is a
+ *                       no-op, and a concurrent caller awaits the same promise;
+ *   - **release**       explicit strong-reference drop for hot swaps (W248).
+ *
+ * `shutdown` also marks the session's checkpoint sidecar as cleanly closed
+ * (E §1.3 P0 ⑤), so the next boot can tell a graceful exit from a crash.
+ *
+ * [release] nulls every handle, which — together with the WeakRef the worker
+ * tools hold on the registry — breaks the
+ * `Runtime -> ctx -> ToolRegistry -> worker tool -> registry` cycle, so a
+ * swapped-out generation can actually be collected.
+ */
+import type { AgentConfig, Context, LlmRegistry, ModelRequest, SessionLog, Statusline, ToolRegistry, TurnOutcome } from "@celestea/core";
+import type { Watchdog, WorkerRegistry } from "@celestea/workers";
+import type { InjectionLane } from "@celestea/core";
+import type { InboxPushOptions, InjectedMessage, SessionInbox } from "./inbox.js";
+import { type SessionBinding } from "./session-binding.js";
+import { type AssembledContext, type StatusTracker, type StatusView } from "./status.js";
+import type { FrameSink, TurnOptions, TurnRunner } from "./turn-runner.js";
+import type { TurnFrame } from "./frames.js";
+import type { UsageAccounting } from "./usage.js";
+import type { Profile } from "./profile.js";
+import type { WorkerHost } from "./worker-wiring.js";
+export type ShutdownHook = () => void | Promise<void>;
+/** Everything compose hands over; the constructor never does IO of its own. */
+export interface RuntimeParts {
+    ctx: Context;
+    profile: Profile;
+    agentConfig: AgentConfig;
+    /** Mutable holder: a rebind swaps the log every reader observes. */
+    sessionRef: {
+        log: SessionLog;
+    };
+    binding: SessionBinding | null;
+    status: StatusTracker;
+    usage: UsageAccounting;
+    /** Per-session mid-turn injection queue (W513). */
+    inbox: SessionInbox;
+    runner: TurnRunner;
+    /** Worker wiring + the W740 watchdog mounted over it (null when off). */
+    workerHost: WorkerHost | null;
+    llm: LlmRegistry | null;
+    tools: ToolRegistry | null;
+    agentLoop: unknown | null;
+    /** Names of the mounted plugins, in mount order (order is semantics). */
+    plugins: readonly string[];
+    shutdownHooks: readonly ShutdownHook[];
+}
+export declare class Runtime {
+    private parts;
+    private binding;
+    private shutdownPromise;
+    private released;
+    /**
+     * W755 (Fix B): the context-usage projection state for THIS session (one
+     * generation = one session). Deliberately owned here rather than in
+     * `RuntimeParts` (compose passes no such thing) and never a module singleton:
+     * two live sessions must not share a prompt anchor. [rebind] re-opens the SAME
+     * session, so the anchor survives it exactly like the usage tracker's does.
+     */
+    private readonly pressure;
+    /**
+     * W762: the last assembly handed out, with the log state it was built from.
+     * One slot, per generation (never a module singleton, never a timer).
+     */
+    private snapshotCache;
+    constructor(parts: RuntimeParts);
+    private get p();
+    get ctx(): Context;
+    get profile(): Profile;
+    get agentConfig(): AgentConfig;
+    /** The active conversation log (a rebind swaps this handle). */
+    get session(): SessionLog;
+    get sessionBinding(): SessionBinding | null;
+    get status(): StatusTracker;
+    /** The session's injection queue (drained by the turn at step boundaries). */
+    get inbox(): SessionInbox;
+    get usage(): UsageAccounting;
+    get llm(): LlmRegistry | null;
+    get tools(): ToolRegistry | null;
+    get workers(): WorkerRegistry | null;
+    /**
+     * W740: the liveness watchdog mounted over this generation's worker registry
+     * (null when the watchdog is off). Adjudication itself belongs to the watchdog
+     * plugin — this is only the host's handle on it (`tick()` by hand, or read
+     * `running`), never a second liveness rule.
+     */
+    get watchdog(): Watchdog | null;
+    get hostSessionId(): string | null;
+    get isBusy(): boolean;
+    get isReleased(): boolean;
+    /** Mounted plugin names, in mount order. */
+    get pluginNames(): readonly string[];
+    /** Drive one turn; a second concurrent call is a [TurnBusyError] (409). */
+    runTurn(input: string | null, opts?: TurnOptions): Promise<TurnOutcome>;
+    /** Cancel the in-flight turn (cooperative); false when nothing was running. */
+    cancelTurn(): boolean;
+    /** Snapshot for the statusline reader (SSE status payloads / GET /api/status). */
+    statusView(): StatusView;
+    /** The frozen `/api/status` payload for this generation. */
+    statusline(): Statusline;
+    /**
+     * W725: this generation's model-visible context, exactly as the loop would
+     * build it for the NEXT step (system + trimmed history + tool schemas), or
+     * null when the mounted loop has no snapshot capability (a test double).
+     *
+     * The assembly is the agent loop's, never this layer's: runtime only forwards
+     * the Context, so the read-only snapshot cannot drift from the real request.
+     *
+     * W762: the result is memoized on the LOG STATE it was derived from, because
+     * the statusline reads it on every 2s tick and the context viewer on every
+     * refresh, while a session log only changes when the engine appends to it.
+     * The key is `(log identity, event count, last event reference)`, all three
+     * cheap to obtain, and it is COMPLETE within one generation: the profile /
+     * trim config is fixed at compose (a config change swaps the generation, not
+     * this object) and the tool surface is mounted at compose too, so
+     * `registry.schemas()` cannot drift under the cache. A rebind swaps the log,
+     * and the identity term catches it even when the new log has the same length.
+     *
+     * Consumers are read-only by construction (`contextViewOf` maps messages into
+     * fresh view rows; `estimatedContextTokens` only reads), so the cached object
+     * is shared rather than copied. A MISS costs one extra `events()` copy (the
+     * key) on top of the assembly: ~0.35ms at 50k events against an 18ms
+     * assembly. A HIT costs only that copy — ~2 orders of magnitude less.
+     */
+    contextSnapshot(): ModelRequest | null;
+    /**
+     * W766: the memoized assembly TOGETHER with its token estimate — what the
+     * statusline's `context_usage` fallback needs.
+     *
+     * W755 made the tick read the loop's own assembly; W762 memoized the assembly
+     * but left the ESTIMATE to be recomputed on every read, which dominated the
+     * tick (7.4ms of a 7.4ms tick at 50k events: an O(bytes) walk of the messages
+     * that could not have changed, because the request it walked was the very
+     * object the cache had just handed back). The estimate now rides in the same
+     * entry, so it is derived once per log state and dropped with the request.
+     *
+     * Lazy on purpose: the usage-frame path and the context viewer never read the
+     * estimate, so a MISS must not pay for it (same reason `tokens`/`assembled`
+     * start null rather than being filled by the assembly that built the request).
+     */
+    assembledContext(): AssembledContext | null;
+    /**
+     * The memoized snapshot entry for the log state right now, building (and
+     * caching) the assembly on a miss. This is the ONE cache the runtime keeps:
+     * the request, its estimate and its display wrapper all hang off it, so they
+     * can never disagree about which log state they describe.
+     */
+    private snapshotEntry;
+    /** Pending host receipts (worker -> host) that the next turn will inject. */
+    pendingReceipts(): number;
+    /**
+     * Deliver a message into THIS session's inbox on `lane` (W513/W515 §1):
+     * `next-turn` = drained at the next turn start (`placement: "queued"`),
+     * `next-step` = drained at the next step boundary of the RUNNING turn
+     * (`placement: "steering"`). The lane is the caller's decision — the host
+     * knows whether a turn is in flight, the runtime does not guess.
+     */
+    inject(text: string, lane?: InjectionLane, opts?: InboxPushOptions): InjectedMessage;
+    /** Messages queued on one lane, or on both (diagnostics / tests). */
+    pendingInjections(lane?: InjectionLane): number;
+    /**
+     * Rebind this generation to the SAME session (same directory, same id) by
+     * re-opening its log. Only between turns: mid-turn rebinding would let one
+     * turn write into two logs.
+     */
+    rebind(binding: SessionBinding): SessionLog;
+    /**
+     * Idempotent + re-entrant shutdown: stop drivers, run the host teardown hooks
+     * (process kills), purge mailboxes, clear registries. Repeating it is a no-op
+     * returning the first promise, so concurrent callers cannot double-run a hook.
+     */
+    shutdown(): Promise<void>;
+    private doShutdown;
+    /**
+     * Explicit strong-reference drop (the sync half of a hot swap): stop the
+     * runner, abort drivers, release the registry and null every handle. Call it
+     * after [shutdown] when the generation is discarded for good.
+     */
+    release(): void;
+    private assertLive;
+}
+/** Host-facing convenience: a sink that only collects frames (tests / CLI). */
+export declare function collectingSink(): {
+    frames: TurnFrame[];
+    sink: FrameSink;
+};

package/dist/runtime.js

@@ -0,0 +1,347 @@
+/**
+ * The composed runtime engine: one generation's services, wired and ready.
+ *
+ * A [Runtime] is deliberately thin — it owns the handles and the lifecycle and
+ * delegates turn driving to [TurnRunner]:
+ *
+ *   - **turn driving**  `runTurn(input, {signal, sink})`, single concurrency slot;
+ *   - **statusline**    `statusline()` reads the live tracker + usage accounting;
+ *   - **rebinding**     `rebind(binding)` re-opens the SAME session directory;
+ *   - **shutdown**      idempotent, re-entrant teardown (drivers, host process
+ *                       hooks, mailbox, registries): calling it twice is a
+ *                       no-op, and a concurrent caller awaits the same promise;
+ *   - **release**       explicit strong-reference drop for hot swaps (W248).
+ *
+ * `shutdown` also marks the session's checkpoint sidecar as cleanly closed
+ * (E §1.3 P0 ⑤), so the next boot can tell a graceful exit from a crash.
+ *
+ * [release] nulls every handle, which — together with the WeakRef the worker
+ * tools hold on the registry — breaks the
+ * `Runtime -> ctx -> ToolRegistry -> worker tool -> registry` cycle, so a
+ * swapped-out generation can actually be collected.
+ */
+import { EVENT_BUS_SERVICE, contextSnapshotOf, createEventBus } from "@celestea/core";
+import { markCleanShutdown } from "@celestea/session";
+import { closeLog } from "./host/engine-session.js";
+import { RuntimeReleasedError, TurnBusyError } from "./errors.js";
+import { bindSession } from "./session-binding.js";
+import { ContextPressure, estimatedContextTokens, statuslineOf, } from "./status.js";
+export class Runtime {
+    parts;
+    binding;
+    shutdownPromise = null;
+    released = false;
+    /**
+     * W755 (Fix B): the context-usage projection state for THIS session (one
+     * generation = one session). Deliberately owned here rather than in
+     * `RuntimeParts` (compose passes no such thing) and never a module singleton:
+     * two live sessions must not share a prompt anchor. [rebind] re-opens the SAME
+     * session, so the anchor survives it exactly like the usage tracker's does.
+     */
+    pressure = new ContextPressure();
+    /**
+     * W762: the last assembly handed out, with the log state it was built from.
+     * One slot, per generation (never a module singleton, never a timer).
+     */
+    snapshotCache = null;
+    constructor(parts) {
+        this.parts = parts;
+        this.binding = parts.binding;
+        if (!parts.ctx.has(EVENT_BUS_SERVICE))
+            parts.ctx.provide(EVENT_BUS_SERVICE, createEventBus());
+    }
+    get p() {
+        const parts = this.parts;
+        if (parts === null)
+            throw new RuntimeReleasedError();
+        return parts;
+    }
+    // --- handles -----------------------------------------------------------
+    get ctx() {
+        return this.p.ctx;
+    }
+    get profile() {
+        return this.p.profile;
+    }
+    get agentConfig() {
+        return this.p.agentConfig;
+    }
+    /** The active conversation log (a rebind swaps this handle). */
+    get session() {
+        return this.p.sessionRef.log;
+    }
+    get sessionBinding() {
+        return this.binding;
+    }
+    get status() {
+        return this.p.status;
+    }
+    /** The session's injection queue (drained by the turn at step boundaries). */
+    get inbox() {
+        return this.p.inbox;
+    }
+    get usage() {
+        return this.p.usage;
+    }
+    get llm() {
+        return this.p.llm;
+    }
+    get tools() {
+        return this.p.tools;
+    }
+    get workers() {
+        return this.p.workerHost?.registry ?? null;
+    }
+    /**
+     * W740: the liveness watchdog mounted over this generation's worker registry
+     * (null when the watchdog is off). Adjudication itself belongs to the watchdog
+     * plugin — this is only the host's handle on it (`tick()` by hand, or read
+     * `running`), never a second liveness rule.
+     */
+    get watchdog() {
+        return this.p.workerHost?.watchdog ?? null;
+    }
+    get hostSessionId() {
+        return this.p.workerHost?.hostSessionId ?? null;
+    }
+    get isBusy() {
+        return this.parts !== null && this.parts.runner.isBusy;
+    }
+    get isReleased() {
+        return this.released;
+    }
+    /** Mounted plugin names, in mount order. */
+    get pluginNames() {
+        return this.p.plugins;
+    }
+    // --- driving turns -----------------------------------------------------
+    /** Drive one turn; a second concurrent call is a [TurnBusyError] (409). */
+    async runTurn(input, opts = {}) {
+        this.assertLive();
+        return this.p.runner.runTurn(input, opts);
+    }
+    /** Cancel the in-flight turn (cooperative); false when nothing was running. */
+    cancelTurn() {
+        return this.parts?.runner.cancel() ?? false;
+    }
+    /** Snapshot for the statusline reader (SSE status payloads / GET /api/status). */
+    statusView() {
+        const p = this.p;
+        return {
+            model: p.profile.model,
+            reasoning_effort: p.profile.reasoning_effort,
+            status: p.status,
+            usage: p.usage,
+            context_window: p.profile.context_window_tokens,
+            events: () => this.p.sessionRef.log.events(),
+            // W755 (Fix A): the SAME assembly `/api/sessions/{id}/context` serves, so
+            // the fallback estimate can never drift from the real next request. The
+            // statusline is polled (and pushed on every SSE tick), so a failing read
+            // degrades to "no snapshot" instead of failing the endpoint.
+            assembled: () => {
+                try {
+                    return this.assembledContext();
+                }
+                catch {
+                    return null;
+                }
+            },
+            pressure: this.pressure,
+        };
+    }
+    /** The frozen `/api/status` payload for this generation. */
+    statusline() {
+        return statuslineOf(this.statusView());
+    }
+    /**
+     * W725: this generation's model-visible context, exactly as the loop would
+     * build it for the NEXT step (system + trimmed history + tool schemas), or
+     * null when the mounted loop has no snapshot capability (a test double).
+     *
+     * The assembly is the agent loop's, never this layer's: runtime only forwards
+     * the Context, so the read-only snapshot cannot drift from the real request.
+     *
+     * W762: the result is memoized on the LOG STATE it was derived from, because
+     * the statusline reads it on every 2s tick and the context viewer on every
+     * refresh, while a session log only changes when the engine appends to it.
+     * The key is `(log identity, event count, last event reference)`, all three
+     * cheap to obtain, and it is COMPLETE within one generation: the profile /
+     * trim config is fixed at compose (a config change swaps the generation, not
+     * this object) and the tool surface is mounted at compose too, so
+     * `registry.schemas()` cannot drift under the cache. A rebind swaps the log,
+     * and the identity term catches it even when the new log has the same length.
+     *
+     * Consumers are read-only by construction (`contextViewOf` maps messages into
+     * fresh view rows; `estimatedContextTokens` only reads), so the cached object
+     * is shared rather than copied. A MISS costs one extra `events()` copy (the
+     * key) on top of the assembly: ~0.35ms at 50k events against an 18ms
+     * assembly. A HIT costs only that copy — ~2 orders of magnitude less.
+     */
+    contextSnapshot() {
+        return this.snapshotEntry().request;
+    }
+    /**
+     * W766: the memoized assembly TOGETHER with its token estimate — what the
+     * statusline's `context_usage` fallback needs.
+     *
+     * W755 made the tick read the loop's own assembly; W762 memoized the assembly
+     * but left the ESTIMATE to be recomputed on every read, which dominated the
+     * tick (7.4ms of a 7.4ms tick at 50k events: an O(bytes) walk of the messages
+     * that could not have changed, because the request it walked was the very
+     * object the cache had just handed back). The estimate now rides in the same
+     * entry, so it is derived once per log state and dropped with the request.
+     *
+     * Lazy on purpose: the usage-frame path and the context viewer never read the
+     * estimate, so a MISS must not pay for it (same reason `tokens`/`assembled`
+     * start null rather than being filled by the assembly that built the request).
+     */
+    assembledContext() {
+        const entry = this.snapshotEntry();
+        const request = entry.request;
+        if (request === null)
+            return null;
+        entry.assembled ??= { request, tokens: estimatedContextTokens(request) };
+        return entry.assembled;
+    }
+    /**
+     * The memoized snapshot entry for the log state right now, building (and
+     * caching) the assembly on a miss. This is the ONE cache the runtime keeps:
+     * the request, its estimate and its display wrapper all hang off it, so they
+     * can never disagree about which log state they describe.
+     */
+    snapshotEntry() {
+        const log = this.p.sessionRef.log;
+        const last = lastEventOf(log);
+        const cached = this.snapshotCache;
+        if (cached !== null && cached.log === log && cached.events === last.count && cached.last === last.event) {
+            return cached;
+        }
+        const request = contextSnapshotOf(this.p.agentLoop, this.p.ctx);
+        const entry = { log, events: last.count, last: last.event, request, assembled: null };
+        this.snapshotCache = entry;
+        return entry;
+    }
+    /** Pending host receipts (worker -> host) that the next turn will inject. */
+    pendingReceipts() {
+        const host = this.parts?.workerHost ?? null;
+        return host === null ? 0 : host.registry.mailbox.pending(host.hostSessionId);
+    }
+    /**
+     * Deliver a message into THIS session's inbox on `lane` (W513/W515 §1):
+     * `next-turn` = drained at the next turn start (`placement: "queued"`),
+     * `next-step` = drained at the next step boundary of the RUNNING turn
+     * (`placement: "steering"`). The lane is the caller's decision — the host
+     * knows whether a turn is in flight, the runtime does not guess.
+     */
+    inject(text, lane = "next-turn", opts = {}) {
+        this.assertLive();
+        return this.p.inbox.push(text, lane, opts);
+    }
+    /** Messages queued on one lane, or on both (diagnostics / tests). */
+    pendingInjections(lane) {
+        return this.parts?.inbox.pending(lane) ?? 0;
+    }
+    // --- lifecycle ---------------------------------------------------------
+    /**
+     * Rebind this generation to the SAME session (same directory, same id) by
+     * re-opening its log. Only between turns: mid-turn rebinding would let one
+     * turn write into two logs.
+     */
+    rebind(binding) {
+        this.assertLive();
+        if (this.p.runner.isBusy)
+            throw new TurnBusyError("rebind");
+        const previous = this.p.sessionRef.log;
+        const log = bindSession(this.p.ctx, binding);
+        this.p.sessionRef.log = log;
+        // P1-4 (W836): the swapped-out log descriptor is closed HERE, not left for
+        // a shutdown that may be generations away; a long-lived studio otherwise
+        // leaks one fd per rebind.
+        closeLog(previous);
+        this.binding = binding;
+        // W762: the cached assembly belonged to the log that was just swapped out.
+        this.snapshotCache = null;
+        return log;
+    }
+    /**
+     * Idempotent + re-entrant shutdown: stop drivers, run the host teardown hooks
+     * (process kills), purge mailboxes, clear registries. Repeating it is a no-op
+     * returning the first promise, so concurrent callers cannot double-run a hook.
+     */
+    shutdown() {
+        if (this.shutdownPromise === null)
+            this.shutdownPromise = this.doShutdown();
+        return this.shutdownPromise;
+    }
+    async doShutdown() {
+        const parts = this.parts;
+        parts?.runner.stop();
+        // P1-5 (W836): stop() only aborts cooperatively. Defer the clean-shutdown
+        // claim until the in-flight turn has written its own terminal row.
+        await parts?.runner.join();
+        // E §1.3 P0 ⑤: a graceful teardown is the ONLY thing that may claim
+        // `clean_shutdown: true` in the session's checkpoint sidecar — that flag is
+        // what tells the next boot "do not repair", so a crash (no shutdown at all)
+        // keeps it false. A log without a checkpoint (tests, embedded use) is a no-op.
+        markCleanShutdown(parts?.sessionRef.log);
+        // P1-4 (W836): and a graceful teardown is where the log descriptor dies.
+        closeLog(parts?.sessionRef.log);
+        const host = parts?.workerHost ?? null;
+        if (host !== null) {
+            host.registry.abortAllNow();
+            await host.registry.joinDrivers();
+        }
+        for (const hook of parts?.shutdownHooks ?? [])
+            await runHook(hook);
+        if (host !== null) {
+            host.registry.mailbox.purgeAll();
+            host.registry.sessions.clear();
+        }
+        this.released = true;
+    }
+    /**
+     * Explicit strong-reference drop (the sync half of a hot swap): stop the
+     * runner, abort drivers, release the registry and null every handle. Call it
+     * after [shutdown] when the generation is discarded for good.
+     */
+    release() {
+        const parts = this.parts;
+        if (parts === null)
+            return;
+        parts.runner.stop();
+        // P1-4 (W836): release is the generation's last breath even when shutdown
+        // was skipped (GenerationHub / registry teardown). Close is idempotent, so
+        // the host's own closeLog before release cannot fail here.
+        closeLog(parts.sessionRef.log);
+        if (parts.workerHost !== null) {
+            parts.workerHost.registry.abortAllNow();
+            parts.workerHost.registry.release();
+        }
+        this.parts = null;
+        this.snapshotCache = null;
+        this.released = true;
+    }
+    assertLive() {
+        if (this.released || this.parts === null)
+            throw new RuntimeReleasedError();
+    }
+}
+async function runHook(hook) {
+    try {
+        await hook();
+    }
+    catch {
+        // A failing teardown hook must not stop the remaining ones: shutdown is the
+        // last thing a generation does, and it has to reach the end.
+    }
+}
+/** `(count, last event)` of a log — the cache key half that changes on append. */
+function lastEventOf(log) {
+    const events = log.events();
+    return { count: events.length, event: events[events.length - 1] };
+}
+/** Host-facing convenience: a sink that only collects frames (tests / CLI). */
+export function collectingSink() {
+    const frames = [];
+    return { frames, sink: (frame) => frames.push(frame) };
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generation-level config sanitization.
+ *
+ * `GET/POST /api/config` hands the current generation's configuration to the
+ * client, so the projection is a whitelist: only the twelve frozen profile keys
+ * (minus the two key-bearing ones, which become existence flags) plus the
+ * derived loop budget. The result is then run through core's redactor before it
+ * is ever serialized, so a credential that sneaks into `base_url` cannot leave
+ * the process (ARCHITECTURE.md §6.3).
+ */
+import type { Profile } from "./profile.js";
+/** Client-facing projection of a [Profile]: no secret value, ever. */
+export interface SanitizedConfig {
+    model: string;
+    base_url: string;
+    request_format: Profile["request_format"];
+    reasoning_effort: string | null;
+    max_steps: number;
+    max_parallel_tool_calls: number;
+    max_output_tokens: number | null;
+    context_window_tokens: number;
+    temperature: number | null;
+    system_prompt: string;
+    /** Env var NAME the key is read from — a name is not a secret. */
+    api_key_env: string;
+    has_api_key_file: boolean;
+}
+/** Whitelist projection of a profile (`api_key_file` becomes a boolean). */
+export declare function sanitizeProfile(profile: Profile): SanitizedConfig;
+/**
+ * The sanitized config as stable, redaction-clean JSON text. Redaction runs on
+ * every serialization (not once at compose), so the export can never carry a
+ * secret even if a future profile key smuggles one in.
+ */
+export declare function sanitizeConfigJson(config: SanitizedConfig): string;

package/dist/sanitize.js

@@ -0,0 +1,36 @@
+/**
+ * Generation-level config sanitization.
+ *
+ * `GET/POST /api/config` hands the current generation's configuration to the
+ * client, so the projection is a whitelist: only the twelve frozen profile keys
+ * (minus the two key-bearing ones, which become existence flags) plus the
+ * derived loop budget. The result is then run through core's redactor before it
+ * is ever serialized, so a credential that sneaks into `base_url` cannot leave
+ * the process (ARCHITECTURE.md §6.3).
+ */
+import { createRedactor, stableStringify } from "@celestea/core";
+/** Whitelist projection of a profile (`api_key_file` becomes a boolean). */
+export function sanitizeProfile(profile) {
+    return {
+        model: profile.model,
+        base_url: profile.base_url,
+        request_format: profile.request_format,
+        reasoning_effort: profile.reasoning_effort,
+        max_steps: profile.max_steps,
+        max_parallel_tool_calls: profile.max_parallel_tool_calls,
+        max_output_tokens: profile.max_output_tokens,
+        context_window_tokens: profile.context_window_tokens,
+        temperature: profile.temperature,
+        system_prompt: profile.system_prompt,
+        api_key_env: profile.api_key_env,
+        has_api_key_file: profile.api_key_file !== null,
+    };
+}
+/**
+ * The sanitized config as stable, redaction-clean JSON text. Redaction runs on
+ * every serialization (not once at compose), so the export can never carry a
+ * secret even if a future profile key smuggles one in.
+ */
+export function sanitizeConfigJson(config) {
+    return createRedactor([]).redact(stableStringify(config));
+}

package/dist/session-binding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Session binding — how a generation is tied to ONE conversation.
+ *
+ * A binding is (session id + directory + a way to open the log). Keeping the
+ * opener as a callback is what lets the runtime stay out of the persistence
+ * business: `packages/session` owns JSONL replay/repair, the host passes
+ * `() => PersistentSessionLog.open(dir, id)`, and the runtime only knows the
+ * `SessionLog` seam.
+ *
+ * Rebinding re-opens the SAME directory/id (`binding.open()` again) and
+ * re-provides the result under `SESSION_LOG_SERVICE`; a later `provide` of the
+ * same token replaces the earlier one, so every consumer that resolves the
+ * service lazily (the agent loop does, per turn) sees the new log while an
+ * in-flight reader keeps the object it already holds.
+ */
+import { type Context, type SessionLog } from "@celestea/core";
+export interface SessionBinding {
+    /** Conversation id (`<workspace>/<session>` or the host id). */
+    readonly sessionId: string;
+    /** Session directory; the same value is reused by every rebind. */
+    readonly dir: string | null;
+    /** Open (or re-open) the log for this binding. Called at compose and on rebind. */
+    open(): SessionLog;
+}
+export interface SessionBindingSpec {
+    sessionId: string;
+    dir?: string | null;
+    open: () => SessionLog;
+}
+/** Ergonomic constructor for a binding (a plain object literal also works). */
+export declare function createSessionBinding(spec: SessionBindingSpec): SessionBinding;
+/**
+ * Open the binding and provide it into the context (last `provide` wins). The
+ * opened log is returned so the caller can keep a direct handle.
+ */
+export declare function bindSession(ctx: Context, binding: SessionBinding): SessionLog;