@celestea/runtime 2.7.1

package/dist/watchdog-mount.d.ts

@@ -0,0 +1,79 @@
+/**
+ * W740 — the watchdog at the composition root.
+ *
+ * W736 built the liveness adjudicator (`@celestea/workers` `watchdog.ts`:
+ * keep-running / done / grace-deferred / respawned / failed / probe-error, with
+ * `WorkerRegistry.finalize` as the single terminal write point) but never mounted
+ * it, so nothing swept the RUNNING rows of the engine's own worker registry in
+ * production. This module is that mount — and nothing else:
+ *
+ *   - it resolves the cadence and the retry/grace budgets from the environment
+ *     (`celesteaWatchdogSettings`) with SAFE defaults, so a bad value degrades to
+ *     the default instead of killing startup or hot-looping;
+ *   - it mounts `watchdogPlugin` into the session's Context, which both schedules
+ *     the sweep (interval timer, `unref`ed) and provides `WATCHDOG_SERVICE` for
+ *     tool/host readers;
+ *   - it hands back a stop function, so shutdown/dispose clears the timer (a
+ *     sweep timer must never outlive the generation that owns the registry).
+ *
+ * SCOPE (W740 boundary, mirrors W736): the registry watched here is the STUDIO
+ * ENGINE's per-session, in-process worker registry. It is NOT the DSH plugin's
+ * cross-process `registry.tsv`; no `proc=` liveness rule and no cross-instance
+ * judgement is introduced. The watchdog only ever adjudicates `ownEntries()`.
+ */
+import { type Context } from "@celestea/core";
+import { type Watchdog, type WorkerRegistry } from "@celestea/workers";
+/** Mount name of the watchdog (kept distinct from the workers plugin's name). */
+export declare const WATCHDOG_PLUGIN_NAME = "celestea.runtime.watchdog";
+/** `CELESTEA_WATCHDOG=off` (or `0`/`false`/`no`) disables the mount entirely. */
+export declare const WATCHDOG_ENV = "CELESTEA_WATCHDOG";
+/** `CELESTEA_WATCHDOG_INTERVAL_MS` — sweep period (0 = off). */
+export declare const WATCHDOG_INTERVAL_ENV = "CELESTEA_WATCHDOG_INTERVAL_MS";
+/** `CELESTEA_WATCHDOG_MAX_RETRIES` — re-dispatch ceiling per worker. */
+export declare const WATCHDOG_MAX_RETRIES_ENV = "CELESTEA_WATCHDOG_MAX_RETRIES";
+/** `CELESTEA_WATCHDOG_GRACE_MS` — fresh-spawn grace before an anomaly is judged. */
+export declare const WATCHDOG_GRACE_ENV = "CELESTEA_WATCHDOG_GRACE_MS";
+/** Cadence + budgets + on/off of the mounted watchdog. */
+export interface WatchdogMountSettings {
+    /** Start sweeping at mount time (false = the caller ticks by hand). */
+    autostart: boolean;
+    /** Sweep period in ms (`> 0`; 0 is never produced — it means "off"). */
+    intervalMs: number;
+    maxRetries: number;
+    graceMs: number;
+    /** Append-only verdict log (`null` = the library default: no deployment path). */
+    watcherLog: string | null;
+    alertsLog: string | null;
+}
+/** Defaults: ON, W736's production cadence, library log paths (off). */
+export declare const WATCHDOG_MOUNT_DEFAULTS: WatchdogMountSettings;
+/** `off` / `0` / `false` / `no` (case-insensitive) mean "do not mount". */
+export declare function watchdogDisabled(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Cadence and budgets from the environment. Every input is validated: a
+ * non-numeric, negative or non-positive-period value falls back to the default,
+ * so a typo can neither abort composition nor spin the sweep in a hot loop.
+ */
+export declare function celesteaWatchdogSettings(env: NodeJS.ProcessEnv): WatchdogMountSettings;
+/** What the composition root keeps after mounting the watchdog. */
+export interface MountedWatchdog {
+    /** The adjudicator the plugin provided (the host ticks it by hand in tests). */
+    watchdog: Watchdog;
+    /** Clear the sweep timer (idempotent; shutdown/dispose calls it). */
+    stop: () => void;
+}
+/**
+ * Mount the watchdog over one composed worker registry. Returns null when the
+ * watchdog is switched off — in that case NO service is provided and NO timer
+ * exists, which is what makes "off" observable rather than merely quiet.
+ *
+ * `settings.autostart: false` still mounts (and still provides the token); it
+ * only leaves the cadence to the caller, which is how a test drives `tick()`.
+ */
+export declare function mountWatchdog(ctx: Context, registry: WorkerRegistry, settings?: Partial<WatchdogMountSettings>): MountedWatchdog | null;
+/**
+ * The shutdown hook of a mounted watchdog: clearing the interval is the whole
+ * job, and it is idempotent, so it can be registered as a host teardown hook
+ * without a second bookkeeping path. `null` (watchdog off) is a no-op.
+ */
+export declare function stopWatchdog(mounted: MountedWatchdog | null): () => void;

package/dist/watchdog-mount.js

@@ -0,0 +1,120 @@
+/**
+ * W740 — the watchdog at the composition root.
+ *
+ * W736 built the liveness adjudicator (`@celestea/workers` `watchdog.ts`:
+ * keep-running / done / grace-deferred / respawned / failed / probe-error, with
+ * `WorkerRegistry.finalize` as the single terminal write point) but never mounted
+ * it, so nothing swept the RUNNING rows of the engine's own worker registry in
+ * production. This module is that mount — and nothing else:
+ *
+ *   - it resolves the cadence and the retry/grace budgets from the environment
+ *     (`celesteaWatchdogSettings`) with SAFE defaults, so a bad value degrades to
+ *     the default instead of killing startup or hot-looping;
+ *   - it mounts `watchdogPlugin` into the session's Context, which both schedules
+ *     the sweep (interval timer, `unref`ed) and provides `WATCHDOG_SERVICE` for
+ *     tool/host readers;
+ *   - it hands back a stop function, so shutdown/dispose clears the timer (a
+ *     sweep timer must never outlive the generation that owns the registry).
+ *
+ * SCOPE (W740 boundary, mirrors W736): the registry watched here is the STUDIO
+ * ENGINE's per-session, in-process worker registry. It is NOT the DSH plugin's
+ * cross-process `registry.tsv`; no `proc=` liveness rule and no cross-instance
+ * judgement is introduced. The watchdog only ever adjudicates `ownEntries()`.
+ */
+import { mountPlugins } from "@celestea/core";
+import { WATCHDOG_DEFAULTS, WATCHDOG_SERVICE, watchdogPlugin, } from "@celestea/workers";
+/** Mount name of the watchdog (kept distinct from the workers plugin's name). */
+export const WATCHDOG_PLUGIN_NAME = "celestea.runtime.watchdog";
+/** `CELESTEA_WATCHDOG=off` (or `0`/`false`/`no`) disables the mount entirely. */
+export const WATCHDOG_ENV = "CELESTEA_WATCHDOG";
+/** `CELESTEA_WATCHDOG_INTERVAL_MS` — sweep period (0 = off). */
+export const WATCHDOG_INTERVAL_ENV = "CELESTEA_WATCHDOG_INTERVAL_MS";
+/** `CELESTEA_WATCHDOG_MAX_RETRIES` — re-dispatch ceiling per worker. */
+export const WATCHDOG_MAX_RETRIES_ENV = "CELESTEA_WATCHDOG_MAX_RETRIES";
+/** `CELESTEA_WATCHDOG_GRACE_MS` — fresh-spawn grace before an anomaly is judged. */
+export const WATCHDOG_GRACE_ENV = "CELESTEA_WATCHDOG_GRACE_MS";
+/** Defaults: ON, W736's production cadence, library log paths (off). */
+export const WATCHDOG_MOUNT_DEFAULTS = {
+    autostart: true,
+    intervalMs: WATCHDOG_DEFAULTS.intervalMs,
+    maxRetries: WATCHDOG_DEFAULTS.maxRetries,
+    graceMs: WATCHDOG_DEFAULTS.graceMs,
+    watcherLog: null,
+    alertsLog: null,
+};
+/** `off` / `0` / `false` / `no` (case-insensitive) mean "do not mount". */
+export function watchdogDisabled(env) {
+    const raw = (env[WATCHDOG_ENV] ?? "").trim().toLowerCase();
+    return raw === "off" || raw === "0" || raw === "false" || raw === "no";
+}
+/**
+ * Cadence and budgets from the environment. Every input is validated: a
+ * non-numeric, negative or non-positive-period value falls back to the default,
+ * so a typo can neither abort composition nor spin the sweep in a hot loop.
+ */
+export function celesteaWatchdogSettings(env) {
+    if (watchdogDisabled(env)) {
+        return { ...WATCHDOG_MOUNT_DEFAULTS, autostart: false, intervalMs: 0 };
+    }
+    return {
+        autostart: true,
+        intervalMs: positiveFrom(env, WATCHDOG_INTERVAL_ENV, WATCHDOG_MOUNT_DEFAULTS.intervalMs),
+        maxRetries: countFrom(env, WATCHDOG_MAX_RETRIES_ENV, WATCHDOG_MOUNT_DEFAULTS.maxRetries),
+        graceMs: positiveFrom(env, WATCHDOG_GRACE_ENV, WATCHDOG_MOUNT_DEFAULTS.graceMs),
+        watcherLog: null,
+        alertsLog: null,
+    };
+}
+/**
+ * Mount the watchdog over one composed worker registry. Returns null when the
+ * watchdog is switched off — in that case NO service is provided and NO timer
+ * exists, which is what makes "off" observable rather than merely quiet.
+ *
+ * `settings.autostart: false` still mounts (and still provides the token); it
+ * only leaves the cadence to the caller, which is how a test drives `tick()`.
+ */
+export function mountWatchdog(ctx, registry, settings = {}) {
+    const cfg = { ...WATCHDOG_MOUNT_DEFAULTS, ...settings };
+    // P2-1 (W836): `autostart:false` still mounts (and still provides the token);
+    // only a non-positive period means "off". Returning null here contradicted the
+    // documented contract above and made a manual `tick()` impossible.
+    if (cfg.intervalMs <= 0)
+        return null;
+    const config = {
+        intervalMs: cfg.intervalMs,
+        resultsDir: registry.resultsDir,
+        maxRetries: cfg.maxRetries,
+        graceMs: cfg.graceMs,
+        watcherLog: cfg.watcherLog,
+        alertsLog: cfg.alertsLog,
+    };
+    mountPlugins(ctx, [watchdogPlugin({ registry, config, autostart: cfg.autostart, name: WATCHDOG_PLUGIN_NAME })]);
+    const watchdog = ctx.get(WATCHDOG_SERVICE);
+    if (watchdog === undefined)
+        return null;
+    return { watchdog, stop: () => watchdog.stop() };
+}
+/**
+ * The shutdown hook of a mounted watchdog: clearing the interval is the whole
+ * job, and it is idempotent, so it can be registered as a host teardown hook
+ * without a second bookkeeping path. `null` (watchdog off) is a no-op.
+ */
+export function stopWatchdog(mounted) {
+    return () => mounted?.stop();
+}
+/** Non-negative integer from the env, else the fallback (0 is allowed). */
+function countFrom(env, name, fallback) {
+    const raw = (env[name] ?? "").trim();
+    if (raw === "")
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+/** Strictly positive integer from the env, else the fallback (0 means "off"). */
+function positiveFrom(env, name, fallback) {
+    const raw = (env[name] ?? "").trim();
+    if (raw === "")
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/dist/worker-wiring.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Worker wiring — the part of composition that only `runtime` can do.
+ *
+ * Layer rules say an L1 package never imports another L1 package, so
+ * `packages/workers` cannot reach the `Llm` / `ToolRegistry` / `AgentLoop`
+ * implementations and cannot build a session log with a real projection. The
+ * composition root can: it resolves the three driver seams from the Context and
+ * hands them to the registry (`attach_drivers`, W206/W232), injects the
+ * worker session log factory, registers the HOST conversation so worker
+ * receipts have an address, and returns the drain hook the turn runner uses.
+ *
+ * Nothing here is mandatory: with `workers: false` the generation runs without
+ * orchestration and every hook degrades to a no-op.
+ */
+import { Context } from "@celestea/core";
+import { WorkerRegistry, type SessionLogFactory, type Watchdog, type WorkerDrivers } from "@celestea/workers";
+import type { PendingReceipt } from "./turn-runner.js";
+export interface WorkerWiring {
+    /** `false` disables orchestration wiring entirely (default: enabled). */
+    enabled?: boolean;
+    /** Pre-built registry (the host owns it); otherwise one is created + mounted. */
+    registry?: WorkerRegistry;
+    /**
+     * `null` = in-memory table only. Omitted = `REGISTRY_TSV_PATH` (the legacy
+     * shared `/tmp` table). E §2.3 P0 ①: the studio passes an EXPLICIT path
+     * (`<data dir>/worker-registry.tsv`, env `CELESTEA_WORKER_REGISTRY`) so it can
+     * never write the table of the DSH-side fleet (B6/R2-1).
+     */
+    tsvPath?: string | null;
+    resultsDir?: string;
+    sourceLabel?: string;
+    /** Worker session log factory (default: `InMemorySessionLog`). */
+    logFactory?: SessionLogFactory;
+    /** Host conversation id (default `cli-main`; the host passes the session id). */
+    hostSessionId?: string;
+    /**
+     * Prefix of the worker session ids this registry mints (`session-` by
+     * default). Every session runtime owns its OWN registry since W513, so the
+     * host passes a session-derived prefix: `worker:<sid>` ids stay unique in the
+     * merged `GET /api/sessions` list.
+     */
+    sessionIdPrefix?: string;
+    /** Model token recorded on the host session meta. */
+    hostModel?: string | null;
+    /**
+     * W729 §2.3: the host session's mode, inherited by every spawn that does not
+     * pass one. `null` = the host declared none (the spawn then records none).
+     */
+    hostMode?: string | null;
+}
+export interface WorkerHost {
+    registry: WorkerRegistry;
+    hostSessionId: string;
+    /** Name of the plugin this wiring mounted (null when a host plugin provided it). */
+    mountedPlugin: string | null;
+    /** Poll the host mailbox: the messages to inject at the next boundary. */
+    drain: () => PendingReceipt[];
+    /** Messages waiting in the host mailbox (the loop's close guard reads it). */
+    pending: () => number;
+    /** Attach driver seams so a spawn is driven, not merely registered. */
+    attach: (drivers: WorkerDrivers | null) => boolean;
+    /**
+     * W740: the liveness watchdog mounted over THIS registry by the composition
+     * root (`compose()` attaches it after this wiring ran), or null when the
+     * watchdog is off. The service itself also lives in the Context under
+     * `WATCHDOG_SERVICE`; this handle is what a host ticks by hand.
+     */
+    watchdog?: Watchdog | null;
+}
+/**
+ * Resolve the registry: an already-mounted one wins (a host plugin provided it),
+ * otherwise create and mount the default alone. Returns null when disabled.
+ */
+export declare function ensureWorkerWiring(ctx: Context, wiring: WorkerWiring | false | undefined): WorkerHost | null;

package/dist/worker-wiring.js

@@ -0,0 +1,107 @@
+/**
+ * Worker wiring — the part of composition that only `runtime` can do.
+ *
+ * Layer rules say an L1 package never imports another L1 package, so
+ * `packages/workers` cannot reach the `Llm` / `ToolRegistry` / `AgentLoop`
+ * implementations and cannot build a session log with a real projection. The
+ * composition root can: it resolves the three driver seams from the Context and
+ * hands them to the registry (`attach_drivers`, W206/W232), injects the
+ * worker session log factory, registers the HOST conversation so worker
+ * receipts have an address, and returns the drain hook the turn runner uses.
+ *
+ * Nothing here is mandatory: with `workers: false` the generation runs without
+ * orchestration and every hook degrades to a no-op.
+ */
+import { Context } from "@celestea/core";
+import { InMemorySessionLog } from "@celestea/session";
+import { WorkerRegistry, WORKER_REGISTRY_SERVICE, workersPlugin, } from "@celestea/workers";
+import { mountPlugins } from "@celestea/core";
+import { HOST_SESSION_ID, RESULTS_DIR } from "./tokens.js";
+const DEFAULT_WORKER_PLUGIN = "celestea.runtime.workers";
+/**
+ * Resolve the registry: an already-mounted one wins (a host plugin provided it),
+ * otherwise create and mount the default alone. Returns null when disabled.
+ */
+export function ensureWorkerWiring(ctx, wiring) {
+    if (wiring === false || wiring?.enabled === false)
+        return null;
+    const provided = ctx.get(WORKER_REGISTRY_SERVICE);
+    const hostSessionId = wiring?.hostSessionId ?? HOST_SESSION_ID;
+    const registry = provided ?? mountDefault(ctx, wiring ?? {}, hostSessionId);
+    registerHost(registry, hostSessionId, wiring?.hostModel ?? null, wiring?.hostMode ?? null);
+    return {
+        registry,
+        hostSessionId,
+        mountedPlugin: provided === undefined ? DEFAULT_WORKER_PLUGIN : null,
+        drain: () => drainHost(registry, hostSessionId),
+        pending: () => registry.mailbox.pending(hostSessionId),
+        attach: (drivers) => attachDrivers(registry, drivers),
+    };
+}
+function mountDefault(ctx, wiring, hostSessionId) {
+    const registry = new WorkerRegistry({
+        tsvPath: wiring.tsvPath === undefined ? undefined : wiring.tsvPath,
+        // E §2.2.2 (`host=`): the row records which conversation dispatched it.
+        hostSessionId,
+        resultsDir: wiring.resultsDir ?? RESULTS_DIR,
+        sourceLabel: wiring.sourceLabel ?? "celestea.runtime",
+        logFactory: wiring.logFactory ?? (() => new InMemorySessionLog()),
+        ...(wiring.sessionIdPrefix === undefined ? {} : { sessionIdPrefix: wiring.sessionIdPrefix }),
+        hostMode: wiring.hostMode ?? null,
+    });
+    mountPlugins(ctx, [workersPlugin({ registry, name: DEFAULT_WORKER_PLUGIN })]);
+    return registry;
+}
+/** Register the host conversation so receipts can be addressed to it (W232). */
+function registerHost(registry, hostSessionId, model, mode) {
+    const host = {
+        meta: { id: hostSessionId, title: hostSessionId, workspace: null, model, mode },
+        log: new InMemorySessionLog(),
+    };
+    registry.registerHostSession(host);
+    // The spawn default: a worker inherits the mode of its owning session (W729).
+    registry.setHostMode(mode);
+}
+/**
+ * FIFO drain of the host queue, annotated with the sender label, the envelope
+ * (`source`) and a stable key (W515 §3/§4).
+ *
+ * W840 (R2 N1): the key is NOT a duplicate filter on this path. The drained
+ * messages are concatenated straight into the turn at compose.ts (never pushed
+ * through `SessionInbox.push`), so the inbox B3 rule never sees them; the id only
+ * surfaces in the SSE `context` frame (session-publisher.ts). The single
+ * once-only gate for a receipt is WorkerRegistry.closeLoop's durable
+ * `receipt:<wid>:<attempt>` token (registry.ts, receiptDelivered).
+ */
+function drainHost(registry, hostSessionId) {
+    return registry.mailbox.poll(hostSessionId).map((m) => ({
+        text: m.content,
+        from: m.from_label,
+        id: idempotencyKeyOf(registry, m),
+        kind: m.kind,
+        source: m.source ?? { kind: "worker-relay", form: "message", senderSessionId: m.from_label },
+    }));
+}
+/**
+ * E §2.2.3 (2-P1 ②): the stable key of a drained message.
+ *
+ * A RECEIPT is keyed by `receipt:<wid>:<attempt>` — stable across processes, so
+ * the SSE `context` frame for a replayed receipt carries the same id. W840
+ * (R2 N1): this key does NOT deduplicate on the production injection path — the
+ * drained receipts are appended straight to the turn (compose.ts), bypassing
+ * `SessionInbox.push` and its B3 rule; closeLoop's durable receiptDelivered token
+ * is the only once-only gate. Routing receipts through the inbox (to make B3
+ * apply here) is a semantics change left for adjudication. Every other message
+ * (a deliberate relay, a stimulus) keeps the in-process mailbox sequence: keying
+ * a relay by `(wid, attempt)` would silently drop a SECOND intentional message.
+ */
+function idempotencyKeyOf(registry, message) {
+    const receipt = message.kind === "receipt" ? registry.receiptKeyFor(message.from_label) : null;
+    return receipt ?? `mailbox:${message.id}`;
+}
+function attachDrivers(registry, drivers) {
+    if (drivers === null)
+        return false;
+    registry.attachDrivers(drivers);
+    return true;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@celestea/runtime",
+  "version": "2.7.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@celestea/agent-loop": "2.7.1",
+    "@celestea/core": "2.7.1",
+    "@celestea/session": "2.7.1",
+    "@celestea/workers": "2.7.1"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}