@celestea/runtime 2.7.1

package/dist/host/engine-session.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Engine-side session binding helpers.
+ *
+ * The host owns the id space (`<workspace>/<session>`); the engine owns the
+ * file name: every session directory holds ONE append-only `cli-main.jsonl`
+ * (`celestea_studio/src/workspaces.rs` SESSION_FILE), so the log is always
+ * opened under the fixed session id `cli-main` and never under the host id —
+ * otherwise `file_name_for` would sanitize `ws/s1` into `ws_s1.jsonl` and the
+ * engine would talk to a file the host never reads.
+ *
+ * When nothing is active (or the id is unknown) the generation runs on an
+ * in-memory log: `/api/turn` still works, and the adapter never invents a
+ * directory on behalf of the operator.
+ *
+ * E §1.3 P0 ②: a persistent log is wrapped in a checkpoint decorator, so every
+ * `turn_start`/`turn_end` it records also updates `<dir>/checkpoint.json`. An
+ * in-memory (detached) session has no directory and therefore no sidecar.
+ *
+ * W747: moved verbatim from `apps/studio/src/runtime/engine-session.ts` into the
+ * runtime's host layer (behaviour, export names and log format unchanged; the old
+ * path is now a re-export shim). The only edit is the import of the intra-package
+ * session binding (`../session-binding.js` instead of the `@celestea/runtime`
+ * alias, which would be a package self-cycle). `sessionIdOfDir` came with it, out
+ * of the host's grants reader (`engine-grants.ts`), because the id space is what
+ * this module already documents; the old path re-exports it unchanged.
+ */
+import { type CheckpointIdentity } from "@celestea/session";
+import type { SessionLog } from "@celestea/core";
+import { type SessionBinding } from "../session-binding.js";
+/** The engine's per-session log file name. */
+export declare const SESSION_LOG_NAME = "cli-main.jsonl";
+/** The session id the log is opened under (keeps the file name cli-main.jsonl). */
+export declare const SESSION_LOG_ID = "cli-main";
+/**
+ * W768: a session's workspace as ONE value — the display NAME the system prompt
+ * renders and the ROOT PATH the tools/sandbox must run in.
+ *
+ * They travel together because they are the same fact seen twice: two
+ * independent lookups (a prompt that says "CelesteaTeamAPI" and a shell that
+ * starts in whatever the process was launched from) drifted apart into a bug the
+ * model then reasoned from. A caller that needs either one resolves this value.
+ */
+export interface SessionWorkspace {
+    /** Workspace key: the basename of `path` (`CelesteaTeamAPI`). */
+    name: string;
+    /** Absolute workspace root — the session's cwd and containment root. */
+    path: string;
+}
+/** Where an active session lives (the host resolves the id; dir may be null). */
+export interface SessionTarget {
+    sessionId: string;
+    dir: string | null;
+    /** W768: the session's workspace, resolved by the host alongside `dir`. */
+    workspace?: SessionWorkspace | null;
+}
+/**
+ * Checkpoint wiring of one host process. `identity` is the `pid`/`boot_id` pair
+ * written into every sidecar (E §1.2.2); tests inject a fixed one so the written
+ * file is deterministic.
+ */
+export interface CheckpointWiring {
+    /**
+     * W878: the TRUSTED `<workspace>/<session>` id of this session, from the
+     * host's own `resolve()` (`ResolvedSession.id`). When present it is the
+     * sidecar's self-description; when absent the legacy `sessionIdOfDir(dir)`
+     * fallback below is used, which only holds while the session directory is a
+     * direct child of the workspace root. New callers must thread the id.
+     */
+    sessionId?: string;
+    identity?: CheckpointIdentity;
+    now?: () => number;
+    warn?: (message: string) => void;
+    /**
+     * E §1.3 P1 ③: the audit channel of a DEGRADED log — the sidecar's
+     * `degraded.log_write_errors` just became non-zero, so disk and memory have
+     * forked. Called at most once per session store.
+     */
+    onDegraded?: (info: {
+        session: string;
+        count: number;
+    }) => void;
+}
+/** `boot_id` is generated ONCE per process and never again while it lives. */
+export declare const PROCESS_CHECKPOINT_IDENTITY: CheckpointIdentity;
+/**
+ * `<workspace>/<session>` of a session directory (the file's self-description).
+ *
+ * W878 legacy: this infers the id from the PATH, so it is only correct while the
+ * session directory is a direct child of the workspace root. It stays exported
+ * for callers/tests that still derive the id, but inside the library it is no
+ * longer the source of truth — `openSessionLog` prefers the explicit
+ * `CheckpointWiring.sessionId` and only falls back here when none was threaded.
+ */
+export declare function sessionIdOfDir(sessionDir: string): string;
+/**
+ * Open (replaying) the append-only log of a session directory, wrapped so the
+ * turn boundaries also land in `<dir>/checkpoint.json` (E §1.3 P0 ②). The
+ * wrapper is transparent: `path`, `close()` and `writeErrorCount()` still work
+ * for the host and for the registry's turn-counter restoration.
+ */
+export declare function openSessionLog(dir: string, wiring?: CheckpointWiring): SessionLog;
+/** One in-memory log per detached session id, reused across rebinds. */
+export declare function memoryBindingFor(logs: Map<string, SessionLog>, sessionId: string | null): SessionBinding;
+/** The binding for a host session id (persistent when a directory is known). */
+export declare function bindingFor(sessionId: string | null, target: SessionTarget | null, logs: Map<string, SessionLog>, wiring?: CheckpointWiring): SessionBinding;
+/**
+ * Worker session-id prefix of one host session (W513).
+ *
+ * Every session runtime owns its OWN worker registry, and a registry mints
+ * `session-<n>` by default — which would collide across sessions in the merged
+ * `GET /api/sessions` view. The session id therefore prefixes the ids
+ * (`sample-ws_s1-session-0`); the detached runtime keeps the frozen
+ * `session-<n>` shape so single-session hosts and fixtures are unchanged.
+ */
+export declare function workerSessionPrefix(sessionId: string | null): string;
+/** Close a session log when its implementation owns a descriptor (idempotent). */
+export declare function closeLog(log: SessionLog | null | undefined): void;

