@celestea/studio 2.7.1

package/dist/runtime/worker-bridge.js

@@ -0,0 +1,156 @@
+/**
+ * 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 { isRecord } from "@celestea/core";
+import { projectMessages } from "@celestea/session";
+import { getExtra, workerAttempt } from "@celestea/workers";
+/**
+ * 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 function workerSessionsOf(registry, hostSessionId) {
+    if (registry === null)
+        return [];
+    return registry.ownEntries().map((entry) => {
+        const sid = getExtra(entry, "sess") ?? "";
+        const meta = sid === "" ? undefined : registry.sessions.get(sid)?.meta;
+        return {
+            id: `worker:${sid === "" ? entry.wid : sid}`,
+            workspace: "engine",
+            kind: "worker",
+            title: meta?.title ?? entry.wid,
+            model: meta?.model ?? getExtra(entry, "model"),
+            // W729 §2.3: the mode recorded at spawn (parent mode unless overridden).
+            mode: meta?.mode ?? getExtra(entry, "mode") ?? "standard",
+            size: registry.sessions.logOf(sid)?.events().length ?? 0,
+            modified: 0,
+            active: false,
+            wid: entry.wid,
+            status: entry.status,
+            state: getExtra(entry, "state") ?? "",
+            host_session: hostSessionId,
+            // E §2.3 P1 ③ (W787): which try this row is and the key of the receipt it
+            // already delivered — the two facts a coordinator needs to tell a
+            // re-dispatch from a duplicate.
+            attempt: workerAttempt(entry),
+            last_receipt: getExtra(entry, "receipt"),
+        };
+    });
+}
+/** Process-wide `worker_status` fold over the merged rows (W513). */
+export function aggregateWorkerStatus(rows, wid) {
+    const scoped = wid === undefined ? [...rows] : rows.filter((row) => row.wid === wid);
+    const by_status = {};
+    const by_state = {};
+    for (const row of scoped) {
+        const status = row.status ?? "RUNNING";
+        const state = row.state ?? "idle";
+        by_status[status] = (by_status[status] ?? 0) + 1;
+        by_state[state] = (by_state[state] ?? 0) + 1;
+    }
+    if (wid !== undefined && scoped.length === 0) {
+        return { ok: false, total: 0, by_status, by_state, workers: [], wid, error: `no worker ${wid} in registry` };
+    }
+    return { ok: scoped.length > 0, total: scoped.length, by_status, by_state, workers: scoped, ...(wid === undefined ? {} : { wid }) };
+}
+/** Merged worker rows over every live instance (W513 aggregate view). */
+export function mergedWorkerRows(entries) {
+    const rows = [];
+    for (const entry of entries) {
+        for (const row of workerSessionsOf(entry.runtime.workers, entry.runtime.hostSessionId)) {
+            rows.push({ ...row, host_session: entry.sessionId, busy: entry.inFlight });
+        }
+    }
+    return rows;
+}
+/** The messages of one worker session, from whichever live instance owns it. */
+export function workerMessagesAcross(entries, sessionId) {
+    for (const entry of entries) {
+        const found = workerMessagesOf(entry.runtime.workers, sessionId);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+/** `POST /api/worker/spawn`: the spawn tool, dispatched through the session's own registry. */
+export async function spawnWorkerThrough(entry, req, callId) {
+    const args = { wid: req.wid, brief: req.brief };
+    for (const key of ["title", "model"]) {
+        const value = req[key];
+        if (value !== undefined)
+            args[key] = value;
+    }
+    // W513: an unaddressed worker reports back to the session that spawned it.
+    args["report_to"] = req.report_to ?? entry.runtime.hostSessionId ?? "";
+    return spawnOutcomeOf(await dispatchWorkerTool(entry.runtime.tools, "spawn_worker", args, callId));
+}
+/**
+ * `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 async function sendWorkerThrough(entries, req, callId) {
+    let last = null;
+    for (const entry of entries) {
+        const body = sendBodyOf(await dispatchWorkerTool(entry.runtime.tools, "send_message", { target: req.target, content: req.content }, callId()));
+        if (body["ok"] === true)
+            return body;
+        last = body;
+    }
+    return last ?? { ok: false, delivered: false, error: "worker registry is not wired" };
+}
+export function workerMessagesOf(registry, sessionId) {
+    const sid = sessionId.startsWith("worker:") ? sessionId.slice("worker:".length) : sessionId;
+    const log = registry?.sessions.logOf(sid);
+    return log === undefined ? null : projectMessages(log.events());
+}
+/** Dispatch one worker tool through the composed registry. */
+export async function dispatchWorkerTool(registry, name, args, callId) {
+    if (registry === null)
+        return null;
+    const out = await registry.dispatch({ call_id: callId, name, args });
+    return isRecord(out.value) ? out.value : null;
+}
+/** `spawn_worker` value envelope -> the HTTP outcome (`{ok, sessionId, title, wid}`). */
+export function spawnOutcomeOf(value) {
+    if (value === null)
+        return { ok: false, error: "worker registry is not wired" };
+    if (value["ok"] !== true)
+        return { ok: false, error: String(value["error"] ?? "worker spawn failed"), value };
+    return { ok: true, sessionId: String(value["sessionId"]), title: String(value["title"]), wid: String(value["wid"]) };
+}
+/** `send_message` value envelope -> the response body (verbatim). */
+export function sendBodyOf(value) {
+    return value ?? { ok: false, delivered: false, error: "worker registry is not wired" };
+}
+/** `worker_status` tool/registry payload -> the frozen HTTP shape. */
+export function toStatusReport(raw, wid) {
+    if (raw === null || raw["ok"] !== true) {
+        const error = raw === null ? "worker registry is not wired" : String(raw["error"] ?? "");
+        return { ok: false, total: 0, by_status: {}, by_state: {}, workers: [], ...(wid === undefined ? {} : { wid }), error };
+    }
+    const byStatus = (raw["by_status"] ?? {});
+    const byState = (raw["by_state"] ?? {});
+    if (wid === undefined) {
+        return { ok: true, total: Number(raw["total"] ?? 0), by_status: byStatus, by_state: byState, workers: (raw["workers"] ?? []) };
+    }
+    const workers = raw["worker"] === undefined ? [] : [raw["worker"]];
+    return { ok: true, total: workers.length, by_status: byStatus, by_state: byState, workers, wid };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * "Does this session instance still hold LIVE worker work?" (W742 §1 / §2.2.4).
+ *
+ * Extracted from `real-runtime-adapter.ts` verbatim: the predicate is about the
+ * WORKER table, not about the adapter, and keeping it beside the other worker
+ * views is what keeps the adapter inside the §4.1 file budget.
+ *
+ * Two things count as live (and only these):
+ *   - a RUNNING row — the brief has no terminal verdict yet (W736 freezes a row
+ *     exactly once, so RUNNING really does mean "not delivered");
+ *   - a worker session with an OPEN turn — a follow-up message being answered;
+ *     by then the row is already settled, so the log is the only witness.
+ * A parked, settled worker is addressable but idle: it must NOT keep its
+ * session's generation frozen, or a config change would never land there.
+ */
+import { type WorkerRegistry } from "@celestea/workers";
+export interface LiveWorkerHost {
+    runtime: {
+        workers: WorkerRegistry | null;
+    };
+}
+export declare function hasLiveWorkersOf(entry: LiveWorkerHost): boolean;

package/dist/runtime/worker-live.js

@@ -0,0 +1,25 @@
+/**
+ * "Does this session instance still hold LIVE worker work?" (W742 §1 / §2.2.4).
+ *
+ * Extracted from `real-runtime-adapter.ts` verbatim: the predicate is about the
+ * WORKER table, not about the adapter, and keeping it beside the other worker
+ * views is what keeps the adapter inside the §4.1 file budget.
+ *
+ * Two things count as live (and only these):
+ *   - a RUNNING row — the brief has no terminal verdict yet (W736 freezes a row
+ *     exactly once, so RUNNING really does mean "not delivered");
+ *   - a worker session with an OPEN turn — a follow-up message being answered;
+ *     by then the row is already settled, so the log is the only witness.
+ * A parked, settled worker is addressable but idle: it must NOT keep its
+ * session's generation frozen, or a config change would never land there.
+ */
+import { getExtra, hasInProgressTurn } from "@celestea/workers";
+export function hasLiveWorkersOf(entry) {
+    const workers = entry.runtime.workers;
+    return workers !== null && workers.ownEntries().some((row) => row.status === "RUNNING" || openTurnOf(workers, row));
+}
+/** W742 §1: is a turn OPEN on this worker's own session log? (W736's rule.) */
+function openTurnOf(workers, row) {
+    const log = workers.sessions.logOf(getExtra(row, "sess") ?? "");
+    return log !== undefined && hasInProgressTurn(log.events());
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Boot observation of the studio's own worker table (E §2.3 P0 ③).
+ *
+ * The startup sequence is: read the table this studio wrote in an earlier life →
+ * judge every row (dead owner? missing host session?) → write ONE audit line per
+ * finding plus one summary line → report on stderr.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: re-dispatch, settle, or rewrite a row. That
+ * is the whole P0/P2 split — acting on a stale row before the tool
+ * side-effect table exists turns "crash recovery" into a side-effect amplifier
+ * (§5.1), and the DSH-side plugin is already the owner of liveness actions for
+ * its own fleet. P0 only makes the situation VISIBLE, in three places:
+ *
+ *   1. `<data dir>/recovery-audit.jsonl` (the durable record);
+ *   2. `GET /api/worker/status` → `stale[]` / `orphans[]` (the live view);
+ *   3. `[celestea-worker-recovery]` on stderr (the operator's log).
+ */
+import type { WorkerRecoveryReport } from "@celestea/workers";
+import type { RecoveryAuditWriter } from "./recovery-audit.js";
+export interface WorkerBootObservationInput {
+    /** The configured table path (null = in-memory: nothing to observe). */
+    path: string | null;
+    /** Does the host session that dispatched a worker still exist? */
+    knownHost?: (sid: string) => boolean;
+    /** Results dir of the deliverable probe. */
+    resultsDir: string;
+    audit?: RecoveryAuditWriter | null;
+    now?: () => number;
+    warn?: (message: string) => void;
+}
+/**
+ * Observe the table once, at boot. Never throws: an unreadable table is reported
+ * and treated as empty (a damaged file must not stop the studio from starting).
+ */
+export declare function observeWorkerTableOnBoot(input: WorkerBootObservationInput): WorkerRecoveryReport;

package/dist/runtime/worker-recovery.js

@@ -0,0 +1,64 @@
+/**
+ * Boot observation of the studio's own worker table (E §2.3 P0 ③).
+ *
+ * The startup sequence is: read the table this studio wrote in an earlier life →
+ * judge every row (dead owner? missing host session?) → write ONE audit line per
+ * finding plus one summary line → report on stderr.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: re-dispatch, settle, or rewrite a row. That
+ * is the whole P0/P2 split — acting on a stale row before the tool
+ * side-effect table exists turns "crash recovery" into a side-effect amplifier
+ * (§5.1), and the DSH-side plugin is already the owner of liveness actions for
+ * its own fleet. P0 only makes the situation VISIBLE, in three places:
+ *
+ *   1. `<data dir>/recovery-audit.jsonl` (the durable record);
+ *   2. `GET /api/worker/status` → `stale[]` / `orphans[]` (the live view);
+ *   3. `[celestea-worker-recovery]` on stderr (the operator's log).
+ */
+import { workerRecoveryBlock } from "./worker-table.js";
+/**
+ * Observe the table once, at boot. Never throws: an unreadable table is reported
+ * and treated as empty (a damaged file must not stop the studio from starting).
+ */
+export function observeWorkerTableOnBoot(input) {
+    const report = workerRecoveryBlock({
+        path: input.path,
+        ...(input.knownHost === undefined ? {} : { knownHost: input.knownHost }),
+        resultsDir: input.resultsDir,
+        ...(input.now === undefined ? {} : { now: input.now }),
+    });
+    for (const row of report.stale)
+        auditRow(input, row, "worker_stale");
+    for (const row of report.orphans)
+        auditRow(input, row, "worker_orphan");
+    input.audit?.write({
+        event: "worker_observed",
+        session: null,
+        count: report.stale.length + report.orphans.length,
+        detail: `table=${input.path ?? "<memory>"} rows=${report.frozen.length + report.live.length + report.stale.length} live=${report.live.length} frozen=${report.frozen.length}`,
+    });
+    announce(input, report);
+    return report;
+}
+/** One audit line per finding — the row's identity, never its brief (§4.4). */
+function auditRow(input, row, event) {
+    input.audit?.write({
+        event,
+        session: row.host_session,
+        wid: row.wid,
+        attempt: row.attempt,
+        host_session: row.host_session,
+        reason: row.reason,
+        action: row.action,
+        count: row.retries,
+        detail: `lease=${row.lease_pid === null ? "none" : `${row.lease_pid}@${row.lease_at ?? 0}`} artifact=${row.artifact ? "yes" : "no"}`,
+    });
+}
+/** The stderr summary: one line, and only when there is something to say. */
+function announce(input, report) {
+    const warn = input.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    if (report.stale.length === 0 && report.orphans.length === 0)
+        return;
+    const names = (rows) => rows.map((r) => `${r.wid}(${r.reason}${r.artifact ? ",artifact" : ""})`).join(", ");
+    warn(`[celestea-worker-recovery] observed only, no re-dispatch: stale=[${names(report.stale)}] orphans=[${names(report.orphans)}]`);
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The studio's worker TABLE path and its boot-observation view (E §2.2.1/§2.2.4).
+ *
+ * Two host decisions live here, both about the same file:
+ *
+ *   1. WHERE the table is. §2.2.1: the studio and the DSH-side plugin
+ *      (`celes-worker-spawn`) each own a table and they must NEVER write each
+ *      other's (R2-1, asserted by B6). The studio's default is
+ *      `<data dir>/worker-registry.tsv`, overridable with
+ *      `CELESTEA_WORKER_REGISTRY`; an EMPTY value means "in-memory only"
+ *      (`tsvPath: null`, the test/embedded option that must stay available).
+ *   2. WHAT a persisted row means at boot: `stale[]` / `orphans[]` for
+ *      `GET /api/worker/status`. P0 OBSERVES ONLY — the judgement is the pure
+ *      function in `@celestea/workers` and nothing here settles or re-dispatches.
+ *
+ * Reading is also how the boot observer writes its audit line, so the two share
+ * this module instead of each parsing the file on its own.
+ */
+import type { WorkerEntry } from "@celestea/core";
+import { type WorkerRecoveryReport } from "@celestea/workers";
+/** `CELESTEA_WORKER_REGISTRY` — the table path; empty = in-memory only. */
+export declare const ENV_WORKER_REGISTRY = "CELESTEA_WORKER_REGISTRY";
+/** File name inside `<data dir>` (never the DSH plugin's `workerBase`). */
+export declare const WORKER_REGISTRY_FILE = "worker-registry.tsv";
+export interface WorkerTablePathInput {
+    env: NodeJS.ProcessEnv;
+    /** `<data dir>` — where workspaces.json / the ledger live. */
+    dataDir?: string | null;
+    /** `<data dir>/worker-results`; its parent is the data dir when unset. */
+    resultsDir?: string | null;
+    /** Explicit option wins (`null` = in-memory); `undefined` = derive it. */
+    override?: string | null;
+}
+/**
+ * The configured table path, or null for an in-memory table. Precedence:
+ * explicit option > `CELESTEA_WORKER_REGISTRY` > `<data dir>/worker-registry.tsv`.
+ */
+export declare function workerTablePath(input: WorkerTablePathInput): string | null;
+/** Parse one table; a missing or unreadable file is an EMPTY table, never a throw. */
+export declare function readWorkerTable(path: string | null): {
+    entries: WorkerEntry[];
+    error: string | null;
+};
+export interface WorkerRecoveryBlockInput {
+    /** The table path (null = in-memory: there is nothing to observe). */
+    path: string | null;
+    /** Does the host session that dispatched a worker still exist? */
+    knownHost?: (sid: string) => boolean;
+    /** Results dir of the deliverable probe (`results/<wid>*.md`). */
+    resultsDir: string;
+    now?: () => number;
+}
+/**
+ * Judge the table for the status view. `stale`/`orphans` are PURE ADDITIONS to
+ * `/api/worker/status`; a foreign-process row is the NORMAL case here (that is
+ * what a persisted table means), so the view must show it.
+ */
+export declare function workerRecoveryBlock(input: WorkerRecoveryBlockInput): WorkerRecoveryReport;

package/dist/runtime/worker-table.js

@@ -0,0 +1,70 @@
+/**
+ * The studio's worker TABLE path and its boot-observation view (E §2.2.1/§2.2.4).
+ *
+ * Two host decisions live here, both about the same file:
+ *
+ *   1. WHERE the table is. §2.2.1: the studio and the DSH-side plugin
+ *      (`celes-worker-spawn`) each own a table and they must NEVER write each
+ *      other's (R2-1, asserted by B6). The studio's default is
+ *      `<data dir>/worker-registry.tsv`, overridable with
+ *      `CELESTEA_WORKER_REGISTRY`; an EMPTY value means "in-memory only"
+ *      (`tsvPath: null`, the test/embedded option that must stay available).
+ *   2. WHAT a persisted row means at boot: `stale[]` / `orphans[]` for
+ *      `GET /api/worker/status`. P0 OBSERVES ONLY — the judgement is the pure
+ *      function in `@celestea/workers` and nothing here settles or re-dispatches.
+ *
+ * Reading is also how the boot observer writes its audit line, so the two share
+ * this module instead of each parsing the file on its own.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { hasDeliverable, observeWorkerTable, parseRegistryTsv } from "@celestea/workers";
+/** `CELESTEA_WORKER_REGISTRY` — the table path; empty = in-memory only. */
+export const ENV_WORKER_REGISTRY = "CELESTEA_WORKER_REGISTRY";
+/** File name inside `<data dir>` (never the DSH plugin's `workerBase`). */
+export const WORKER_REGISTRY_FILE = "worker-registry.tsv";
+/**
+ * The configured table path, or null for an in-memory table. Precedence:
+ * explicit option > `CELESTEA_WORKER_REGISTRY` > `<data dir>/worker-registry.tsv`.
+ */
+export function workerTablePath(input) {
+    if (input.override !== undefined)
+        return input.override === null ? null : resolve(input.override);
+    const raw = input.env[ENV_WORKER_REGISTRY];
+    if (raw !== undefined)
+        return raw.trim() === "" ? null : resolve(raw);
+    const dir = input.dataDir ?? (input.resultsDir == null ? null : resolve(input.resultsDir, ".."));
+    if (dir === null || dir === "")
+        return null;
+    return join(isAbsolute(dir) ? dir : resolve(dir), WORKER_REGISTRY_FILE);
+}
+/** Parse one table; a missing or unreadable file is an EMPTY table, never a throw. */
+export function readWorkerTable(path) {
+    if (path === null)
+        return { entries: [], error: null };
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        // ENOENT is the normal state before the first spawn (no file yet).
+        return { entries: [], error: e.code === "ENOENT" ? null : messageOf(e) };
+    }
+    return { entries: parseRegistryTsv(text).entries, error: null };
+}
+/**
+ * Judge the table for the status view. `stale`/`orphans` are PURE ADDITIONS to
+ * `/api/worker/status`; a foreign-process row is the NORMAL case here (that is
+ * what a persisted table means), so the view must show it.
+ */
+export function workerRecoveryBlock(input) {
+    const { entries } = readWorkerTable(input.path);
+    return observeWorkerTable(entries, {
+        ...(input.knownHost === undefined ? {} : { knownHost: input.knownHost }),
+        artifactExists: (entry) => hasDeliverable(input.resultsDir, entry.wid).found,
+        ...(input.now === undefined ? {} : { now: input.now() }),
+    });
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}