@celestea/studio 2.7.1

package/dist/runtime/session-publisher.js

@@ -0,0 +1,48 @@
+/**
+ * The SSE publishers the host raises on behalf of ONE session (W515 §2/§4).
+ *
+ * Two concerns that look alike and are kept together for that reason:
+ *   - an injected message's placement change (`status` frames: `queued` /
+ *     `steering` on acceptance, `context` when a boundary consumes it);
+ *   - a parked user question (`question`, W783).
+ *
+ * Both are "the adapter knows the session id and the bus; nobody else does", so
+ * both are built from the same two callbacks and neither needs the engine.
+ *
+ * NOTE (pure move, W783): the injection publisher below is W515 behaviour that
+ * used to live inline in `real-runtime-adapter.ts`. Nothing about what it emits
+ * changed — only where it is written down.
+ */
+import { createSessionInbox } from "@celestea/runtime";
+import { inboxMessageOf } from "./inbox-message.js";
+/**
+ * The injection hooks of one session: the ACCEPT side is observed when the inbox
+ * queues a message, and the CONSUME side only through `onInjected`, which knows
+ * WHICH boundary drained it (a mailbox receipt never enters the inbox, so it
+ * cannot be reported here).
+ */
+export function injectionHooksOf(sessionId, deps) {
+    const publish = (placement, message, boundary) => {
+        deps.emitStatus(sessionId, {
+            phase: "progress",
+            placement,
+            ...(boundary === undefined ? {} : { boundary }),
+            message: {
+                id: message.id,
+                kind: message.kind,
+                from: message.from,
+                lane: message.lane,
+                source: message.source,
+                summary: message.source.summary ?? message.text.slice(0, 120),
+            },
+            statusline: {},
+        });
+    };
+    return {
+        inbox: createSessionInbox(deps.now, { onQueued: (message, placement) => publish(placement, message) }),
+        onInjected: (messages, boundary) => {
+            for (const message of messages)
+                publish("context", inboxMessageOf(message), boundary);
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * W794 — releasing the engine generation of a session whose DIRECTORY is going
+ * away (deleted into `<ws>/.celestea-trash/`, or archived).
+ *
+ * Extracted from `real-runtime-adapter.ts` for the same reason
+ * `session-lifecycle.ts` was (W787): the adapter is the HTTP seam and sits on the
+ * §4.1 file budget, while "cut the response in flight, then hand the generation
+ * back" is about a session's lifetime, not about the seam.
+ *
+ * 裁决 background: the active marker is a state label, not a protection, so a
+ * session can be removed while it is streaming an answer. Deleting it must (a)
+ * SUCCEED and (b) leave nothing of it running — no model response mid-flight, no
+ * instance quietly writing into a directory that moved, no auto-wake loop probing
+ * for a generation that can never come back.
+ */
+import type { SessionRuntimeRegistry } from "@celestea/runtime";
+/**
+ * Default budget of the settle wait below. Generous enough for a cooperative
+ * abort of a real step; short enough that a wedged turn cannot hold a delete
+ * request open. `CELESTEA_RELEASE_SETTLE_MS` overrides it.
+ */
+export declare const RELEASE_SETTLE_MS = 1500;
+/** The effective release-settle budget of one process. */
+export declare function releaseSettleMs(env: NodeJS.ProcessEnv): number;
+export interface SessionReleaseDeps {
+    registry: SessionRuntimeRegistry;
+    /** The adapter's cooperative abort — the SAME one `POST /api/cancel` sends. */
+    cancel: (session: string) => boolean;
+    /** W769: unpark the session's auto-wake loop for good. */
+    forget: (session: string) => Promise<void>;
+    /** How long to wait for the aborted turn to settle. */
+    settleMs: number;
+}
+/**
+ * Cut the session's in-flight model response and drop ITS generation.
+ *
+ * Three steps, in this order and for these reasons:
+ *   1. `cancel(session)` — the cooperative abort, because it is the only path
+ *      that unwinds a step cleanly (the loop writes its own `turn_end:
+ *      cancelled`); a removal may not leave a response streaming into a
+ *      directory that is leaving;
+ *   2. wait (bounded by `settleMs`) for that turn to settle, so the log write
+ *      lands and no writer survives when the directory moves;
+ *   3. `registry.release` — detach + dispose THIS instance through the very
+ *      disposer an evict/rebuild uses. The session's next activate/turn composes
+ *      a fresh generation on demand; no other session and no process-wide
+ *      generation is touched.
+ *
+ * `false` = this session had no live instance (an unknown id, or one that was
+ * never used) — nothing to cut, which is what makes the call safe for every id
+ * of a batch. `null` (the detached default generation) is never released.
+ */
+export declare function releaseSessionOf(deps: SessionReleaseDeps, session: string | null): Promise<boolean>;

package/dist/runtime/session-release.js

@@ -0,0 +1,80 @@
+/**
+ * W794 — releasing the engine generation of a session whose DIRECTORY is going
+ * away (deleted into `<ws>/.celestea-trash/`, or archived).
+ *
+ * Extracted from `real-runtime-adapter.ts` for the same reason
+ * `session-lifecycle.ts` was (W787): the adapter is the HTTP seam and sits on the
+ * §4.1 file budget, while "cut the response in flight, then hand the generation
+ * back" is about a session's lifetime, not about the seam.
+ *
+ * 裁决 background: the active marker is a state label, not a protection, so a
+ * session can be removed while it is streaming an answer. Deleting it must (a)
+ * SUCCEED and (b) leave nothing of it running — no model response mid-flight, no
+ * instance quietly writing into a directory that moved, no auto-wake loop probing
+ * for a generation that can never come back.
+ */
+import { limitFromEnv } from "./session-compose.js";
+/**
+ * Default budget of the settle wait below. Generous enough for a cooperative
+ * abort of a real step; short enough that a wedged turn cannot hold a delete
+ * request open. `CELESTEA_RELEASE_SETTLE_MS` overrides it.
+ */
+export const RELEASE_SETTLE_MS = 1_500;
+/** Poll granularity of that wait. */
+const SETTLE_POLL_MS = 5;
+/** The effective release-settle budget of one process. */
+export function releaseSettleMs(env) {
+    return limitFromEnv(env, "CELESTEA_RELEASE_SETTLE_MS", RELEASE_SETTLE_MS);
+}
+/**
+ * Cut the session's in-flight model response and drop ITS generation.
+ *
+ * Three steps, in this order and for these reasons:
+ *   1. `cancel(session)` — the cooperative abort, because it is the only path
+ *      that unwinds a step cleanly (the loop writes its own `turn_end:
+ *      cancelled`); a removal may not leave a response streaming into a
+ *      directory that is leaving;
+ *   2. wait (bounded by `settleMs`) for that turn to settle, so the log write
+ *      lands and no writer survives when the directory moves;
+ *   3. `registry.release` — detach + dispose THIS instance through the very
+ *      disposer an evict/rebuild uses. The session's next activate/turn composes
+ *      a fresh generation on demand; no other session and no process-wide
+ *      generation is touched.
+ *
+ * `false` = this session had no live instance (an unknown id, or one that was
+ * never used) — nothing to cut, which is what makes the call safe for every id
+ * of a batch. `null` (the detached default generation) is never released.
+ */
+export async function releaseSessionOf(deps, session) {
+    if (session === null)
+        return false;
+    const entry = deps.registry.peek(session);
+    if (entry === null) {
+        // W833 (R3 B7 / W816 F2): "no live instance" does NOT mean "no loop". An
+        // idle-evicted session keeps its autowake loop parked against a generation
+        // that can never return; deleting/archiving it must forget the loop here or
+        // it logs "no live generation to bind" and burns a timer forever.
+        await deps.forget(session);
+        return false;
+    }
+    if (entry.inFlight) {
+        deps.cancel(session);
+        await awaitSettled(entry, deps.settleMs);
+    }
+    await deps.forget(session);
+    return deps.registry.release(session);
+}
+/**
+ * Wait — with a REAL clock, whatever `opts.now` says — for an aborted turn to
+ * reach its terminal state. Polling rather than a callback keeps the wait
+ * independent of which teardown path ends the turn (settled turn, failed turn,
+ * the `drive()` tail), which is exactly the set we cannot enumerate from here. A
+ * timeout is not an error: the instance is force-released either way, it only
+ * means the log write may have lost the race.
+ */
+async function awaitSettled(entry, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (entry.inFlight && Date.now() < deadline)
+        await new Promise((r) => setTimeout(r, SETTLE_POLL_MS));
+    return !entry.inFlight;
+}

package/dist/runtime/test-util.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared helpers for the REAL-engine tests.
+ *
+ * Every helper builds a throwaway host: a temp data root, one registered
+ * workspace, and the app wired to the real adapter through `engineFactory`, so
+ * `harness.runtime` IS the engine (`RealRuntimeAdapter`), never a proxy. The
+ * engine's tool roots are pinned to the temp workspace, so the production path
+ * guard stays mounted and read-only tool calls are allowed inside it.
+ *
+ * W743: the engine is built by `createStudioEngine` (app.ts) — the SAME factory
+ * production uses. This file injects only paths/env/profile/LLM and must never
+ * grow a second assembly of its own (see `composition-root.test.ts`).
+ */
+import type { SessionEvent } from "@celestea/core";
+import type { DisclosureOptions } from "./engine-plugins.js";
+import { type StudioHarness } from "../harness.test-util.js";
+import type { BusSubscription } from "../sse.js";
+import type { RealRuntimeAdapter } from "./real-runtime-adapter.js";
+import { type OfflineLlmOptions } from "./offline-llm.js";
+export interface EngineHarnessOptions {
+    /** Sessions to plant: `name` -> events (written as cli-main.jsonl). */
+    sessions?: Record<string, readonly SessionEvent[]>;
+    /** Offline LLM options (script / inter-frame delay) for every generation. */
+    llm?: OfflineLlmOptions;
+    /** `session.json` of the planted sessions (`name` -> its keys, W729). */
+    meta?: Record<string, Record<string, string>>;
+    /**
+     * Environment for the HOST and for the engine this harness builds: the app's
+     * config and the real adapter's own knobs (`CELESTEA_WATCHDOG*`, tool roots,
+     * resource caps) both read it (W740).
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Files planted before the app composes (JSON-encoded; see `makeHarness`). */
+    files?: Record<string, unknown>;
+    /** Files planted VERBATIM (the worker table, a planted sidecar). */
+    rawFiles?: Record<string, string>;
+    /**
+     * W806 (P0): turn dynamic tool disclosure ON for the harness engine (absent =
+     * the static mode baseline every existing test composes).
+     */
+    disclosure?: DisclosureOptions;
+}
+/** One complete turn in the engine's native JSONL shape. */
+export declare function turnEvents(n: number, text?: string): SessionEvent[];
+/** `count` complete turns, one per number. */
+export declare function turns(count: number): SessionEvent[];
+/** Plant a session directory with `cli-main.jsonl` (returns its absolute dir). */
+export declare function plantSession(workspace: string, name: string, events: readonly SessionEvent[], meta?: Record<string, string>): string;
+/** A turn is settled once the adapter reports idle again (+ one macrotask). */
+export declare function waitIdle(h: StudioHarness, timeoutMs?: number): Promise<void>;
+/** The harness's engine adapter (the real one). */
+export declare function engineOf(h: StudioHarness): RealRuntimeAdapter;
+/** One observed SSE frame (event name + envelope). */
+export interface FrameRecord {
+    event: string;
+    turn: number;
+    seq: number;
+    payload: Record<string, unknown>;
+}
+/** Terminal status phases of a turn (the closing frame the host publishes). */
+export declare const TERMINAL_PHASES: readonly string[];
+/** The SSE payload is `unknown` on the wire; the host always sends an object. */
+export declare function asPayload(value: unknown): Record<string, unknown>;
+/** Drain frames until the turn's closing status frame (or fail loudly). */
+export declare function collectUntilTerminal(sub: BusSubscription, frames: FrameRecord[], timeoutMs?: number): Promise<void>;
+export interface TurnResult {
+    status: number;
+    body: Record<string, unknown>;
+    turn: number;
+    frames: FrameRecord[];
+}
+/** POST /api/turn while observing every SSE frame it produces. */
+export declare function runTurnWithFrames(h: StudioHarness, input: string, timeoutMs?: number): Promise<TurnResult>;
+/** Activate a session over the HTTP contract (the engine binds it on the turn). */
+export declare function activate(h: StudioHarness, id: string): Promise<void>;
+/** The session log file of a workspace session. */
+export declare function readSessionLog(h: StudioHarness, name: string): string;
+export declare function makeEngineHarness(opts?: EngineHarnessOptions): StudioHarness;

package/dist/runtime/test-util.js

@@ -0,0 +1,162 @@
+/**
+ * Shared helpers for the REAL-engine tests.
+ *
+ * Every helper builds a throwaway host: a temp data root, one registered
+ * workspace, and the app wired to the real adapter through `engineFactory`, so
+ * `harness.runtime` IS the engine (`RealRuntimeAdapter`), never a proxy. The
+ * engine's tool roots are pinned to the temp workspace, so the production path
+ * guard stays mounted and read-only tool calls are allowed inside it.
+ *
+ * W743: the engine is built by `createStudioEngine` (app.ts) — the SAME factory
+ * production uses. This file injects only paths/env/profile/LLM and must never
+ * grow a second assembly of its own (see `composition-root.test.ts`).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { serializeEventLog } from "@celestea/runtime";
+import { createStudioEngine } from "../app.js";
+import { jsonRequest, makeHarness } from "../harness.test-util.js";
+import { createOfflineLlm } from "./offline-llm.js";
+/** One complete turn in the engine's native JSONL shape. */
+export function turnEvents(n, text = `答 ${n}`) {
+    const id = `turn-${n}`;
+    return [
+        { type: "turn_start", id },
+        { type: "user_message", text: `问 ${n}` },
+        { type: "assistant_message", text },
+        { type: "turn_end", id, outcome: "completed" },
+    ];
+}
+/** `count` complete turns, one per number. */
+export function turns(count) {
+    const out = [];
+    for (let i = 0; i < count; i++)
+        out.push(...turnEvents(i));
+    return out;
+}
+/** Plant a session directory with `cli-main.jsonl` (returns its absolute dir). */
+export function plantSession(workspace, name, events, meta) {
+    const dir = join(workspace, name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "cli-main.jsonl"), serializeEventLog(events));
+    if (meta !== undefined)
+        writeFileSync(join(dir, "session.json"), JSON.stringify(meta));
+    return dir;
+}
+/** A turn is settled once the adapter reports idle again (+ one macrotask). */
+export async function waitIdle(h, timeoutMs = 5_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (h.runtime.isBusy()) {
+        if (Date.now() > deadline)
+            throw new Error("turn did not settle in time");
+        await new Promise((r) => setTimeout(r, 2));
+    }
+    await new Promise((r) => setTimeout(r, 2));
+}
+/** The harness's engine adapter (the real one). */
+export function engineOf(h) {
+    return h.runtime;
+}
+/** Terminal status phases of a turn (the closing frame the host publishes). */
+export const TERMINAL_PHASES = ["completed", "cancelled", "error", "step_limit", "interrupted"];
+function record(frame) {
+    return { event: frame.event, turn: frame.envelope.turn, seq: frame.envelope.seq, payload: asPayload(frame.envelope.payload) };
+}
+/** The SSE payload is `unknown` on the wire; the host always sends an object. */
+export function asPayload(value) {
+    return (value ?? {});
+}
+/** Drain frames until the turn's closing status frame (or fail loudly). */
+export async function collectUntilTerminal(sub, frames, timeoutMs = 5_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const left = deadline - Date.now();
+        if (left <= 0)
+            throw new Error(`turn frames did not terminate (saw ${frames.map((f) => f.event).join(",")})`);
+        const frame = await Promise.race([sub.next(), new Promise((r) => setTimeout(() => r(null), left))]);
+        if (frame === null)
+            throw new Error("no frame before the deadline");
+        frames.push(record(frame));
+        if (frame.event === "status" && TERMINAL_PHASES.includes(String(asPayload(frame.envelope.payload)["phase"])))
+            return;
+    }
+}
+/** POST /api/turn while observing every SSE frame it produces. */
+export async function runTurnWithFrames(h, input, timeoutMs = 5_000) {
+    const sub = h.studio.services.bus.subscribe();
+    const frames = [];
+    const res = await h.app.request("/api/turn", jsonRequest("POST", { input }));
+    const body = (await res.json());
+    const turn = Number(body["turn"] ?? 0);
+    if (res.status === 202)
+        await collectUntilTerminal(sub, frames, timeoutMs);
+    sub.close();
+    await waitIdle(h);
+    return { status: res.status, body, turn, frames };
+}
+/** Activate a session over the HTTP contract (the engine binds it on the turn). */
+export async function activate(h, id) {
+    const res = await h.app.request(`/api/sessions/${encodeURIComponent(id)}/activate`, jsonRequest("POST"));
+    if (res.status !== 200)
+        throw new Error(`activate ${id} failed: ${res.status} ${await res.text()}`);
+}
+/** The session log file of a workspace session. */
+export function readSessionLog(h, name) {
+    return readFileSync(join(h.workspace, name, "cli-main.jsonl"), "utf8");
+}
+/** The startup profile of the OFFLINE engine (no provider registry involved). */
+const OFFLINE_PROFILE = {
+    model: "offline-model",
+    base_url: "http://127.0.0.1:9/v1",
+    api_key_env: "CELESTEA_API_KEY",
+    reasoning_effort: null,
+    max_steps: 4096,
+    max_parallel_tool_calls: 4,
+    max_output_tokens: null,
+    context_window: 1_000_000,
+    system_prompt: "engine identity prompt",
+};
+/**
+ * The injected values of the harness engine (W743).
+ *
+ * W732 A1: this harness used to carry its OWN hand-copied copy of the engine
+ * assembly, and that copy had drifted — it never passed `grants` (so the W516
+ * boundary was composed as "no grants at all") and never passed `ledgerFile`
+ * (so no HTTP-layer test ever saw a usage row). It now injects PATHS/ENV/PROFILE
+ * only and reuses `createStudioEngine` (app.ts), the very function production
+ * runs: one assembly, two call sites.
+ */
+function offlineEngineDeps(opts, host) {
+    return (stores) => {
+        const wsPath = stores.workspaces.workspacePath("sample-ws");
+        const dataRoot = wsPath === undefined ? process.cwd() : dirname(wsPath);
+        return {
+            // The harness data root IS the directory of the workspace just mounted
+            // (`makeHarness` composes cwd = <root>), so the grants audit channel, the
+            // usage ledger and the fail-closed root rules agree with the HTTP layer.
+            workspacesFile: join(dataRoot, "workspaces.json"),
+            // W740: the real adapter reads the watchdog cadence from ITS env, so the
+            // harness env has to travel here as well (not only to the app).
+            env: { ...process.env, ...(wsPath === undefined ? {} : { CELESTEA_TOOL_ROOTS: wsPath }), ...(opts.env ?? {}) },
+            profile: OFFLINE_PROFILE,
+            providerLabel: null,
+            host,
+            llm: () => createOfflineLlm(opts.llm ?? {}),
+            ...(opts.disclosure === undefined ? {} : { disclosure: opts.disclosure }),
+        };
+    };
+}
+export function makeEngineHarness(opts = {}) {
+    // W729: the per-session prompt hook needs the host services, which exist only
+    // AFTER composition — the same late-bound ref `app.ts` uses (see HostRef).
+    const host = { services: null };
+    const h = makeHarness({
+        engineFactory: createStudioEngine(offlineEngineDeps(opts, host)),
+        ...(opts.files === undefined ? {} : { files: opts.files }),
+        ...(opts.rawFiles === undefined ? {} : { rawFiles: opts.rawFiles }),
+    });
+    host.services = h.studio.services;
+    for (const [name, events] of Object.entries(opts.sessions ?? {}))
+        plantSession(h.workspace, name, events, opts.meta?.[name]);
+    return h;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * W740 — the watchdog's read-only face on the host.
+ *
+ * The watchdog itself lives in `packages/workers` (adjudication) and is mounted
+ * by `packages/runtime`'s composition root (cadence + teardown). What is left for
+ * the host is READING it, and this module is that reading, so the adapter stays
+ * about the HTTP contract:
+ *
+ *   - `watchdogOf` / `watchdogRunningOf` — one session's sweep handle;
+ *   - `watchdogCount` — how many live instances sweep (the `worker_status`
+ *     projection's `watchdogs` field);
+ *   - `workerStatusOf` — the `by_status` fold over the merged rows, tagged with
+ *     that count.
+ *
+ * Everything here PEEKS. A session that was never composed is not composed just
+ * to answer a diagnostic: liveness must never be the thing that creates an engine.
+ */
+import type { SessionRuntime, SessionRuntimeRegistry } from "@celestea/runtime";
+import type { Watchdog, WorkerRecoveryReport } from "@celestea/workers";
+import type { WorkerSessionRow, WorkerStatusReport } from "../runtime-adapter.js";
+/** The session's watchdog, or null when it has no instance / the watchdog is off. */
+export declare function watchdogOf(registry: SessionRuntimeRegistry, session?: string | null): Watchdog | null;
+/** Is this session's sweep timer running? */
+export declare function watchdogRunningOf(registry: SessionRuntimeRegistry, session?: string | null): boolean;
+/** Live instances currently sweeping their worker rows. */
+export declare function watchdogCount(entries: readonly SessionRuntime[]): number;
+/**
+ * The process-wide worker status: `by_status` counted from the merged rows (so a
+ * watchdog verdict moves it), the number of live sweepers, and — E §2.3 P0 ③ —
+ * the boot observer's judgement of the PERSISTED table (`stale[]` / `orphans[]`).
+ * The last two are PURE ADDITIONS to the frozen response shape.
+ */
+export declare function workerStatusOf(rows: readonly WorkerSessionRow[], watchdogs: number, wid?: string, recovery?: WorkerRecoveryReport | null): WorkerStatusReport;

package/dist/runtime/watchdog-view.js

@@ -0,0 +1,45 @@
+/**
+ * W740 — the watchdog's read-only face on the host.
+ *
+ * The watchdog itself lives in `packages/workers` (adjudication) and is mounted
+ * by `packages/runtime`'s composition root (cadence + teardown). What is left for
+ * the host is READING it, and this module is that reading, so the adapter stays
+ * about the HTTP contract:
+ *
+ *   - `watchdogOf` / `watchdogRunningOf` — one session's sweep handle;
+ *   - `watchdogCount` — how many live instances sweep (the `worker_status`
+ *     projection's `watchdogs` field);
+ *   - `workerStatusOf` — the `by_status` fold over the merged rows, tagged with
+ *     that count.
+ *
+ * Everything here PEEKS. A session that was never composed is not composed just
+ * to answer a diagnostic: liveness must never be the thing that creates an engine.
+ */
+import { aggregateWorkerStatus } from "./worker-bridge.js";
+/** The session's watchdog, or null when it has no instance / the watchdog is off. */
+export function watchdogOf(registry, session) {
+    return registry.peek(session ?? null)?.runtime.watchdog ?? null;
+}
+/** Is this session's sweep timer running? */
+export function watchdogRunningOf(registry, session) {
+    return watchdogOf(registry, session)?.running ?? false;
+}
+/** Live instances currently sweeping their worker rows. */
+export function watchdogCount(entries) {
+    let running = 0;
+    for (const entry of entries)
+        if (entry.runtime.watchdog?.running === true)
+            running += 1;
+    return running;
+}
+/**
+ * The process-wide worker status: `by_status` counted from the merged rows (so a
+ * watchdog verdict moves it), the number of live sweepers, and — E §2.3 P0 ③ —
+ * the boot observer's judgement of the PERSISTED table (`stale[]` / `orphans[]`).
+ * The last two are PURE ADDITIONS to the frozen response shape.
+ */
+export function workerStatusOf(rows, watchdogs, wid, recovery) {
+    const report = aggregateWorkerStatus(rows, wid);
+    const sweepers = watchdogs === 0 ? report : { ...report, watchdogs };
+    return recovery == null ? sweepers : { ...sweepers, stale: recovery.stale, orphans: recovery.orphans };
+}

package/dist/runtime/worker-bridge.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Worker orchestration bridge: the `POST /api/worker/*` surface is a thin proxy
+ * over the engine's own worker tools (`src/api.rs:437-503`), and the two
+ * `GET` surfaces read the in-process registries directly.
+ *
+ * Keeping the mapping here means the adapter never re-implements orchestration:
+ * `spawn_worker` / `session_send_message` are DISPATCHED through the composed
+ * `ToolRegistry` (so the HTTP surface and the model's tool surface cannot
+ * drift), while `worker_status` reads the same registry summary the tool reads.
+ *
+ * W513: each session runtime owns its own registry, so the rows carry the
+ * owning host session (`host_session`) and the worker id / registry status /
+ * driver state — enough for `GET /api/sessions` to list workers per session and
+ * for the host to aggregate a process-wide `worker_status`.
+ */
+import { type ToolRegistry } from "@celestea/core";
+import { type WorkerRegistry } from "@celestea/workers";
+import type { WorkerSessionRow, WorkerSpawnOutcome, WorkerStatusReport } from "../runtime-adapter.js";
+/**
+ * Engine-memory worker sessions (`worker:<sid>`, pseudo-workspace "engine").
+ *
+ * W740: the row is ENTRY-driven, not conversation-driven. A settled worker gives
+ * up its conversation (W736's receipt path; the watchdog's F2 release), so a
+ * projection that only walked `registry.sessions.metas()` dropped every
+ * DONE/FAILED worker out of the panel the moment it finished — exactly the
+ * opposite of what a status view is for. Each registry row emits a panel row,
+ * enriched with the live conversation while one still exists.
+ */
+export declare function workerSessionsOf(registry: WorkerRegistry | null, hostSessionId: string | null): WorkerSessionRow[];
+/** Process-wide `worker_status` fold over the merged rows (W513). */
+export declare function aggregateWorkerStatus(rows: readonly WorkerSessionRow[], wid?: string): WorkerStatusReport;
+/** Studio projection of a worker session transcript (null = unknown session). */
+/**
+ * W769: the runtime facts these aggregations need about ONE session instance —
+ * structural, so the adapter passes its own `SessionRuntime` rows straight in and
+ * this module never imports the runtime package (it stays a pure view layer).
+ */
+export interface WorkerHostEntry {
+    sessionId: string | null;
+    dir: string | null;
+    inFlight: boolean;
+    runtime: {
+        workers: WorkerRegistry | null;
+        hostSessionId: string | null;
+        tools: ToolRegistry | null;
+    };
+}
+/** Merged worker rows over every live instance (W513 aggregate view). */
+export declare function mergedWorkerRows(entries: readonly WorkerHostEntry[]): WorkerSessionRow[];
+/** The messages of one worker session, from whichever live instance owns it. */
+export declare function workerMessagesAcross(entries: readonly WorkerHostEntry[], sessionId: string): unknown[] | null;
+/** `POST /api/worker/spawn`: the spawn tool, dispatched through the session's own registry. */
+export declare function spawnWorkerThrough(entry: WorkerHostEntry, req: {
+    wid: string;
+    brief: string;
+    title?: string;
+    model?: string;
+    report_to?: string;
+}, callId: string): Promise<WorkerSpawnOutcome>;
+/**
+ * `POST /api/worker/send`: the worker's registry is per session, so the message is
+ * routed to the instance that owns the target — the first one that accepts it wins.
+ */
+export declare function sendWorkerThrough(entries: readonly WorkerHostEntry[], req: {
+    target: string;
+    content: string;
+}, callId: () => string): Promise<Record<string, unknown>>;
+export declare function workerMessagesOf(registry: WorkerRegistry | null, sessionId: string): unknown[] | null;
+/** Dispatch one worker tool through the composed registry. */
+export declare function dispatchWorkerTool(registry: ToolRegistry | null, name: string, args: Record<string, unknown>, callId: string): Promise<Record<string, unknown> | null>;
+/** `spawn_worker` value envelope -> the HTTP outcome (`{ok, sessionId, title, wid}`). */
+export declare function spawnOutcomeOf(value: Record<string, unknown> | null): WorkerSpawnOutcome;
+/** `send_message` value envelope -> the response body (verbatim). */
+export declare function sendBodyOf(value: Record<string, unknown> | null): Record<string, unknown>;
+/** `worker_status` tool/registry payload -> the frozen HTTP shape. */
+export declare function toStatusReport(raw: Record<string, unknown> | null, wid: string | undefined): WorkerStatusReport;