package/dist/host/engine-session.js

@@ -0,0 +1,109 @@
+/**
+ * Engine-side session binding helpers.
+ *
+ * The host owns the id space (`<workspace>/<session>`); the engine owns the
+ * file name: every session directory holds ONE append-only `cli-main.jsonl`
+ * (`celestea_studio/src/workspaces.rs` SESSION_FILE), so the log is always
+ * opened under the fixed session id `cli-main` and never under the host id —
+ * otherwise `file_name_for` would sanitize `ws/s1` into `ws_s1.jsonl` and the
+ * engine would talk to a file the host never reads.
+ *
+ * When nothing is active (or the id is unknown) the generation runs on an
+ * in-memory log: `/api/turn` still works, and the adapter never invents a
+ * directory on behalf of the operator.
+ *
+ * E §1.3 P0 ②: a persistent log is wrapped in a checkpoint decorator, so every
+ * `turn_start`/`turn_end` it records also updates `<dir>/checkpoint.json`. An
+ * in-memory (detached) session has no directory and therefore no sidecar.
+ *
+ * W747: moved verbatim from `apps/studio/src/runtime/engine-session.ts` into the
+ * runtime's host layer (behaviour, export names and log format unchanged; the old
+ * path is now a re-export shim). The only edit is the import of the intra-package
+ * session binding (`../session-binding.js` instead of the `@celestea/runtime`
+ * alias, which would be a package self-cycle). `sessionIdOfDir` came with it, out
+ * of the host's grants reader (`engine-grants.ts`), because the id space is what
+ * this module already documents; the old path re-exports it unchanged.
+ */
+import { basename, dirname } from "node:path";
+import { InMemorySessionLog } from "@celestea/session";
+import { PersistentSessionLog } from "@celestea/session";
+import { checkpointedLog, CheckpointStore, currentProcessIdentity, writeErrorCountOf, } from "@celestea/session";
+import { createSessionBinding } from "../session-binding.js";
+/** The engine's per-session log file name. */
+export const SESSION_LOG_NAME = "cli-main.jsonl";
+/** The session id the log is opened under (keeps the file name cli-main.jsonl). */
+export const SESSION_LOG_ID = "cli-main";
+/** `boot_id` is generated ONCE per process and never again while it lives. */
+export const PROCESS_CHECKPOINT_IDENTITY = currentProcessIdentity();
+/**
+ * `<workspace>/<session>` of a session directory (the file's self-description).
+ *
+ * W878 legacy: this infers the id from the PATH, so it is only correct while the
+ * session directory is a direct child of the workspace root. It stays exported
+ * for callers/tests that still derive the id, but inside the library it is no
+ * longer the source of truth — `openSessionLog` prefers the explicit
+ * `CheckpointWiring.sessionId` and only falls back here when none was threaded.
+ */
+export function sessionIdOfDir(sessionDir) {
+    return `${basename(dirname(sessionDir))}/${basename(sessionDir)}`;
+}
+/**
+ * Open (replaying) the append-only log of a session directory, wrapped so the
+ * turn boundaries also land in `<dir>/checkpoint.json` (E §1.3 P0 ②). The
+ * wrapper is transparent: `path`, `close()` and `writeErrorCount()` still work
+ * for the host and for the registry's turn-counter restoration.
+ */
+export function openSessionLog(dir, wiring = {}) {
+    const log = PersistentSessionLog.open(dir, SESSION_LOG_ID);
+    const store = new CheckpointStore({
+        dir,
+        // Self-description `<workspace>/<session>` — the id grants.json also uses, so
+        // a sidecar found in a renamed directory is ignored instead of trusted.
+        // W878: the explicit id wins; `sessionIdOfDir` is only the legacy fallback
+        // for callers that have no trusted id (it is wrong once a session dir sinks
+        // below the workspace root, e.g. `<ws>/.celestea/sessions/<dir>`).
+        session: wiring.sessionId ?? sessionIdOfDir(dir),
+        identity: wiring.identity ?? PROCESS_CHECKPOINT_IDENTITY,
+        ...(wiring.now === undefined ? {} : { now: wiring.now }),
+        ...(wiring.warn === undefined ? {} : { warn: wiring.warn }),
+        logWriteErrors: () => writeErrorCountOf(log),
+        ...(wiring.onDegraded === undefined ? {} : { onDegraded: wiring.onDegraded }),
+    });
+    return checkpointedLog(log, store);
+}
+/** One in-memory log per detached session id, reused across rebinds. */
+export function memoryBindingFor(logs, sessionId) {
+    const key = sessionId ?? "<detached>";
+    const log = logs.get(key) ?? new InMemorySessionLog();
+    logs.set(key, log);
+    return createSessionBinding({ sessionId: key, dir: null, open: () => log });
+}
+/** The binding for a host session id (persistent when a directory is known). */
+export function bindingFor(sessionId, target, logs, wiring = {}) {
+    if (sessionId === null || target === null || target.dir === null)
+        return memoryBindingFor(logs, sessionId);
+    const dir = target.dir;
+    // W878: thread the trusted id into the sidecar wiring. `sessionId` is narrowed
+    // to a string here, so the checkpoint store never has to infer it from `dir`.
+    return createSessionBinding({ sessionId, dir, open: () => openSessionLog(dir, { ...wiring, sessionId }) });
+}
+/**
+ * Worker session-id prefix of one host session (W513).
+ *
+ * Every session runtime owns its OWN worker registry, and a registry mints
+ * `session-<n>` by default — which would collide across sessions in the merged
+ * `GET /api/sessions` view. The session id therefore prefixes the ids
+ * (`sample-ws_s1-session-0`); the detached runtime keeps the frozen
+ * `session-<n>` shape so single-session hosts and fixtures are unchanged.
+ */
+export function workerSessionPrefix(sessionId) {
+    if (sessionId === null)
+        return "session-";
+    return `${sessionId.replace(/[^A-Za-z0-9._-]/g, "_")}-session-`;
+}
+/** Close a session log when its implementation owns a descriptor (idempotent). */
+export function closeLog(log) {
+    const close = log === null || log === undefined ? undefined : log.close;
+    if (typeof close === "function")
+        close.call(log);
+}

