@celestea/studio 2.7.1

package/dist/runtime/recovery-audit.js

@@ -0,0 +1,95 @@
+/**
+ * The iteration-E recovery audit channel (E §5.2③, P1).
+ *
+ * §5.2③: every automatic or observed recovery fact must appear in three places —
+ * an append-only local log, a structured field and an audit line. W730's P0
+ * deliberately deferred the audit half of the checkpoint capability because
+ * inventing a second audit FILE then had no owner; P1 is that owner, and this is
+ * the ONE channel both P1 capabilities write through:
+ *
+ *   - `log_degraded`      — a session log refused a write (`writeErrorCount>0`):
+ *                           disk and memory forked, and nobody would ever know;
+ *   - `worker_stale`      — a persisted worker row whose owning process is dead;
+ *   - `worker_orphan`     — a RUNNING row whose `host=` session is gone;
+ *   - `worker_observed`   — the boot sweep's summary line (always exactly one);
+ *   - `session_repaired`  — a crashed turn was closed by appending ONE
+ *                           `turn_end: interrupted` row (§1.2.3, R1-1).
+ *
+ * Discipline (identical to `grants-audit.jsonl` / `fallbacks-audit.jsonl`):
+ * local append-only `<data dir>/recovery-audit.jsonl`, mode 0600, rotated at
+ * 16 MiB; the platform `POST /api/audit` is BEST-EFFORT and only when
+ * `CELESTEA_AUDIT_URL` is set. A failed write is reported, never thrown — an
+ * audit channel must not be able to break the thing it observes. Nothing here
+ * ever records a prompt, a command line or a credential: wid / turn_id / count
+ * only (§4.4).
+ */
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const RECOVERY_AUDIT_FILE = "recovery-audit.jsonl";
+/** Rotate at 16 MiB, keeping the previous chain (LTS ops audit rules). */
+export const RECOVERY_AUDIT_MAX_BYTES = 16 * 1024 * 1024;
+export const ENV_AUDIT_URL = "CELESTEA_AUDIT_URL";
+export const ENV_CENTER_TOKEN = "CELESTEA_CENTER_TOKEN";
+export class RecoveryAuditWriter {
+    path;
+    env;
+    now;
+    post;
+    /** Diagnostics of failed writes (never thrown): the caller reports them. */
+    errors = [];
+    constructor(opts) {
+        this.path = join(opts.dataDir, RECOVERY_AUDIT_FILE);
+        this.env = opts.env ?? process.env;
+        this.now = opts.now ?? Date.now;
+        this.post = opts.post ?? defaultPost;
+    }
+    get filePath() {
+        return this.path;
+    }
+    /** Append one line (local first, platform best-effort — §4.4). */
+    write(event) {
+        const line = { ts: event.ts ?? this.now(), ...event };
+        this.append(line);
+        this.deliver(line);
+    }
+    append(line) {
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            this.rotate();
+            appendFileSync(this.path, `${JSON.stringify(line)}\n`, { mode: 0o600 });
+            chmodSync(this.path, 0o600);
+        }
+        catch (e) {
+            this.errors.push(messageOf(e));
+        }
+    }
+    /** 16 MiB ceiling: the previous chain becomes `<path>.1` (replaced). */
+    rotate() {
+        try {
+            if (statSync(this.path).size < RECOVERY_AUDIT_MAX_BYTES)
+                return;
+            renameSync(this.path, `${this.path}.1`);
+        }
+        catch {
+            // No file yet (first write) or an unreadable one: nothing to rotate.
+        }
+    }
+    /** Best-effort platform channel; its own failure is recorded locally. */
+    deliver(line) {
+        const url = this.env[ENV_AUDIT_URL];
+        if (url === undefined || url.trim() === "")
+            return;
+        const token = this.env[ENV_CENTER_TOKEN] ?? "";
+        const body = JSON.stringify({ category: "audit", summary: `[recovery] ${line.event}`, detail: line });
+        void this.post(url, body, { "content-type": "application/json", "x-center-token": token }).catch((e) => {
+            this.errors.push(`platform audit failed: ${messageOf(e)}`);
+        });
+    }
+}
+async function defaultPost(url, body, headers) {
+    const response = await fetch(url, { method: "POST", body, headers });
+    return { ok: response.ok, status: response.status };
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/runtime/recovery-view.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `GET /api/status.recovery` (E §1.3 P1 ②) — the LIVE view of one session's
+ * checkpoint, appended to an existing endpoint (P1 adds no endpoint).
+ *
+ * Every field answers a question the operator could otherwise only answer by
+ * reading two files by hand:
+ *
+ *   - `recovered_turns` — which turns THIS engine had to close after a crash
+ *     (the sidecar's `repaired[]`, the durable record of R1-1);
+ *   - `dangling_turns`  — how many turns the LOG leaves open right now. It is a
+ *     judgement about the log (K4: the log is the truth), so it is counted from
+ *     the events, using the same rule as `analyzeReplay().danglingTurns`;
+ *   - `degraded`        — the log and the disk forked (`writeErrorCount>0`, G1-6);
+ *   - `last_outcome`    — the phase of the LAST `turn_end` in the log, which is
+ *     what "was the previous turn interrupted?" really asks.
+ *
+ * Nothing here composes an instance: a session with no live generation reports
+ * the empty block (zeros, no turns) rather than waking an engine for a poll.
+ */
+import { type SessionLog } from "@celestea/core";
+/** The `recovery` block of `/api/status` (a pure addition, always present). */
+export interface RecoveryView {
+    session: string | null;
+    /** Turn ids this engine closed after a crash (`checkpoint.repaired[]`). */
+    recovered_turns: string[];
+    /** `turn_start` rows without a `turn_end` right now. */
+    dangling_turns: number;
+    /** True when the session log has refused a write (disk ≠ memory). */
+    degraded: boolean;
+    /** Phase of the log's last `turn_end` (null = the log has no closed turn). */
+    last_outcome: string | null;
+}
+/** The empty block: no live instance, no checkpoint, no log. */
+export declare function emptyRecoveryView(session: string | null): RecoveryView;
+/** Build the block from the session's LIVE log (a checkpointed one, normally). */
+export declare function recoveryViewOf(log: SessionLog | null | undefined, session: string | null): RecoveryView;

package/dist/runtime/recovery-view.js

@@ -0,0 +1,63 @@
+/**
+ * `GET /api/status.recovery` (E §1.3 P1 ②) — the LIVE view of one session's
+ * checkpoint, appended to an existing endpoint (P1 adds no endpoint).
+ *
+ * Every field answers a question the operator could otherwise only answer by
+ * reading two files by hand:
+ *
+ *   - `recovered_turns` — which turns THIS engine had to close after a crash
+ *     (the sidecar's `repaired[]`, the durable record of R1-1);
+ *   - `dangling_turns`  — how many turns the LOG leaves open right now. It is a
+ *     judgement about the log (K4: the log is the truth), so it is counted from
+ *     the events, using the same rule as `analyzeReplay().danglingTurns`;
+ *   - `degraded`        — the log and the disk forked (`writeErrorCount>0`, G1-6);
+ *   - `last_outcome`    — the phase of the LAST `turn_end` in the log, which is
+ *     what "was the previous turn interrupted?" really asks.
+ *
+ * Nothing here composes an instance: a session with no live generation reports
+ * the empty block (zeros, no turns) rather than waking an engine for a poll.
+ */
+import { outcomePhase } from "@celestea/core";
+import { checkpointStoreOf, writeErrorCountOf } from "@celestea/session";
+/** The empty block: no live instance, no checkpoint, no log. */
+export function emptyRecoveryView(session) {
+    return { session, recovered_turns: [], dangling_turns: 0, degraded: false, last_outcome: null };
+}
+/** Build the block from the session's LIVE log (a checkpointed one, normally). */
+export function recoveryViewOf(log, session) {
+    if (log === null || log === undefined)
+        return emptyRecoveryView(session);
+    const events = log.events();
+    const store = checkpointStoreOf(log);
+    const checkpoint = store?.load() ?? null;
+    const repaired = checkpoint !== null && checkpoint.kind === "ok" ? checkpoint.value.repaired : [];
+    return {
+        session,
+        recovered_turns: repaired.map((r) => r.turn_id),
+        dangling_turns: danglingOf(events),
+        // The LIVE counter wins over the sampled one: it is the same number the log
+        // itself reports right now, and a sticky `>0` in the sidecar keeps a past
+        // fork visible even after a healthy restart (which is intended).
+        degraded: writeErrorCountOf(log) > 0 || (checkpoint !== null && checkpoint.kind === "ok" && checkpoint.value.degraded.log_write_errors > 0),
+        last_outcome: lastOutcomeOf(events),
+    };
+}
+/** `turn_start` minus `turn_end` — the rule of `analyzeReplay().danglingTurns`. */
+function danglingOf(events) {
+    let open = 0;
+    for (const event of events) {
+        if (event.type === "turn_start")
+            open += 1;
+        else if (event.type === "turn_end")
+            open -= 1;
+    }
+    return Math.max(0, open);
+}
+function lastOutcomeOf(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event !== undefined && event.type === "turn_end")
+            return outcomePhase(event.outcome);
+    }
+    return null;
+}

