@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/core/sandbox-routes.d.ts

@@ -10,11 +10,16 @@ export type SandboxRouteSession = SessionSandboxRef & {
     readonly activeTurnId: string | null;
     readonly status: string;
 };
+/** A session together with a synchronous lookup over its sandbox owner chain. */
+export type SandboxRouteRead = {
+    readonly session: SandboxRouteSession;
+    readonly lookup: (id: string) => SessionSandboxRef | undefined;
+};
 export type SandboxRouteDeps = {
     readonly sandbox: SandboxManager;
-    readonly session: (id: string) => SandboxRouteSession;
-    readonly lookup: (id: string) => SessionSandboxRef | undefined;
-    readonly getAction: (id: string) => Action | undefined;
+    /** The session (rejects when missing) and its owner chain, read in one transaction. */
+    readonly session: (id: string) => Promise<SandboxRouteRead>;
+    readonly getAction: (id: string) => Promise<Action | undefined>;
 };
 /**
  * `POST /v1/sessions/:id/sandbox/:tool` — application principal.
@@ -32,4 +37,8 @@ export declare function validateSandboxAttach(body: {
     sandbox?: {
         session: string;
     };
-}, newManifest: SessionSandboxRef["manifest"], lookup: (id: string) => SessionSandboxRef | undefined): string | undefined;
+}, newManifest: SessionSandboxRef["manifest"], lookup: (id: string) => SessionSandboxRef | undefined, 
+/** Acting for a subject: another owner's session is the 404 of a missing one. */
+options?: {
+    opaque?: boolean;
+}): string | undefined;

package/dist/core/sandbox-routes.js

@@ -34,9 +34,9 @@ function toolInput(body) {
     const { claimId: _c, generation: _g, requestId: _r, ...input } = record;
     return input;
 }