package/dist/host/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * W747 — the host layer of the engine assembly.
+ *
+ * The engine's true composition root used to live entirely in `apps/studio`
+ * (`apps/studio/src/runtime/**`, ~2500 lines): profile resolution, provider
+ * targeting, session-log binding, tool/sandbox/guard assembly, grants policy.
+ * `@celestea/runtime` only mounted plugins. W732 §A2 / §F1 flagged that as the
+ * largest gap between the documented layering and the code, so the engine-side
+ * half moves here, one bounded cut at a time.
+ *
+ * Rules for this layer:
+ *   1. `packages/*` may never import `apps/*` (dependency-cruiser
+ *      `no-packages-to-apps`): a module only moves here once it depends on
+ *      nothing but `@celestea/core`, the L1 packages and `../` internals.
+ *   2. The host keeps its HTTP shapes and its data files. When a module needs a
+ *      host-owned type, the MINIMAL structural slice it reads is declared here
+ *      (see `ProfileSlot` in `provider-target.ts`) — never a copy of the host
+ *      view, and never a host import.
+ *   3. Nothing is re-written while moving: behaviour, export names and error
+ *      text stay byte-identical, and the old `apps/studio/src/runtime/<mod>.ts`
+ *      path stays alive as a re-export shim so existing imports do not break.
+ *
+ * These modules are NOT a package subpath: everything below is re-exported by
+ * `../index.ts`, the package's only public API (cross-package deep imports are
+ * forbidden by `dependency-cruiser` and ESLint). A subpath export would need an
+ * exception in `.dependency-cruiser.cjs`; that is a separate decision.
+ *
+ * Moved so far (W747, first cut):
+ *   engine-session.ts  log/binding assembly + the `<ws>/<session>` id helper
+ *   provider-target.ts startup model/base_url/api-key resolution (W511)
+ * Still in `apps/studio/src/runtime/` and blocked — see the W747 report:
+ *   engine-profile.ts  needs `EngineProfile`/`ProfilePatch` (apps runtime-adapter)
+ *                      and `MIN_STEPS`/`CONTEXT_WINDOW` (apps config)
+ *   engine-plugins.ts  needs `@celestea/tools` in packages/runtime/package.json
+ *   llm-assembly.ts    needs `@celestea/llm` in packages/runtime/package.json
+ *   session-compose.ts needs `CapacityError` (apps runtime-adapter) + the above
+ */
+export * from "./engine-session.js";
+export * from "./provider-target.js";