package/dist/runtime/session-compose.d.ts

@@ -0,0 +1,235 @@
+/**
+ * SessionComposer — `compose()` for ONE session (W513).
+ *
+ * Every session runtime is one self-consistent generation: its own profile
+ * snapshot (base profile + the session's `session.json` model override), its own
+ * session binding (`<dir>/cli-main.jsonl` or an in-memory log when detached),
+ * its own usage tracker, its own agent loop instance and its own worker
+ * registry. Nothing is shared but the process (and the LLM seam factory), which
+ * is exactly what makes two sessions unable to see each other's history.
+ *
+ * The module also owns the resource caps and the two error channels the host
+ * maps onto HTTP 503, so the adapter itself stays about the HTTP contract.
+ */
+import { type Llm, type PendingInjection, type Sandbox, type Tool, type ToolGuard } from "@celestea/core";
+import { type SessionInbox } from "@celestea/runtime";
+import { type UsageLedgerFile } from "@celestea/runtime";
+import { type Profile, type Runtime, type Summarizer, type WatchdogMountSettings } from "@celestea/runtime";
+import { type CheckpointWiring, type SessionTarget } from "./engine-session.js";
+import { type DisclosureOptions } from "./engine-plugins.js";
+import type { PendingQuestion, QuestionRegistry } from "../question-registry.js";
+import type { FallbackWiring } from "./fallback-host.js";
+import type { RecoveryAuditWriter } from "./recovery-audit.js";
+import type { SessionGrantsReader } from "./session-grants.js";
+import { type ImageDowngradeInfo } from "@celestea/llm";
+/** W510 resource caps (overridable through the adapter options or the env). */
+export declare const MAX_LIVE_SESSIONS = 4;
+export declare const MAX_CONCURRENT_TURNS = 2;
+export declare const SESSION_IDLE_TTL_MS: number;
+/**
+ * Per-session injection wiring the host supplies (placement over SSE, W515 §2).
+ * The HOST builds it in `session-publisher.ts`; the fields are optional here
+ * because a session with no observers gets a plain inbox and no callback.
+ */
+export interface SessionInjectionHooks {
+    /** The session's inbox (default: a plain one with no observers). */
+    inbox?: SessionInbox;
+    /** Called when a message LEAVES a lane and becomes model-visible history. */
+    onInjected?: (messages: readonly PendingInjection[], boundary: "turn-start" | "step") => void;
+}
+export interface SessionComposerOptions {
+    env: NodeJS.ProcessEnv;
+    /** Build the injection hooks of one session instance (inbox + observer). */
+    sessionHooks?: (sessionId: string | null) => SessionInjectionHooks;
+    /** BASE profile (the `/api/config` one); sessions add their model override. */
+    baseProfile: () => Profile;
+    /** Host lookup: `<workspace>/<session>` -> directory (null = detached). */
+    resolveSession?: (id: string) => SessionTarget | null;
+    /** Session-level model override (`session.json`), applied per instance. */
+    sessionModel?: (id: string) => string | null;
+    /**
+     * W729: session-level mode (`session.json.mode`; null = the session never
+     * declared one). Consumed by the worker wiring, so a worker's row/receipt can
+     * record the mode of the session that spawned it (§2.3).
+     */
+    sessionMode?: (id: string) => string | null;
+    /**
+     * W729 (§5.1 #4, R3): the session's OWN system prompt. Without this hook the
+     * process would assemble ONE prompt at startup and every session would share
+     * it — the mode would then only hold for the focused session. `null` = "use
+     * the base profile prompt" (a session with no declared mode, K8).
+     */
+    sessionSystemPrompt?: (id: string) => string | null;
+    /**
+     * E §4 P1 (W785): the model-fallback wiring. `wrap()` returns null while the
+     * capability is off (`CELESTEA_LLM_FALLBACK` unset — the default), so the
+     * pre-P1 path stays byte-for-byte identical (D9); when armed it returns the
+     * decorated seam and the ledger is booked PER ATTEMPT by the decorator
+     * instead of once per call, which is what makes D6's rows possible.
+     */
+    fallback?: FallbackWiring | null;
+    /** LLM seam factory; default = the assembled engine LLM (live provider). */
+    llm?: (profile: Profile) => Llm;
+    /** Extra tools registered after the six builtins. */
+    tools?: readonly Tool[];
+    /**
+     * W806 (P0): dynamic tool disclosure for the composed sessions. Absent = the
+     * static mode baseline (byte-identical face). Present = a reduced initial set
+     * is offered and the rest is revealed one turn at a time. The DETACHED
+     * generation never takes it: it backs `{{tools}}` / `GET /api/tools`, which
+     * must keep announcing the static disclosable universe (S3).
+     */
+    disclosure?: DisclosureOptions;
+    sandbox?: Sandbox;
+    /** Guard override: `undefined` = production guard, `null` = no guard. */
+    guard?: ToolGuard | null;
+    /** Disable worker orchestration wiring entirely. */
+    workers?: false;
+    /**
+     * W740: the liveness watchdog over this session's worker registry. Omitted =
+     * the environment decides (`compose()` reads it); `false` never mounts it.
+     * The sweep timer dies with the instance (the runtime's shutdown hook), so a
+     * reclaimed session leaks nothing.
+     */
+    watchdog?: Partial<WatchdogMountSettings> | false;
+    /** Worker receipt/report directory (default `<cwd>/worker-results`). */
+    resultsDir?: string;
+    /**
+     * E §2.3 P0 ①: the worker table this process writes. `undefined` = derive it
+     * (`CELESTEA_WORKER_REGISTRY`, else `<data dir>/worker-registry.tsv`);
+     * `null` = IN-MEMORY only, which stays a first-class option for tests and
+     * embedded hosts (B6 is about the DEFAULT, not about removing the choice).
+     */
+    workerRegistryPath?: string | null;
+    /** `<data dir>` — the default home of that table (see `worker-table.ts`). */
+    dataDir?: string | null;
+    /** Compact summarizer override (default: the `Llm` seam). */
+    summarize?: (profile: Profile) => Summarizer;
+    /**
+     * Session grants reader (W516 §4.2): read at every compose, so a grant or a
+     * revocation is visible at the session's next turn boundary and never inside
+     * a running turn. Absent = no grants at all (tests, embedded use).
+     */
+    grants?: SessionGrantsReader;
+    /**
+     * W728 §3 P0: the process-shared append-only usage ledger. Absent/null = this
+     * generation books nothing (tests, embedded use); the studio host creates ONE
+     * file per process (`<data dir>/usage-ledger.jsonl`) and every session
+     * instance books its own rows into it.
+     */
+    ledgerFile?: UsageLedgerFile | null;
+    /** Provider row id of the startup target, recorded as the ledger's `provider`. */
+    providerLabel?: string | null;
+    /**
+     * E §1.3 P0 ②: checkpoint sidecar wiring. A persistent session log is always
+     * checkpointed; this only overrides the process identity (`boot_id`/`pid`) and
+     * the clock, which tests pin to keep the written file deterministic.
+     */
+    checkpoint?: CheckpointWiring;
+    /**
+     * W787 (§5.2③): the audit channel of the recovery facts this process observes
+     * (a degraded session log). Absent = no audit line is written.
+     */
+    recoveryAudit?: RecoveryAuditWriter | null;
+    now?: () => number;
+    /**
+     * W783: the process-wide pending-question table. Present = every composed
+     * session offers `ask_user_question`; absent = no session does (tests and
+     * embeddings that have no human answerer).
+     */
+    questionRegistry?: QuestionRegistry | null;
+    /**
+     * W783: publish one parked question as a `question` SSE frame. The composer
+     * supplies it (it knows the session id and can reach the bus); absent = the
+     * frame is not emitted, which no production host wants.
+     */
+    publishQuestion?: (sessionId: string | null, question: PendingQuestion) => void;
+    /**
+     * W804: the configured input_modalities of one model id, or null when the
+     * model is unknown/unconfigured (=> optimistic default: image input allowed).
+     */
+    modelInputModalities?: (modelId: string) => readonly string[] | null;
+    /**
+     * W804 (section 7.6): a model rejected image input and the turn was downgraded
+     * to text + placeholders. The host turns this into the three visible channels
+     * (info block / statusline / audit).
+     */
+    onModelDowngrade?: (sessionId: string | null, info: ImageDowngradeInfo) => void;
+}
+/** Non-negative integer from the environment, else the frozen default. */
+export declare function limitFromEnv(env: NodeJS.ProcessEnv, name: string, fallback: number): number;
+/** Shut one instance down and close its log descriptor (order matters). */
+export declare function disposeRuntime(runtime: Runtime): Promise<void>;
+/** Wrap the registry caps into the ONE error the HTTP layer maps to 503. */
+export declare function capacityErrorOf(e: unknown): unknown;
+export declare class SessionComposer {
+    private readonly opts;
+    private readonly memoryLogs;
+    constructor(opts: SessionComposerOptions);
+    /** Compose one session generation (the registry's build factory). */
+    compose(sessionId: string | null, dir: string | null): Runtime;
+    /**
+     * W783: the user-question wiring of ONE session generation, or null when the
+     * host mounted no table (the tool is then not offered to the model at all).
+     *
+     * The bus is the SESSION's own (`compose()` provides it), filled in by the
+     * plugin body: an answerer chain per generation is what stops a question asked
+     * in one session from being answered into another.
+     */
+    private questionWiring;
+    /**
+     * The session's ledger, or null when the host did not wire one. The session
+     * label is the file's self-description (`<workspace>/<session>`, §3.2.1).
+     *
+     * W878: `compose(sessionId, dir)` already carries the trusted id, so the label
+     * uses it directly and only falls back to `HOST_SESSION_ID` when the id is
+     * null (the detached generation). `dir` is kept in the signature for the
+     * caller but is deliberately no longer a source of the label.
+     */
+    private usageLedger;
+    /**
+     * E §4 P1 (W785): the ONE place a composed generation decides which `Llm` it
+     * runs on. Fallback OFF (or unwired) = the W728 path unchanged (ledger wrapper
+     * around the raw seam). Fallback ON = the decorator, which books one ledger
+     * row per ATTEMPT and hands the switch to the next target.
+     */
+    private engineLlm;
+    /**
+     * W728 §3 P0: wrap the engine `Llm` so every model step books one ledger row
+     * (success, failure and retry alike). The wrapper lives in the composed
+     * Context, so worker-driven calls go through it as well; the summarizer path
+     * is separate (`summarizer()`, a P1 concern).
+     */
+    private stepObservedLlm;
+    /**
+     * Base profile + the session's own `session.json` overrides (model AND, since
+     * W729, the mode-dependent system prompt). This is the ONE place a session's
+     * instance profile is decided, so two sessions in the same process can differ
+     * in prompt without either one seeing the other's.
+     */
+    profileFor(sessionId: string | null): Profile;
+    /** The session's profile overrides; `null` when it declares none. */
+    private sessionOverrides;
+    /** The compact summarizer of the CURRENT base profile. */
+    summarizer(): Summarizer;
+    /**
+     * Worker wiring: ONE registry per session instance (W513, design D7), so a
+     * receipt returns to the session that spawned the worker and `worker:<sid>`
+     * ids stay unique through the session-derived prefix. W787: the table is
+     * PERSISTED by default at `workerRegistryPath()` (`<data dir>/
+     * worker-registry.tsv`; `CELESTEA_WORKER_REGISTRY` overrides). Only an
+     * explicit `tsvPath: null` is an in-memory table, so the default no
+     * longer collides the host with the fleet's shared `/tmp/registry.tsv`.
+     */
+    private workerWiring;
+    /** E §2.3 P0 ①: the configured table path (see `worker-table.ts` for the rules). */
+    private workerRegistryPath;
+    private llmFactory;
+    private bindingTo;
+    /**
+     * E §1.3 P1 ③: a session log that refused a write is reported to the audit
+     * channel (the sidecar already carries the sticky counter, §1.2.2). One line
+     * per session instance — the store fires this at most once.
+     */
+    private noteDegraded;
+}