@celestea/studio 2.7.1

package/dist/runtime/offline-llm.js

@@ -0,0 +1,132 @@
+/**
+ * The OFFLINE engine LLM — a deterministic, in-process `Llm` seam implementation.
+ *
+ * Purpose: the TS host must be testable and replayable with ZERO network access
+ * (`禁真网`). This adapter answers every `generate()` from a local script, so a
+ * real turn (real `DefaultAgentLoop`, real `ToolRegistry`, real session log)
+ * runs end to end without a provider.
+ *
+ * It is not a stub that fakes the loop: the loop, the tool dispatch, the log and
+ * the SSE frames are the production ones. Only the model is local.
+ *
+ * Two behaviours:
+ *   - a normal turn answers with the next scripted step (text / thinking /
+ *     tool calls / usage), defaulting to a deterministic `echo:` reply;
+ *   - a COMPACTION request (the four-section summarizer prompt) answers with a
+ *     deterministic four-section summary derived from the transcript, so a
+ *     compaction is reproducible byte for byte across runs.
+ *
+ * `deltaMs` interleaves real delays between frames: a test can abort mid-stream
+ * and observe the cooperative cancel path instead of a turn that already
+ * finished.
+ */
+import { createHash } from "node:crypto";
+import { assistantText, } from "@celestea/core";
+import { COMPACT_SYSTEM_PROMPT } from "@celestea/runtime";
+/** Text of the last user message (the echo source / summary input). */
+function lastUserText(req) {
+    for (let i = req.messages.length - 1; i >= 0; i--) {
+        const m = req.messages[i];
+        if (m === undefined || m.role !== "user")
+            continue;
+        // W804: an image-only message still echoes something (never an empty string).
+        return m.content.map((c) => (c.type === "text" ? c.content : c.type === "image" ? `[图片:${c.content.media_type}]` : "")).join("");
+    }
+    return "";
+}
+/** Deterministic usage so `cache_hit_ratio` / `context_usage` are assertable. */
+export function offlineUsage(req, answer) {
+    let chars = req.system?.length ?? 0;
+    for (const m of req.messages) {
+        for (const c of m.content) {
+            // W804: an image block must not estimate as 0 chars (context view accuracy).
+            if (c.type === "text")
+                chars += c.content.length;
+            else if (c.type === "image")
+                chars += 300;
+        }
+    }
+    const prompt = Math.ceil(chars / 4);
+    const completion = Math.max(1, Math.ceil(answer.length / 4));
+    return { prompt_tokens: prompt, completion_tokens: completion, total_tokens: prompt + completion, cache_read: Math.floor(prompt / 2), reasoning_tokens: 0 };
+}
+/** True when the request is the compaction summarizer (not a chat turn). */
+export function isCompactionRequest(req) {
+    return req.system !== null && req.system.includes(COMPACT_SYSTEM_PROMPT.slice(0, 12));
+}
+/** The default offline summary: four sections + a stable digest of the input. */
+export function offlineSummary(transcript) {
+    const digest = createHash("sha256").update(transcript, "utf8").digest("hex").slice(0, 12);
+    const last = transcript.trimEnd().split("\n").slice(-1)[0] ?? "";
+    return [
+        "1) 正在进行的任务：离线确定性摘要（mock LLM），输入摘要见下方 digest。",
+        "2) 已做的决策：结构由 compact 计划固定（摘要轮 + 最近 K 轮），摘要正文由本 mock 生成。",
+        `3) 关键事实与文件改动：transcript ${transcript.length} 字符，digest ${digest}。`,
+        `4) 待办：最近一行记录：${last.slice(0, 200)}`,
+    ].join("\n");
+}
+/** Split text into fixed-size chunks (never splitting a code point). */
+export function chunkText(text, size) {
+    const chars = [...text];
+    const out = [];
+    for (let i = 0; i < chars.length; i += size)
+        out.push(chars.slice(i, i + size).join(""));
+    return out.length === 0 ? [""] : out;
+}
+/** Assistant message of a step (tool calls win over text, like the provider). */
+export function stepMessage(step) {
+    const calls = step.tool_calls ?? [];
+    if (calls.length === 0)
+        return assistantText(step.text ?? "");
+    return { role: "assistant", content: calls.map((c) => ({ type: "tool_call", content: c })), tool_call_id: null };
+}
+/** The frame list of one scripted step (before timing is applied). */
+export function stepFrames(step, req, chunk) {
+    const frames = [];
+    if (step.fail !== undefined)
+        return [{ kind: "failed", kindOf: "generate", message: step.fail }];
+    if (step.interrupted === true)
+        return [{ kind: "interrupted" }];
+    const thinking = step.thinking ?? "";
+    if (thinking !== "")
+        for (const piece of chunkText(thinking, chunk))
+            frames.push({ kind: "thinking", text: piece });
+    const text = step.text ?? "";
+    if (text !== "")
+        for (const piece of chunkText(text, chunk))
+            frames.push({ kind: "text", text: piece });
+    frames.push({ kind: "usage", usage: offlineUsage(req, text) });
+    frames.push({ kind: "done", message: stepMessage(step) });
+    return frames;
+}
+/** Yield frames, optionally with a delay between them. */
+async function* emit(frames, delayMs) {
+    for (const frame of frames) {
+        if (delayMs > 0)
+            await new Promise((r) => setTimeout(r, delayMs));
+        yield frame;
+    }
+}
+/** Build the deterministic offline engine LLM. */
+export function createOfflineLlm(opts = {}) {
+    const chunk = Math.max(1, opts.chunkChars ?? 24);
+    const delayMs = Math.max(0, opts.deltaMs ?? 0);
+    const summary = opts.summary ?? offlineSummary;
+    const script = opts.script ?? [];
+    let calls = 0;
+    const stepFor = (req) => {
+        if (isCompactionRequest(req))
+            return { text: summary(lastUserText(req)) };
+        return script.shift() ?? { text: `echo: ${lastUserText(req)}` };
+    };
+    return {
+        get calls() {
+            return calls;
+        },
+        generate(req) {
+            calls += 1;
+            opts.onRequest?.(req);
+            return Promise.resolve(emit(stepFrames(stepFor(req), req, chunk), delayMs));
+        },
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * W747 compat shim — this module moved to the runtime's host layer:
+ * `packages/runtime/src/host/provider-target.ts` (exported as `@celestea/runtime`).
+ *
+ * The rules, the export names and the error text are unchanged; a caller migrates
+ * by deleting its import, not by editing the engine. `ProfileSlot` (the minimal
+ * structural profile slice, added by the move) is deliberately NOT re-exported
+ * here: this path's export surface stays exactly what it was.
+ */
+export { CHAT_COMPLETIONS_FORMAT, applyProviderTarget, listedModelIds, ownerOf, resolveBaseUrl, resolveModel, resolveProviderKey, resolveProviderTarget, type ProviderKeySource as KeySource, type ModelSource, type ProviderLookup, type ProviderRef, type ProviderTarget, } from "@celestea/runtime";

package/dist/runtime/provider-target.js

@@ -0,0 +1,10 @@
+/**
+ * W747 compat shim — this module moved to the runtime's host layer:
+ * `packages/runtime/src/host/provider-target.ts` (exported as `@celestea/runtime`).
+ *
+ * The rules, the export names and the error text are unchanged; a caller migrates
+ * by deleting its import, not by editing the engine. `ProfileSlot` (the minimal
+ * structural profile slice, added by the move) is deliberately NOT re-exported
+ * here: this path's export surface stays exactly what it was.
+ */
+export { CHAT_COMPLETIONS_FORMAT, applyProviderTarget, listedModelIds, ownerOf, resolveBaseUrl, resolveModel, resolveProviderKey, resolveProviderTarget, } from "@celestea/runtime";

package/dist/runtime/question-host.d.ts

@@ -0,0 +1,33 @@
+/**
+ * W783 — the host's user-question capability in ONE object.
+ *
+ * Three things have to exist together and must never drift apart:
+ *   - the process-wide [QuestionRegistry] (so `POST /api/questions/{id}/answer`
+ *     can find a request from its id alone, whichever session asked);
+ *   - the [QuestionView] that publishes a parked question on the session's SSE
+ *     bus and renders the §7 recovery list;
+ *   - the wiring the composer hands to each session generation.
+ *
+ * Bundling them keeps `real-runtime-adapter.ts` — the engine seam, which has a
+ * hard size budget and should stay about the engine — down to a handle and three
+ * one-line delegations. The bus and the turn numbering are reached through
+ * callbacks, so the adapter stays the only thing that knows how to reach them.
+ */
+import type { AskUserQuestionAnswerItem } from "@celestea/core";
+import { type PendingQuestion, type QuestionRegistry } from "../question-registry.js";
+import type { PendingQuestionView, QuestionAnswerOutcome } from "../runtime-adapter.js";
+import { type QuestionPublisher } from "./question-view.js";
+/** The host's question capability: table + view, created once per process. */
+export declare class QuestionHost {
+    private readonly registry;
+    private readonly view;
+    constructor(publisher: QuestionPublisher);
+    /** The table (what the composer wires each session's service to). */
+    table(): QuestionRegistry;
+    /** Publish one parked question (§9 item 9). */
+    publish(sessionId: string | null, question: PendingQuestion): void;
+    /** Answer one pending question (`POST /api/questions/{id}/answer`). */
+    answer(requestId: string, answers: AskUserQuestionAnswerItem[], sessionId?: string): QuestionAnswerOutcome;
+    /** Every question still answerable (`GET /api/questions`, §7 recovery). */
+    list(sessionId?: string | null): PendingQuestionView[];
+}

package/dist/runtime/question-host.js

@@ -0,0 +1,41 @@
+/**
+ * W783 — the host's user-question capability in ONE object.
+ *
+ * Three things have to exist together and must never drift apart:
+ *   - the process-wide [QuestionRegistry] (so `POST /api/questions/{id}/answer`
+ *     can find a request from its id alone, whichever session asked);
+ *   - the [QuestionView] that publishes a parked question on the session's SSE
+ *     bus and renders the §7 recovery list;
+ *   - the wiring the composer hands to each session generation.
+ *
+ * Bundling them keeps `real-runtime-adapter.ts` — the engine seam, which has a
+ * hard size budget and should stay about the engine — down to a handle and three
+ * one-line delegations. The bus and the turn numbering are reached through
+ * callbacks, so the adapter stays the only thing that knows how to reach them.
+ */
+import { createQuestionRegistry } from "../question-registry.js";
+import { QuestionView } from "./question-view.js";
+/** The host's question capability: table + view, created once per process. */
+export class QuestionHost {
+    registry = createQuestionRegistry();
+    view;
+    constructor(publisher) {
+        this.view = new QuestionView(this.registry, publisher);
+    }
+    /** The table (what the composer wires each session's service to). */
+    table() {
+        return this.registry;
+    }
+    /** Publish one parked question (§9 item 9). */
+    publish(sessionId, question) {
+        this.view.publish(sessionId, question);
+    }
+    /** Answer one pending question (`POST /api/questions/{id}/answer`). */
+    answer(requestId, answers, sessionId) {
+        return this.view.answer(requestId, answers, sessionId);
+    }
+    /** Every question still answerable (`GET /api/questions`, §7 recovery). */
+    list(sessionId) {
+        return this.view.list(sessionId);
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * W783 — the host-side view of the pending-question table.
+ *
+ * This module is what the HTTP layer talks to: it publishes parked questions on
+ * the session's SSE bus, resolves them when the human answers, and renders the
+ * §7 recovery list. Keeping it out of `real-runtime-adapter.ts` is not cosmetic —
+ * that file is the engine seam and has a hard size budget; more importantly, none
+ * of this needs the engine, only the table plus a way to reach the bus.
+ *
+ * The one thing it deliberately does NOT do is write the `user_answer` log row:
+ * the session's own service owns that, because it is the single place that
+ * observes EVERY settlement (a real answer and a §6.3 timeout alike).
+ */
+import { type TurnFrame } from "@celestea/runtime";
+import type { AskUserQuestionAnswerItem } from "@celestea/core";
+import type { PendingQuestion, QuestionRegistry } from "../question-registry.js";
+import type { PendingQuestionView, QuestionAnswerOutcome } from "../runtime-adapter.js";
+/** Where a question frame goes and which turn number it belongs to. */
+export interface QuestionPublisher {
+    /** Emit one `question` SSE frame for `sessionId` (null = detached). */
+    emit: (sessionId: string | null, turn: number, frame: TurnFrame) => void;
+    /** The session-local turn number currently running, or 0 when idle. */
+    turnOf: (sessionId: string | null) => number;
+}
+/** The pending-question table as the host sees it. */
+export declare class QuestionView {
+    private readonly registry;
+    private readonly publisher;
+    constructor(registry: QuestionRegistry, publisher: QuestionPublisher);
+    /** Publish one parked question (§9 item 9) — deadline and timeout included. */
+    publish(sessionId: string | null, question: PendingQuestion): void;
+    /**
+     * Answer one pending question (`POST /api/questions/{id}/answer`). Resolving
+     * the parked promise is what wakes the tool call — no message is injected
+     * (§4.2), because a message would only be steering the parked turn cannot drain.
+     *
+     * A refusal is a first-class answer, never a silent success: `unknown` and
+     * `mismatch` are caller errors, while `timed_out`/`settled` report the §6.2
+     * race in whichever direction it actually resolved.
+     */
+    answer(requestId: string, answers: AskUserQuestionAnswerItem[], sessionId?: string): QuestionAnswerOutcome;
+    /**
+     * Every question still answerable, with the deadline judged AT READ TIME
+     * (§6.1) so a reconnecting client rebuilds the card and its countdown without
+     * trusting its own clock.
+     */
+    list(sessionId?: string | null, now?: number): PendingQuestionView[];
+}

package/dist/runtime/question-view.js

@@ -0,0 +1,76 @@
+/**
+ * W783 — the host-side view of the pending-question table.
+ *
+ * This module is what the HTTP layer talks to: it publishes parked questions on
+ * the session's SSE bus, resolves them when the human answers, and renders the
+ * §7 recovery list. Keeping it out of `real-runtime-adapter.ts` is not cosmetic —
+ * that file is the engine seam and has a hard size budget; more importantly, none
+ * of this needs the engine, only the table plus a way to reach the bus.
+ *
+ * The one thing it deliberately does NOT do is write the `user_answer` log row:
+ * the session's own service owns that, because it is the single place that
+ * observes EVERY settlement (a real answer and a §6.3 timeout alike).
+ */
+import { questionFrame } from "@celestea/runtime";
+/** The pending-question table as the host sees it. */
+export class QuestionView {
+    registry;
+    publisher;
+    constructor(registry, publisher) {
+        this.registry = registry;
+        this.publisher = publisher;
+    }
+    /** Publish one parked question (§9 item 9) — deadline and timeout included. */
+    publish(sessionId, question) {
+        const frame = questionFrame({
+            session: sessionId,
+            id: question.requestId,
+            questions: question.questions,
+            expiresAt: question.expiresAt,
+            timeoutMs: question.timeoutMs,
+        });
+        this.publisher.emit(sessionId, this.publisher.turnOf(sessionId), frame);
+    }
+    /**
+     * Answer one pending question (`POST /api/questions/{id}/answer`). Resolving
+     * the parked promise is what wakes the tool call — no message is injected
+     * (§4.2), because a message would only be steering the parked turn cannot drain.
+     *
+     * A refusal is a first-class answer, never a silent success: `unknown` and
+     * `mismatch` are caller errors, while `timed_out`/`settled` report the §6.2
+     * race in whichever direction it actually resolved.
+     */
+    answer(requestId, answers, sessionId) {
+        const question = this.registry.get(requestId);
+        if (question === undefined)
+            return { ok: false, reason: "unknown" };
+        if (sessionId !== undefined && question.sessionId !== sessionId)
+            return { ok: false, reason: "mismatch" };
+        if (question.isSettled) {
+            return { ok: false, reason: question.settlement === "timed_out" ? "timed_out" : "settled" };
+        }
+        const session = question.sessionId;
+        question.answer(answers);
+        this.registry.remove(requestId);
+        return { ok: true, session };
+    }
+    /**
+     * Every question still answerable, with the deadline judged AT READ TIME
+     * (§6.1) so a reconnecting client rebuilds the card and its countdown without
+     * trusting its own clock.
+     */
+    list(sessionId, now = Date.now()) {
+        return this.registry
+            .all()
+            .filter((question) => sessionId === undefined || question.sessionId === sessionId)
+            .map((question) => ({
+            id: question.requestId,
+            session: question.sessionId,
+            questions: question.questions,
+            expires_at: question.expiresAt,
+            timeout_ms: question.timeoutMs,
+            remaining_ms: question.remainingMs(now),
+            expired: question.isExpired(now),
+        }));
+    }
+}

package/dist/runtime/real-runtime-adapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The REAL `RuntimeAdapter` — `packages/runtime` mounted behind the engine seam.
+ *
+ * W513 shape: this class is a HOST over a [SessionRuntimeRegistry], not a single
+ * engine. Every session gets its own composition (own agent loop, own tool
+ * registry, own status/usage trackers, own worker registry, own session log,
+ * own inbox) created lazily on first use, reused while the profile epoch is
+ * current, and reclaimed when idle. There is no "global main session":
+ * `workspaces.json.active_session` is only the view the UI should restore.
+ *
+ * W742 lifecycle (both were documented before but not wired):
+ *   - an epoch bump (POST /api/config, POST /api/providers/default, a grant
+ *     write) NEVER tears down an instance that is still driving workers: the
+ *     registry only marks it and rebuilds it once those workers ended, so a
+ *     model switch can no longer abort a background worker and erase its rows
+ *     (the HTTP 409 guards of both endpoints close the same hole up front);
+ *   - `CELESTEA_SESSION_IDLE_TTL_MS` is real: the registry's unref'ed reclaimer
+ *     sweeps deferrable rebuilds + the idle TTL in the background, and
+ *     `shutdown()` disarms it (no timer outlives the engine).
+ *
+ * Mapping (host HTTP surface -> composition / engine):
+ *   POST /api/turn                  -> `startTurn` (idle) or `inject` (busy);
+ *   GET  /api/events                -> `attach(bus)`, frames carry the session;
+ *   POST /api/sessions/{id}/activate-> `ensureSession` (never 409);
+ *   POST /api/cancel                -> the target session's AbortController;
+ *   POST /api/sessions/batch-delete -> `releaseSession` (W794: abort + drop the
+ *                                      instance before the directory moves);
+ *   POST /api/clear                 -> the target session log's `clear()`;
+ *   POST /api/sessions/{id}/compact -> `runCompaction` + that instance rebuilt;
+ *   GET  /api/status                -> the requested session's statusline;
+ *   GET  /api/tools                 -> the composed `ToolRegistry.schemas()`;
+ *   GET+POST /api/config            -> bump the profile epoch (lazy rebuild);
+ *   worker endpoints                -> per-session registries, merged for reads.
+ *
+ * The per-session turn/state machinery lives in the registry and the composition
+ * in `session-compose.ts`; this file is the seam implementation the handlers see.
+ *
+ * LLM: an injected seam wins (tests / replay inject the OFFLINE deterministic
+ * engine, so no test, no contract check and no replay reaches the network); with
+ * nothing injected each instance is assembled against the profile's provider
+ * (`llm-assembly.ts`), i.e. production is a real model.
+ */
+import type { TurnOutcome } from "@celestea/core";
+import type { Watchdog, WorkerRegistry } from "@celestea/workers";
+import type { EngineProfile, RuntimeAdapter } from "../runtime-adapter.js";
+import { type SessionComposerOptions } from "./session-compose.js";
+export { SESSION_LOG_ID, SESSION_LOG_NAME, type SessionTarget } from "./engine-session.js";
+export { MAX_CONCURRENT_TURNS, MAX_LIVE_SESSIONS, SESSION_IDLE_TTL_MS } from "./session-compose.js";
+export { RELEASE_SETTLE_MS } from "./session-release.js";
+/** Everything the composer needs, plus the resource caps. */
+export interface RealRuntimeAdapterOptions extends Omit<SessionComposerOptions, "env" | "baseProfile"> {
+    /** Startup engine profile (see [defaultEngineProfile]). */
+    profile?: EngineProfile;
+    /** Process environment (provider keys, tool roots, resource caps). */
+    env?: NodeJS.ProcessEnv;
+    /** Live-instance cap (default [MAX_LIVE_SESSIONS] / `CELESTEA_MAX_LIVE_SESSIONS`). */
+    maxLiveSessions?: number;
+    /** Concurrent-turn cap (default [MAX_CONCURRENT_TURNS]). */
+    maxConcurrentTurns?: number;
+    /** Idle TTL for the reclaimer (default [SESSION_IDLE_TTL_MS]). */
+    idleTtlMs?: number;
+    /**
+     * `<data dir>` — where `fallbacks.json` / `fallbacks-audit.jsonl` live, and the
+     * default home of the worker table (`<data dir>/worker-registry.tsv`, §2.2.1).
+     * Defaults to the ledger's directory (all three are process-level data files).
+     */
+    dataDir?: string;
+}
+/** `RuntimeAdapter` + the lifecycle handles the host needs beyond the seam. */
+export interface RealRuntimeAdapter extends RuntimeAdapter {
+    /** Epoch of the current profile generation (bumped by every configure). */
+    generationEpoch(): number;
+    /** Absolute path of the default (detached) session log (null = in memory). */
+    sessionLogPath(): string | null;
+    /** Set the engine system prompt used by the next composed generation. */
+    primeSystemPrompt(prompt: string): void;
+    /** The last terminal turn state over every session (diagnostics / tests). */
+    lastTurnOutcome(): TurnOutcome | null;
+    /**
+     * W740: the liveness watchdog of the session's instance (null when the
+     * watchdog is off). The timer is scheduled by the composition root; this
+     * handle is how the host inspects or hand-ticks it.
+     */
+    watchdog(session?: string | null): Watchdog | null;
+    /** W794: how many auto-wake loops are mounted (diagnostics / tests). */
+    autowakeLoops(): number;
+    /** Is this session's sweep timer running? (no instance = false.) */
+    watchdogRunning(session?: string | null): boolean;
+    /** The session's live worker registry, or null when it has no instance. */
+    workersOf(session?: string | null): WorkerRegistry | null;
+    /** Tear every live instance down (idempotent). */
+    shutdown(): Promise<void>;
+}
+/** Build the real adapter (the host's default engine). */
+export declare function createRealRuntimeAdapter(opts?: RealRuntimeAdapterOptions): RealRuntimeAdapter;