package/dist/host/index.js

@@ -0,0 +1,39 @@
+/**
+ * W747 — the host layer of the engine assembly.
+ *
+ * The engine's true composition root used to live entirely in `apps/studio`
+ * (`apps/studio/src/runtime/**`, ~2500 lines): profile resolution, provider
+ * targeting, session-log binding, tool/sandbox/guard assembly, grants policy.
+ * `@celestea/runtime` only mounted plugins. W732 §A2 / §F1 flagged that as the
+ * largest gap between the documented layering and the code, so the engine-side
+ * half moves here, one bounded cut at a time.
+ *
+ * Rules for this layer:
+ *   1. `packages/*` may never import `apps/*` (dependency-cruiser
+ *      `no-packages-to-apps`): a module only moves here once it depends on
+ *      nothing but `@celestea/core`, the L1 packages and `../` internals.
+ *   2. The host keeps its HTTP shapes and its data files. When a module needs a
+ *      host-owned type, the MINIMAL structural slice it reads is declared here
+ *      (see `ProfileSlot` in `provider-target.ts`) — never a copy of the host
+ *      view, and never a host import.
+ *   3. Nothing is re-written while moving: behaviour, export names and error
+ *      text stay byte-identical, and the old `apps/studio/src/runtime/<mod>.ts`
+ *      path stays alive as a re-export shim so existing imports do not break.
+ *
+ * These modules are NOT a package subpath: everything below is re-exported by
+ * `../index.ts`, the package's only public API (cross-package deep imports are
+ * forbidden by `dependency-cruiser` and ESLint). A subpath export would need an
+ * exception in `.dependency-cruiser.cjs`; that is a separate decision.
+ *
+ * Moved so far (W747, first cut):
+ *   engine-session.ts  log/binding assembly + the `<ws>/<session>` id helper
+ *   provider-target.ts startup model/base_url/api-key resolution (W511)
+ * Still in `apps/studio/src/runtime/` and blocked — see the W747 report:
+ *   engine-profile.ts  needs `EngineProfile`/`ProfilePatch` (apps runtime-adapter)
+ *                      and `MIN_STEPS`/`CONTEXT_WINDOW` (apps config)
+ *   engine-plugins.ts  needs `@celestea/tools` in packages/runtime/package.json
+ *   llm-assembly.ts    needs `@celestea/llm` in packages/runtime/package.json
+ *   session-compose.ts needs `CapacityError` (apps runtime-adapter) + the above
+ */
+export * from "./engine-session.js";
+export * from "./provider-target.js";