-async function runTool(deps, session, tool, input, signal) {
-    const spec = resolveSpec(session, deps.lookup);
-    const ownerId = owningSandboxSessionId(session, deps.lookup);
+async function runTool(deps, { session, lookup }, tool, input, signal) {
+    const spec = resolveSpec(session, lookup);
+    const ownerId = owningSandboxSessionId(session, lookup);
     const ref = {
         id: ownerId,
         activeTurnId: session.activeTurnId,
@@ -49,11 +49,11 @@ async function runTool(deps, session, tool, input, signal) {
  * Refused while the session has an active agent turn.
  */
 export async function handleSessionSandboxTool(deps, sessionId, toolName, body, signal) {
-    const session = deps.session(sessionId);
-    if (session.activeTurnId)
+    const read = await deps.session(sessionId);
+    if (read.session.activeTurnId)
         throw new SandboxRouteError(409, "Sandbox is unavailable while the session has an active agent turn");
     const tool = parseTool(toolName);
-    return runTool(deps, session, tool, toolInput(body), signal);
+    return runTool(deps, read, tool, toolInput(body), signal);
 }
 /**
  * `POST /v1/actions/:id/sandbox/:tool` — executor, authorized by the live claim.
@@ -69,7 +69,7 @@ export async function handleActionSandboxTool(deps, actionId, toolName, body, si
         throw new SandboxRouteError(400, "claimId is required");
     if (typeof generation !== "number" || !Number.isInteger(generation) || generation < 1)
         throw new SandboxRouteError(400, "generation must be a positive integer");
-    const action = deps.getAction(actionId);
+    const action = await deps.getAction(actionId);
     if (!action)
         throw new SandboxRouteError(404, "Action not found");
     if (action.status !== "claimed" ||
@@ -78,19 +78,21 @@ export async function handleActionSandboxTool(deps, actionId, toolName, body, si
         !action.leaseExpiresAt ||
         Date.parse(action.leaseExpiresAt) <= Date.now())
         throw new SandboxRouteError(409, "Stale or expired claim");
-    const session = deps.session(action.sessionId);
-    if (session.activeTurnId !== action.turnId)
+    const read = await deps.session(action.sessionId);
+    if (read.session.activeTurnId !== action.turnId)
         throw new SandboxRouteError(409, "Action unavailable");
     const tool = parseTool(toolName);
-    return runTool(deps, session, tool, toolInput(body), signal);
+    return runTool(deps, read, tool, toolInput(body), signal);
 }
 /** Validate PutSession.sandbox attach: same owner, identical specs. */
-export function validateSandboxAttach(body, newManifest, lookup) {
+export function validateSandboxAttach(body, newManifest, lookup, 
+/** Acting for a subject: another owner's session is the 404 of a missing one. */
+options = {}) {
     const share = body.sandbox?.session;
     if (!share)
         return undefined;
     const owner = lookup(share);
-    if (!owner)
+    if (!owner || (options.opaque && owner.ownerUserId !== body.ownerUserId))
         throw new SandboxRouteError(404, "Sandbox session not found");
     if (owner.ownerUserId !== body.ownerUserId)
         throw new SandboxRouteError(403, "Sandbox session must belong to the same owner");

package/dist/execution/memory.d.ts

@@ -0,0 +1,54 @@
+import { type DurableExecution, type Wake, type WorkerHandlers } from "./types.js";
+export interface MemoryExecutionOptions {
+    /** Delay between sweep passes of one Tenant. Default 5000. */
+    sweepIntervalMs?: number;
+    /** First retry delay after `advance` throws; doubles per attempt. Default 50. */
+    retryDelayMs?: number;
+    /** Attempts before giving up on a throwing `advance` and reporting it. Default 5. */
+    maxAttempts?: number;
+    /** How long a dedupe key merges repeated wakes. Default 24 hours. */
+    dedupeRetentionMs?: number;
+    /** Receives handler failures that are not retried. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * In-process `DurableExecution`. Not durable: wakes, timers and sweeps live in
+ * memory. It keeps the seam's ordering guarantees within one process, which is
+ * what unit tests and the Runtime before Restate (Wave 2) need.
+ */
+export declare class MemoryExecution implements DurableExecution {
+    private handlers?;
+    private readonly keys;
+    /** Dedupe keys seen, with the time each was first seen; insertion order is age order. */
+    private readonly seen;
+    private readonly timers;
+    private readonly sweeps;
+    private readonly delayed;
+    private readonly inflight;
+    private readonly sweepIntervalMs;
+    private readonly retryDelayMs;
+    private readonly maxAttempts;
+    private readonly dedupeRetentionMs;
+    private readonly onError;
+    constructor(options?: MemoryExecutionOptions);
+    wake(tenantId: string, sessionId: string, wake: Wake): Promise<void>;
+    timer(tenantId: string, key: string, at: Date): Promise<void>;
+    armSweep(tenantId: string): Promise<void>;
+    disarmSweep(tenantId: string): Promise<void>;
+    start(handlers: WorkerHandlers): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Resolves once no advance is running or queued and no busy or retry
+     * re-wake is pending. Timers and sweeps are not waited for. Test helper.
+     */
+    idle(): Promise<void>;
+    private enqueue;
+    private drain;
+    /** Drops dedupe keys older than the retention window. */
+    private forgetDedupeKeys;
+    private advanceOnce;
+    private armTimer;
+    private scheduleSweep;
+    private later;
+    private track;
+}

package/dist/execution/memory.js

@@ -0,0 +1,217 @@
+import { WAKE_REASONS, sessionKey, } from "./types.js";
+/**
+ * In-process `DurableExecution`. Not durable: wakes, timers and sweeps live in
+ * memory. It keeps the seam's ordering guarantees within one process, which is
+ * what unit tests and the Runtime before Restate (Wave 2) need.
+ */
+export class MemoryExecution {
+    handlers;
+    keys = new Map();
+    /** Dedupe keys seen, with the time each was first seen; insertion order is age order. */
+    seen = new Map();
+    timers = new Map();
+    sweeps = new Map();
+    delayed = new Set();
+    inflight = new Set();
+    sweepIntervalMs;
+    retryDelayMs;
+    maxAttempts;
+    dedupeRetentionMs;
+    onError;
+    constructor(options = {}) {
+        this.sweepIntervalMs = options.sweepIntervalMs ?? 5000;
+        this.retryDelayMs = options.retryDelayMs ?? 50;
+        this.maxAttempts = options.maxAttempts ?? 5;
+        this.dedupeRetentionMs = options.dedupeRetentionMs ?? 24 * 60 * 60_000;
+        this.onError =
+            options.onError ??
+                ((error) => queueMicrotask(() => {
+                    throw error;
+                }));
+    }
+    async wake(tenantId, sessionId, wake) {
+        if (!WAKE_REASONS.includes(wake.reason))
+            throw new Error(`Unknown wake reason: ${String(wake.reason)}`);
+        const key = sessionKey(tenantId, sessionId);
+        if (wake.dedupeKey !== undefined) {
+            const now = Date.now();
+            this.forgetDedupeKeys(now);
+            const dedupe = `${key}\u0000${wake.dedupeKey}`;
+            if (this.seen.has(dedupe))
+                return;
+            this.seen.set(dedupe, now);
+        }
+        this.enqueue(tenantId, sessionId);
+    }
+    async timer(tenantId, key, at) {
+        const id = `${tenantId}\u0000${key}`;
+        const existing = this.timers.get(id);
+        if (existing?.handle)
+            clearTimeout(existing.handle);
+        const timer = { tenantId, key, at: at.getTime() };
+        this.timers.set(id, timer);
+        if (this.handlers)
+            this.armTimer(id, timer);
+    }
+    async armSweep(tenantId) {
+        if (this.sweeps.has(tenantId))
+            return;
+        const sweep = { running: false };
+        this.sweeps.set(tenantId, sweep);
+        if (this.handlers)
+            this.scheduleSweep(tenantId, sweep, 0);
+    }
+    async disarmSweep(tenantId) {
+        const sweep = this.sweeps.get(tenantId);
+        if (sweep?.handle)
+            clearTimeout(sweep.handle);
+        this.sweeps.delete(tenantId);
+    }
+    async start(handlers) {
+        if (this.handlers)
+            throw new Error("DurableExecution already started");
+        this.handlers = handlers;
+        for (const state of this.keys.values())
+            if (state.queued && !state.running)
+                this.drain(state);
+        for (const [id, timer] of this.timers)
+            this.armTimer(id, timer);
+        for (const [tenantId, sweep] of this.sweeps)
+            this.scheduleSweep(tenantId, sweep, 0);
+    }
+    async stop() {
+        this.handlers = undefined;
+        for (const handle of this.delayed)
+            clearTimeout(handle);
+        this.delayed.clear();
+        for (const timer of this.timers.values())
+            if (timer.handle)
+                clearTimeout(timer.handle);
+        for (const sweep of this.sweeps.values())
+            if (sweep.handle)
+                clearTimeout(sweep.handle);
+        for (const state of this.keys.values())
+            state.controller?.abort();
+        while (this.inflight.size > 0)
+            await Promise.allSettled(this.inflight);
+    }
+    /**
+     * Resolves once no advance is running or queued and no busy or retry
+     * re-wake is pending. Timers and sweeps are not waited for. Test helper.
+     */
+    async idle() {
+        while (this.delayed.size > 0 ||
+            this.inflight.size > 0 ||
+            [...this.keys.values()].some((s) => s.running || (s.queued && this.handlers)))
+            await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    enqueue(tenantId, sessionId) {
+        const key = sessionKey(tenantId, sessionId);
+        let state = this.keys.get(key);
+        if (!state)
+            this.keys.set(key, (state = {
+                tenantId,
+                sessionId,
+                running: false,
+                queued: false,
+                attempts: 0,
+            }));
+        state.queued = true;
+        if (!state.running && this.handlers)
+            this.drain(state);
+    }
+    drain(state) {
+        state.running = true;
+        this.track((async () => {
+            try {
+                while (state.queued && this.handlers) {
+                    state.queued = false;
+                    await this.advanceOnce(state, this.handlers);
+                }
+            }
+            finally {
+                state.running = false;
+                // Idle keys hold nothing (a retry keeps its attempt count); forget them so
+                // long-lived processes stay small.
+                const key = sessionKey(state.tenantId, state.sessionId);
+                if (!state.queued && state.attempts === 0 && this.keys.get(key) === state)
+                    this.keys.delete(key);
+            }
+        })());
+    }
+    /** Drops dedupe keys older than the retention window. */
+    forgetDedupeKeys(now) {
+        for (const [dedupe, seenAt] of this.seen) {
+            if (now - seenAt < this.dedupeRetentionMs)
+                break;
+            this.seen.delete(dedupe);
+        }
+    }
+    async advanceOnce(state, handlers) {
+        const controller = new AbortController();
+        state.controller = controller;
+        try {
+            const result = await handlers.advance(state.tenantId, state.sessionId, controller.signal);
+            state.attempts = 0;
+            if (result.status === "busy")
+                this.later(result.retryAfterMs, () => this.enqueue(state.tenantId, state.sessionId));
+        }
+        catch (error) {
+            state.attempts += 1;
+            if (state.attempts >= this.maxAttempts || controller.signal.aborted) {
+                state.attempts = 0;
+                this.onError(error);
+            }
+            else
+                this.later(this.retryDelayMs * 2 ** (state.attempts - 1), () => this.enqueue(state.tenantId, state.sessionId));
+        }
+        finally {
+            state.controller = undefined;
+        }
+    }
+    armTimer(id, timer) {
+        timer.handle = setTimeout(() => {
+            if (this.timers.get(id) !== timer)
+                return;
+            this.timers.delete(id);
+            const handlers = this.handlers;
+            if (!handlers)
+                return;
+            if (!handlers.fire) {
+                this.onError(new Error("WorkerHandlers.fire is required for timers"));
+                return;
+            }
+            this.track(handlers.fire(timer.tenantId, timer.key).catch(this.onError));
+        }, Math.max(0, timer.at - Date.now()));
+    }
+    scheduleSweep(tenantId, sweep, delay) {
+        if (sweep.running || sweep.handle)
+            return;
+        sweep.handle = setTimeout(() => {
+            sweep.handle = undefined;
+            const handlers = this.handlers;
+            if (!handlers || this.sweeps.get(tenantId) !== sweep)
+                return;
+            sweep.running = true;
+            this.track(handlers
+                .sweep(tenantId)
+                .catch(this.onError)
+                .finally(() => {
+                sweep.running = false;
+                if (this.handlers && this.sweeps.get(tenantId) === sweep)
+                    this.scheduleSweep(tenantId, sweep, this.sweepIntervalMs);
+            }));
+        }, delay);
+    }
+    later(ms, fn) {
+        const handle = setTimeout(() => {
+            this.delayed.delete(handle);
+            fn();
+        }, Math.max(0, ms));
+        this.delayed.add(handle);
+    }
+    track(promise) {
+        this.inflight.add(promise);
+        void promise.finally(() => this.inflight.delete(promise));
+    }
+}

package/dist/execution/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The Durable Session Execution seam (architecture §12.3).
+ *
+ * Durable Session Execution decides when to look at a session again. It never
+ * holds session state: every outcome lives in the Session Store, and `advance`
+ * is safe to repeat (§10.1). Restate is the supported implementation
+ * (`adapters/execution/restate.ts`); `execution/memory.ts` is the in-process
+ * implementation used by unit tests, `startEphemeralRuntime` and a Host
+ * started without Restate endpoints.
+ *
+ * ## Guarantees every implementation keeps
+ *
+ * - **One advance per key at a time.** The key is `<tenantId>:<sessionId>`.
+ *   Two `advance` calls for one key never overlap, on one process or many.
+ *   Different keys may run concurrently.
+ * - **At least once after a wake.** When `wake` resolves, an `advance` for the
+ *   key will start after that point (possibly merged with other wakes). Wakes
+ *   are sent after the Session Store transaction that caused them commits
+ *   (`Tx.afterCommit`), never inside it.
+ * - **Dedupe.** Wakes carrying the same `dedupeKey` for the same key cause at
+ *   most one advance for that cause (within the implementation's retention
+ *   window, at least 24 hours for Restate).
+ * - **Busy re-wake.** An advance that returns `busy` is re-run for the same key
+ *   after `retryAfterMs`.
+ * - **Retries on infrastructure errors.** A handler that throws is retried with
+ *   backoff. Session outcomes never throw: a turn that fails, pauses, waits or
+ *   becomes `uncertain` is settled in the Session Store and `advance` returns
+ *   `done`.
+ * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
+ *   armed Tenant is a no-op. The sweep expires claims, re-wakes orphaned
+ *   `runnable` sessions and relays outbox rows left behind.
+ */
+/** Why a session is woken (§12.3, "Where wakes come from"). */
+export type WakeReason = 
+/** Session commands. */
+"message" | "approve" | "respond"
+/** An executor posted an Action result. */
+ | "action_result"
+/** A linked agent turn completed, failed or was cancelled. */
+ | "linked"
+/** Queued flow effects, pending agent effects reconciled. */
+ | "flow"
+/** The Tenant sweep and `busy` re-wakes. */
+ | "recover";
+export declare const WAKE_REASONS: readonly WakeReason[];
+export interface Wake {
+    reason: WakeReason;
+    /**
+     * Merges repeated wakes for the same cause, e.g. the command's idempotency
+     * key. Scoped to the session key. Absent means never deduped.
+     */
+    dedupeKey?: string;
+}
+export type AdvanceResult = {
+    status: "done";
+}
+/** Another Worker holds a live lease; run again for this key after `retryAfterMs`. */
+ | {
+    status: "busy";
+    retryAfterMs: number;
+};
+/** What a Worker runs when Durable Session Execution calls it. */
+export interface WorkerHandlers {
+    /**
+     * Advances one session (§10.5). `signal` aborts when the Worker stops or the
+     * session is cancelled through the control stream. Throw only on
+     * infrastructure errors.
+     */
+    advance(tenantId: string, sessionId: string, signal: AbortSignal): Promise<AdvanceResult>;
+    /** One pass of the Tenant sweep. Re-armed by the implementation afterwards. */
+    sweep(tenantId: string): Promise<void>;
+    /** A durable timer set with `timer` fired. Required when `timer` is used. */
+    fire?(tenantId: string, key: string): Promise<void>;
+}
+export interface DurableExecution {
+    /** At-least-once. `dedupeKey` merges repeated wakes for the same cause. */
+    wake(tenantId: string, sessionId: string, wake: Wake): Promise<void>;
+    /**
+     * Durable one-shot timer that calls `WorkerHandlers.fire(tenantId, key)` at
+     * or after `at`. Setting a key again replaces the earlier time where the
+     * implementation can; `fire` must be idempotent either way.
+     */
+    timer(tenantId: string, key: string, at: Date): Promise<void>;
+    /** Arms the Tenant's self-re-arming sweep. Idempotent. */
+    armSweep(tenantId: string): Promise<void>;
+    /** Stops re-arming the Tenant's sweep (Tenant deleted). A pass already running finishes. */
+    disarmSweep(tenantId: string): Promise<void>;
+    /** Starts delivering to `handlers` (serving the Worker endpoint, for Restate). */
+    start(handlers: WorkerHandlers): Promise<void>;
+    /** Stops delivering, aborts running advances' signals and waits for them. */
+    stop(): Promise<void>;
+    /**
+     * Resolves when the backing service answers, rejects otherwise (readiness,
+     * `infra/execution.ts`). Absent for in-process implementations.
+     */
+    probe?(signal: AbortSignal): Promise<void>;
+    /**
+     * Invocations for `tenantId` that need an operator: paused after exhausting
+     * retries, or backing off after failures (Tenant status). Absent for
+     * in-process implementations.
+     */
+    stuckInvocations?(tenantId: string): Promise<StuckInvocation[]>;
+}
+/** An invocation that needs an operator (`DurableExecution.stuckInvocations`). */
+export interface StuckInvocation {
+    id: string;
+    /** `paused` or `backing-off`. */
+    status: string;
+    /** Service name without any prefix, e.g. `NylorunSession`. */
+    service: string;
+    handler: string;
+    /** Object key: `<tenantId>:<sessionId>`, `<tenantId>` or `<tenantId>:<timer key>`. */
+    key: string;
+    tenantId?: string;
+    retryCount: number;
+    lastFailure?: string;
+    modifiedAt?: string;
+}
+/** The key one advance at a time is serialized on. */
+export declare function sessionKey(tenantId: string, sessionId: string): string;
+/** Splits a key made by `sessionKey`. Tenant ids never contain `:`. */
+export declare function parseSessionKey(key: string): {
+    tenantId: string;
+    sessionId: string;
+};

package/dist/execution/types.js

@@ -0,0 +1,52 @@
+/**
+ * The Durable Session Execution seam (architecture §12.3).
+ *
+ * Durable Session Execution decides when to look at a session again. It never
+ * holds session state: every outcome lives in the Session Store, and `advance`
+ * is safe to repeat (§10.1). Restate is the supported implementation
+ * (`adapters/execution/restate.ts`); `execution/memory.ts` is the in-process
+ * implementation used by unit tests, `startEphemeralRuntime` and a Host
+ * started without Restate endpoints.
+ *
+ * ## Guarantees every implementation keeps
+ *
+ * - **One advance per key at a time.** The key is `<tenantId>:<sessionId>`.
+ *   Two `advance` calls for one key never overlap, on one process or many.
+ *   Different keys may run concurrently.
+ * - **At least once after a wake.** When `wake` resolves, an `advance` for the
+ *   key will start after that point (possibly merged with other wakes). Wakes
+ *   are sent after the Session Store transaction that caused them commits
+ *   (`Tx.afterCommit`), never inside it.
+ * - **Dedupe.** Wakes carrying the same `dedupeKey` for the same key cause at
+ *   most one advance for that cause (within the implementation's retention
+ *   window, at least 24 hours for Restate).
+ * - **Busy re-wake.** An advance that returns `busy` is re-run for the same key
+ *   after `retryAfterMs`.
+ * - **Retries on infrastructure errors.** A handler that throws is retried with
+ *   backoff. Session outcomes never throw: a turn that fails, pauses, waits or
+ *   becomes `uncertain` is settled in the Session Store and `advance` returns
+ *   `done`.
+ * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
+ *   armed Tenant is a no-op. The sweep expires claims, re-wakes orphaned
+ *   `runnable` sessions and relays outbox rows left behind.
+ */
+export const WAKE_REASONS = [
+    "message",
+    "approve",
+    "respond",
+    "action_result",
+    "linked",
+    "flow",
+    "recover",
+];
+/** The key one advance at a time is serialized on. */
+export function sessionKey(tenantId, sessionId) {
+    return `${tenantId}:${sessionId}`;
+}
+/** Splits a key made by `sessionKey`. Tenant ids never contain `:`. */
+export function parseSessionKey(key) {
+    const at = key.indexOf(":");
+    if (at <= 0 || at === key.length - 1)
+        throw new Error(`Invalid session key: ${key}`);
+    return { tenantId: key.slice(0, at), sessionId: key.slice(at + 1) };
+}

package/dist/host/config-for.d.ts

@@ -2,7 +2,8 @@ import type { HostConfigFile } from "./config.js";
 import type { Logger, TenantConfig } from "../tenant/types.js";
 /**
  * Builds a TenantConfig for `openTenantRuntime`.
- * Reads seeded sandbox backend from the Tenant database when present (I1).
+ * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
+ * setting overrides it when the Tenant opens (I1, A18).
  */
 export declare function configForFactory(options: {
     hostRoot: string;

package/dist/host/config-for.js

@@ -1,33 +1,15 @@
-import { existsSync } from "node:fs";
-import { DatabaseSync } from "node:sqlite";
 import { tenantPaths } from "../tenant/paths.js";
-import { readTenantConfig } from "../tenant/schema.js";
 import { tenantChildEnvironment } from "./environment.js";
 /**
  * Builds a TenantConfig for `openTenantRuntime`.
- * Reads seeded sandbox backend from the Tenant database when present (I1).
+ * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
+ * setting overrides it when the Tenant opens (I1, A18).
  */
 export function configForFactory(options) {
     const { baseline } = options;
     return (id) => {
         const tenant = tenantPaths(options.hostRoot, id);
-        let sandboxBackend = "auto";
-        if (existsSync(tenant.database)) {
-            try {
-                const db = new DatabaseSync(tenant.database, { readOnly: true });
-                try {
-                    const seeded = readTenantConfig(db).sandboxBackend;
-                    if (seeded)
-                        sandboxBackend = seeded;
-                }
-                finally {
-                    db.close();
-                }
-            }
-            catch {
-                /* unreadable — keep default */
-            }
-        }
+        const sandboxBackend = "auto";
         return {
             tenantId: id,
             mode: options.mode ?? "shared",

package/dist/host/config.d.ts

@@ -10,14 +10,6 @@ export interface HostConfigFile {
         nodeExtraCaCerts?: string;
     };
 }
-/** host-state.json — process only */
-export interface HostStateFile {
-    pid: number;
-    startedAt: string;
-    version: string;
-    entry: string;
-    url: string;
-}
 /** host-credentials.json, mode 0600 */
 export interface HostCredentialsFile {
     adminKey: string;

package/dist/host/create-host.d.ts

@@ -1,5 +1,6 @@
-import type { Logger, TenantModule } from "../tenant/types.js";
+import { type Logger, type TenantModule } from "../tenant/types.js";
 import type { HostConfigFile, HostCredentialsFile } from "./config.js";
+import type { ContainerListen } from "./stack-config.js";
 export interface CreateHostOptions {
     hostRoot: string;
     module: TenantModule;
@@ -10,10 +11,44 @@ export interface CreateHostOptions {
     coreVersion: string;
     /** Process id reported by `/health` and admin host status. Defaults to `process.pid`. */
     pid?: number;
+    /**
+     * Container mode: bind this address and port instead of host.json's, and
+     * accept only `allowedHosts` in the `Host` check (replacing the
+     * loopback-only rule). host.json then describes the client-facing address.
+     */
+    listen?: ContainerListen;
+    /**
+     * The client-facing URL `/v1/admin/status` reports as `host.url`
+     * (`NYLORUN_PUBLIC_URL`). Defaults to the bound address, which in container
+     * mode is `http://0.0.0.0:4000`.
+     */
+    publicUrl?: string;
+    /**
+     * Infrastructure readiness (`infra/readiness.ts`). `/ready` adds its checks
+     * and answers 503 while it reports not ok. Default: listener and discovery
+     * only.
+     */
+    readiness?: () => Promise<{
+        ok: boolean;
+        checks: Record<string, boolean>;
+    }>;
+    /**
+     * Shutdown steps around closing the Tenants. `close()` runs them whatever asked for it
+     * (SIGTERM in `host/main.ts`, `POST /v1/admin/host/shutdown`): the listener stops, then
+     * `beforeTenants` (stop the Worker so no advance starts on a closing Tenant), the Tenants
+     * close, then `afterTenants` (end the infrastructure clients). A failing step is logged
+     * and shutdown goes on.
+     */
+    shutdown?: {
+        beforeTenants?(): Promise<void>;
+        afterTenants?(): Promise<void>;
+    };
 }
 export interface HostServer {
     listen(): Promise<void>;
     close(): Promise<void>;
+    /** Settles once `close()` has finished, whatever called it. */
+    readonly closed: Promise<void>;
     readonly url: string;
 }
 /** Constant-time comparison of SHA-256 digests of the presented and stored admin keys. */