package/dist/host/provider-target.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Startup provider-target resolution (W511) — the TS port of the legacy
+ * `providers::apply_startup_default` + `resolve_base_url` + `resolve_api_key`.
+ *
+ * providers.json is the operator's registry of upstreams; resolving a target
+ * means answering three questions BEFORE the first compose (and again on every
+ * generation swap, from the host's own profile):
+ *
+ *   model     `default_model` IS IN the models list of some provider -> that id
+ *             ("providers.json default_model");
+ *             else env `CELESTEA_MODEL` -> "env CELESTEA_MODEL";
+ *             else whatever the caller's profile already carried
+ *             ("profile default", i.e. the celestea.toml slot).
+ *             An unlisted `default_model` never wins: the contract validates it
+ *             against the provider rows instead of trusting a stale string.
+ *   base_url  the provider that OWNS the resolved model, when its
+ *             request_format is chat_completions and its base_url is non-empty
+ *             (written into the profile before compose);
+ *             else env `CELESTEA_BASE_URL` -> else the profile's own base_url.
+ *   api key   env[api_key_env] when non-empty; otherwise a plaintext key stored
+ *             on the owning provider row is injected into the PROCESS ENV (the
+ *             engine's only key channel, exactly like the engine's `env::set_var`).
+ *             In-memory only: never written to a data file, never returned in a
+ *             response, never logged.
+ *
+ * The module is store-free: it consumes the three `ProvidersStore` methods it
+ * needs, so the rules are unit-testable without a data file.
+ *
+ * W747: moved verbatim from `apps/studio/src/runtime/provider-target.ts` into the
+ * runtime's host layer (rules, export names and behaviour unchanged; the old
+ * path is now a re-export shim). The ONE edit is the profile slice below: the
+ * host view (`EngineProfile`) lives in `apps/studio/src/runtime-adapter.ts` and a
+ * package may not import an app, so the three fields this module actually reads
+ * are declared here as the minimal structural `ProfileSlot` that the host view
+ * already satisfies. `applyProviderTarget` is generic in it, so a caller holding
+ * an `EngineProfile` gets that exact type back.
+ */
+/** The startup-profile slice this module reads (satisfied by the host's view). */
+export interface ProfileSlot {
+    model: string;
+    base_url: string;
+    api_key_env: string;
+}
+/** The fields of a providers.json row this module reads. */
+export interface ProviderRef {
+    id: string;
+    base_url: string;
+    request_format: string;
+    api_key: string | null;
+    models: readonly {
+        id: string;
+    }[];
+}
+/** The `ProvidersStore` slice this module needs. */
+export interface ProviderLookup {
+    rows(): readonly ProviderRef[];
+    defaultModel(): string | null;
+}
+/** Where the resolved model id came from (reported by the startup log). */
+export type ModelSource = "providers.json default_model" | "env CELESTEA_MODEL" | "profile default";
+/**
+ * Where the api key came from; "none" means unauthenticated requests.
+ *
+ * W747: named `ProviderKeySource` in the engine because `profile.ts` already
+ * exports a `KeySource` — the `resolve_api_key` ORDER (`env` / `api_key_file`
+ * / `home_config` / `provider_store` / `borrowed_engine_key` / `none`), which is a
+ * different, wider vocabulary. Two exports cannot share one name in a package's
+ * single public API, and the host's narrower 3-value union is what the startup
+ * log reports; the host-side shim re-exports it under its original name, so no
+ * `apps/studio` import changed.
+ */
+export type ProviderKeySource = "env" | "provider_store" | "none";
+export interface ProviderTarget {
+    model: string;
+    base_url: string;
+    /** The provider row that lists `model` (null = no provider claims it). */
+    provider_id: string | null;
+    model_source: ModelSource;
+    key_source: ProviderKeySource;
+}
+/** The request format that has a live adapter today (`ENGINE_FORMAT`). */
+export declare const CHAT_COMPLETIONS_FORMAT = "chat_completions";
+/** Every model id any provider row lists (the `default_model` allow-list). */
+export declare function listedModelIds(lookup: ProviderLookup): Set<string>;
+/** Resolve the model id + its source. Pure: no env mutation, no I/O. */
+export declare function resolveModel(lookup: ProviderLookup, env: NodeJS.ProcessEnv, fallbackModel: string): {
+    model: string;
+    source: ModelSource;
+};
+/** The first provider row listing `model` (`find_provider_with_model`). */
+export declare function ownerOf(lookup: ProviderLookup, model: string): ProviderRef | null;
+/** `resolve_base_url(profile, env)` restricted to the TS channels. */
+export declare function resolveBaseUrl(owner: ProviderRef | null, env: NodeJS.ProcessEnv, profileBaseUrl: string): string;
+/**
+ * The key to authenticate with: the deployment's env key wins, a keyless env
+ * borrows the owning provider's stored key (injected into the process env by
+ * the caller). Blank values never count as "configured".
+ */
+export declare function resolveProviderKey(owner: ProviderRef | null, env: NodeJS.ProcessEnv, apiKeyEnv: string): {
+    key: string | null;
+    source: ProviderKeySource;
+};
+/** The three answers together, from the host's startup profile. */
+export declare function resolveProviderTarget(lookup: ProviderLookup, env: NodeJS.ProcessEnv, base: ProfileSlot): ProviderTarget;
+/**
+ * Apply a target to the startup profile and hand the secret to the process env.
+ * The key is written to `env[api_key_env]` ONLY — the returned profile and every
+ * log line stay key-free. Returns the profile plus the applied target.
+ */
+export declare function applyProviderTarget<P extends ProfileSlot>(base: P, target: ProviderTarget, lookup: ProviderLookup, env: NodeJS.ProcessEnv): {
+    profile: P;
+    target: ProviderTarget;
+};

package/dist/host/provider-target.js

@@ -0,0 +1,116 @@
+/**
+ * Startup provider-target resolution (W511) — the TS port of the legacy
+ * `providers::apply_startup_default` + `resolve_base_url` + `resolve_api_key`.
+ *
+ * providers.json is the operator's registry of upstreams; resolving a target
+ * means answering three questions BEFORE the first compose (and again on every
+ * generation swap, from the host's own profile):
+ *
+ *   model     `default_model` IS IN the models list of some provider -> that id
+ *             ("providers.json default_model");
+ *             else env `CELESTEA_MODEL` -> "env CELESTEA_MODEL";
+ *             else whatever the caller's profile already carried
+ *             ("profile default", i.e. the celestea.toml slot).
+ *             An unlisted `default_model` never wins: the contract validates it
+ *             against the provider rows instead of trusting a stale string.
+ *   base_url  the provider that OWNS the resolved model, when its
+ *             request_format is chat_completions and its base_url is non-empty
+ *             (written into the profile before compose);
+ *             else env `CELESTEA_BASE_URL` -> else the profile's own base_url.
+ *   api key   env[api_key_env] when non-empty; otherwise a plaintext key stored
+ *             on the owning provider row is injected into the PROCESS ENV (the
+ *             engine's only key channel, exactly like the engine's `env::set_var`).
+ *             In-memory only: never written to a data file, never returned in a
+ *             response, never logged.
+ *
+ * The module is store-free: it consumes the three `ProvidersStore` methods it
+ * needs, so the rules are unit-testable without a data file.
+ *
+ * W747: moved verbatim from `apps/studio/src/runtime/provider-target.ts` into the
+ * runtime's host layer (rules, export names and behaviour unchanged; the old
+ * path is now a re-export shim). The ONE edit is the profile slice below: the
+ * host view (`EngineProfile`) lives in `apps/studio/src/runtime-adapter.ts` and a
+ * package may not import an app, so the three fields this module actually reads
+ * are declared here as the minimal structural `ProfileSlot` that the host view
+ * already satisfies. `applyProviderTarget` is generic in it, so a caller holding
+ * an `EngineProfile` gets that exact type back.
+ */
+/** The request format that has a live adapter today (`ENGINE_FORMAT`). */
+export const CHAT_COMPLETIONS_FORMAT = "chat_completions";
+function trimmed(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+/** Every model id any provider row lists (the `default_model` allow-list). */
+export function listedModelIds(lookup) {
+    const ids = new Set();
+    for (const p of lookup.rows())
+        for (const m of p.models)
+            ids.add(m.id);
+    return ids;
+}
+/** Resolve the model id + its source. Pure: no env mutation, no I/O. */
+export function resolveModel(lookup, env, fallbackModel) {
+    const declared = trimmed(lookup.defaultModel());
+    if (declared !== "" && listedModelIds(lookup).has(declared)) {
+        return { model: declared, source: "providers.json default_model" };
+    }
+    const fromEnv = trimmed(env["CELESTEA_MODEL"]);
+    if (fromEnv !== "")
+        return { model: fromEnv, source: "env CELESTEA_MODEL" };
+    return { model: fallbackModel, source: "profile default" };
+}
+/** The first provider row listing `model` (`find_provider_with_model`). */
+export function ownerOf(lookup, model) {
+    for (const p of lookup.rows()) {
+        if (p.models.some((m) => m.id === model))
+            return p;
+    }
+    return null;
+}
+/** `resolve_base_url(profile, env)` restricted to the TS channels. */
+export function resolveBaseUrl(owner, env, profileBaseUrl) {
+    if (owner !== null && owner.request_format === CHAT_COMPLETIONS_FORMAT && trimmed(owner.base_url) !== "") {
+        return owner.base_url;
+    }
+    const fromEnv = trimmed(env["CELESTEA_BASE_URL"]);
+    return fromEnv === "" ? profileBaseUrl : fromEnv;
+}
+/**
+ * The key to authenticate with: the deployment's env key wins, a keyless env
+ * borrows the owning provider's stored key (injected into the process env by
+ * the caller). Blank values never count as "configured".
+ */
+export function resolveProviderKey(owner, env, apiKeyEnv) {
+    if (trimmed(env[apiKeyEnv]) !== "")
+        return { key: trimmed(env[apiKeyEnv]), source: "env" };
+    const stored = trimmed(owner?.api_key);
+    return stored === "" ? { key: null, source: "none" } : { key: stored, source: "provider_store" };
+}
+/** The three answers together, from the host's startup profile. */
+export function resolveProviderTarget(lookup, env, base) {
+    const { model, source } = resolveModel(lookup, env, base.model);
+    const owner = ownerOf(lookup, model);
+    const { source: keySource } = resolveProviderKey(owner, env, base.api_key_env);
+    return {
+        model,
+        base_url: resolveBaseUrl(owner, env, base.base_url),
+        provider_id: owner?.id ?? null,
+        model_source: source,
+        key_source: keySource,
+    };
+}
+/**
+ * Apply a target to the startup profile and hand the secret to the process env.
+ * The key is written to `env[api_key_env]` ONLY — the returned profile and every
+ * log line stay key-free. Returns the profile plus the applied target.
+ */
+export function applyProviderTarget(base, target, lookup, env) {
+    const owner = target.provider_id === null ? null : ownerOf(lookup, target.model);
+    const { key, source } = resolveProviderKey(owner, env, base.api_key_env);
+    if (key !== null)
+        env[base.api_key_env] = key;
+    return {
+        profile: { ...base, model: target.model, base_url: target.base_url },
+        target: { ...target, key_source: source },
+    };
+}

package/dist/inbox-checkpoint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The inbox's persistence sink over one session's `checkpoint.json` (E §1.3 P1 ①).
+ *
+ * WHY the checkpoint and not a file of its own: §1.2.1 fixes the classification —
+ * "everything derivable from `cli-main.jsonl` is NOT persisted twice" — and the
+ * two queue lanes plus the accepted-id ledger are exactly the facts the log
+ * cannot express. Putting them in the sidecar also means ONE atomic write path
+ * (tmp-<pid> + rename, mode 0600) for every non-log fact of the session.
+ *
+ * The sink is intentionally tiny and total: `load()` returns null for a missing,
+ * corrupt or foreign sidecar (a queue that cannot be read is simply empty — the
+ * same fail-safe discipline the recovery decision table uses), and `save()`
+ * never throws (the store reports its own failures on stderr).
+ */
+import type { CheckpointStore } from "@celestea/session";
+import type { InboxSink } from "./inbox.js";
+/** Bind an inbox to the session sidecar's two lanes + delivered-id ledger. */
+export declare function checkpointInboxSink(store: CheckpointStore): InboxSink;

package/dist/inbox-checkpoint.js

@@ -0,0 +1,37 @@
+/**
+ * The inbox's persistence sink over one session's `checkpoint.json` (E §1.3 P1 ①).
+ *
+ * WHY the checkpoint and not a file of its own: §1.2.1 fixes the classification —
+ * "everything derivable from `cli-main.jsonl` is NOT persisted twice" — and the
+ * two queue lanes plus the accepted-id ledger are exactly the facts the log
+ * cannot express. Putting them in the sidecar also means ONE atomic write path
+ * (tmp-<pid> + rename, mode 0600) for every non-log fact of the session.
+ *
+ * The sink is intentionally tiny and total: `load()` returns null for a missing,
+ * corrupt or foreign sidecar (a queue that cannot be read is simply empty — the
+ * same fail-safe discipline the recovery decision table uses), and `save()`
+ * never throws (the store reports its own failures on stderr).
+ */
+/** Bind an inbox to the session sidecar's two lanes + delivered-id ledger. */
+export function checkpointInboxSink(store) {
+    return {
+        load() {
+            const persisted = store.persistedQueues();
+            if (persisted === null)
+                return null;
+            return {
+                // Writing is structurally compatible (a message IS a lane message); the
+                // read direction narrows `lane`/`kind`/`source`, which only the inbox can
+                // guarantee — hence exactly one cast, at the boundary (K1: no sibling
+                // import just to share the type).
+                next_turn: persisted.lanes.next_turn,
+                next_step: persisted.lanes.next_step,
+                delivered_ids: persisted.delivered_ids,
+            };
+        },
+        save(snapshot) {
+            const write = (messages) => [...messages];
+            store.lanesChanged(write(snapshot.next_turn), write(snapshot.next_step), snapshot.delivered_ids);
+        },
+    };
+}