@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/api/openapi.js

@@ -0,0 +1,137 @@
+/**
+ * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
+ *
+ * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
+ *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
+ *   and attached to each release.
+ * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
+ *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ *
+ * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
+ * the environment: the same Runtime makes the same document.
+ */
+import { OpenAPIRegistry, OpenApiGeneratorV32, } from "@asteasolutions/zod-to-openapi";
+import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
+import { HealthResponseSchema, ReadyResponseSchema } from "@nylorun/core/contracts";
+import { createAdminApi } from "../host/admin-api.js";
+import { RUNTIME_VERSION } from "../version.js";
+import { tenantApi } from "./http/app.js";
+const PROTOCOL = {
+    min: HOST_PROTOCOL.min,
+    max: HOST_PROTOCOL.max,
+    features: [...HOST_PROTOCOL.features],
+};
+const bearer = (description, bearerFormat) => ({
+    type: "http",
+    scheme: "bearer",
+    ...(bearerFormat ? { bearerFormat } : {}),
+    description,
+});
+/** `/health`, `/ready` and `/openapi.json`: what every listener answers without a key. */
+function hostRoutes() {
+    const registry = new OpenAPIRegistry();
+    const route = (config) => registry.registerPath(config);
+    route({
+        method: "get",
+        path: "/health",
+        tags: ["Host"],
+        summary: "Check the Runtime",
+        description: "The protocol range and features a client checks first. Refuses an `Origin`.",
+        responses: {
+            200: {
+                description: "The Runtime is up",
+                content: { "application/json": { schema: HealthResponseSchema.meta({ id: "Health" }) } },
+            },
+        },
+    });
+    route({
+        method: "get",
+        path: "/ready",
+        tags: ["Host"],
+        summary: "Check the Runtime is ready",
+        description: "The listeners, the Tenant (open), Postgres, Restate and S2.",
+        responses: {
+            200: {
+                description: "Ready",
+                content: { "application/json": { schema: ReadyResponseSchema.meta({ id: "Ready" }) } },
+            },
+            503: { description: "Not ready: `checks` says what is not" },
+        },
+    });
+    route({
+        method: "get",
+        path: "/openapi.json",
+        tags: ["Host"],
+        summary: "Get this document",
+        responses: { 200: { description: "The Tenant API's OpenAPI document" } },
+    });
+    return registry;
+}
+function tenantSchemes(registry) {
+    registry.registerComponent("securitySchemes", "applicationKey", bearer("An application key of the Tenant, or a key derived from the admin key. With `Nylorun-Subject` and `Nylorun-Scopes`, it acts for that person, narrowed to those scopes."));
+    registry.registerComponent("securitySchemes", "subjectToken", bearer("A subject token (`POST /v1/tokens`): one person and one role of the access policy, for at most 15 minutes.", "JWT"));
+    registry.registerComponent("securitySchemes", "deliveryToken", bearer("The delivery token the Runtime signs each Action delivery with (`Nylorun-Signature`), sent back by the Action endpoint. It reaches only that Action's heartbeat, result and sandbox routes, while that delivery is current, for at most 15 minutes.", "JWT"));
+    registry.registerComponent("securitySchemes", "publishableKey", {
+        type: "apiKey",
+        in: "header",
+        name: "Nylorun-Key",
+        description: "A publishable key, sent by a browser page on one of its origins. Public by design: it grants the access policy's anonymous scopes.",
+    });
+}
+let tenant;
+let admin;
+/** The Tenant API's document. */
+export function tenantDocument() {
+    if (tenant)
+        return tenant;
+    const host = hostRoutes();
+    tenantSchemes(host);
+    tenant = new OpenApiGeneratorV32([
+        ...host.definitions,
+        ...tenantApi().openAPIRegistry.definitions,
+    ]).generateDocument({
+        openapi: "3.2.0",
+        info: {
+            title: "Nylorun Runtime: Tenant API",
+            version: RUNTIME_VERSION,
+            description: "Agents, sessions and their events, vaults, access and the Tenant's settings. A Runtime serves one Tenant: its URL is the Tenant's, and no request names it. Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials`, `x-nylorun-scopes` (the subject scopes that reach it) and `x-nylorun-browser` fields.",
+            "x-nylorun-protocol": PROTOCOL,
+        },
+        servers: [
+            {
+                url: "{origin}",
+                description: "A Runtime: the local stack (`nylorun start`), or where yours runs",
+                variables: { origin: { default: "http://localhost:8787" } },
+            },
+        ],
+    });
+    return tenant;
+}
+/** The Admin API's document. */
+export function adminDocument() {
+    if (admin)
+        return admin;
+    // Only the routes' declarations are read: nothing is served from this app.
+    const api = createAdminApi({
+        status: () => Promise.reject(new Error("Not served")),
+        shutdown: () => { },
+    });
+    api.openAPIRegistry.registerComponent("securitySchemes", "adminKey", bearer("The Host's admin key (`host-credentials.json`). Never a Tenant bearer."));
+    admin = new OpenApiGeneratorV32(api.openAPIRegistry.definitions).generateDocument({
+        openapi: "3.2.0",
+        info: {
+            title: "Nylorun Runtime: Admin API",
+            version: RUNTIME_VERSION,
+            description: "The Host's status, its Tenant's state and shutdown, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
+            "x-nylorun-protocol": PROTOCOL,
+        },
+        servers: [
+            {
+                url: "{origin}",
+                description: "The operator listener: the local stack's, or where yours runs",
+                variables: { origin: { default: "http://localhost:8788" } },
+            },
+        ],
+    });
+    return admin;
+}

package/dist/api/route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How the Runtime declares an HTTP route: once, for both serving and the OpenAPI document.
+ *
+ * `app.openapi(route, handler)` from `@hono/zod-openapi` also validates the path, query and
+ * body before the handler runs, answering failures its own way. The Runtime's handlers parse
+ * where they always have (after the lookups and checks a rejection must come after), so their
+ * rejections keep their order and messages; `serveRoute` registers the route and serves it
+ * with no validators of its own.
+ */
+import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
+import type { Env, Handler } from "hono";
+export declare function serveRoute<E extends Env>(app: OpenAPIHono<E>, route: RouteConfig, handler: Handler<E>): void;

package/dist/api/route.js

@@ -0,0 +1,4 @@
+export function serveRoute(app, route, handler) {
+    app.openAPIRegistry.registerPath(route);
+    app.on(route.method.toUpperCase(), route.path.replaceAll(/\/{(.+?)}/g, "/:$1"), handler);
+}

package/dist/core/bearer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Application keys are 256-bit CSPRNG values and the wire schema requires at least 16
+ * characters, so an unsalted digest is adequate to keep them out of the Session Store at rest.
+ * This is not a password KDF and must not be used for one.
+ */
+export declare const hashToken: (token: string) => string;
+/** Mint a 32-byte hex application key for tests and CLI bootstrap. */
+export declare function mintBearerToken(): string;

package/dist/core/bearer.js

@@ -0,0 +1,11 @@
+import { createHash, randomBytes } from "node:crypto";
+/**
+ * Application keys are 256-bit CSPRNG values and the wire schema requires at least 16
+ * characters, so an unsalted digest is adequate to keep them out of the Session Store at rest.
+ * This is not a password KDF and must not be used for one.
+ */
+export const hashToken = (token) => createHash("sha256").update(token, "utf8").digest("hex");
+/** Mint a 32-byte hex application key for tests and CLI bootstrap. */
+export function mintBearerToken() {
+    return randomBytes(32).toString("hex");
+}

package/dist/core/flow-host.d.ts

@@ -1,4 +1,4 @@
-import type { Action, ActionOutcome } from "@nylorun/core/contracts";
+import type { ActionOutcome } from "@nylorun/core/contracts";
 import type { JsonValue, WorkflowManifest } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
 import type { Wake } from "../execution/types.js";
@@ -73,7 +73,7 @@ export type CascadeCancelPlan = {
     /** Linked agent sessions to cancel, deepest path first. */
     readonly agentSessionIds: string[];
     readonly pendingActionIds: string[];
-    readonly claimedActionIds: string[];
+    readonly deliveringActionIds: string[];
 };
 /** Wakes a session after commit (`DurableExecution.wake` through the Tenant context). */
 type Schedule = (sessionId: string, wake: Wake) => void | Promise<void>;
@@ -83,7 +83,7 @@ export type FlowEffect = EffectDoc & {
     outcome?: ActionOutcome;
     error?: string;
 };
-/** Active agent turns + pending/claimed actions for one workflow turn. */
+/** Active agent turns + pending/delivering actions for one workflow turn. */
 export declare function countActiveFlowWork(t: Tx, workflowSessionId: string, turnId: string): Promise<number>;
 /** The `commands` document key of a session command's idempotency key (`tenant/commands.ts`). */
 export declare function commandKey(sessionId: string, idempotencyKey: string): string;
@@ -132,20 +132,11 @@ export declare function reconcilePendingAgentEffect(input: {
     readonly effectId: string;
     readonly schedule: Schedule;
 }): Promise<boolean>;
-/** Claimed `fn`/`verify` Actions, for the re-offer after a Tenant opens. */
-export declare function claimedFnVerifyActions(t: Tx): Promise<Action[]>;
-/**
- * Re-offer one claimed `fn`/`verify` Action (SD-P7 / WF-C9): they are pure or repeat-safe, so
- * a claim left by an executor of an earlier process is offered again at once rather than
- * after its lease. The next claim bumps the generation, which fences a late result. Locks
- * only the Action's session. Returns true when it re-offered.
- */
-export declare function reofferFnVerifyClaim(t: Tx, actionId: string): Promise<boolean>;
 /** Path depth for deepest-first cancel ordering. */
 export declare function pathDepth(path: string): number;
 /**
  * Plan a cancel cascade for a workflow session: linked agents deepest first,
- * then pending → cancelled and claimed → uncertain actions (SD-P11 / WF-R53).
+ * then pending → cancelled and delivering → uncertain actions (SD-P11 / WF-R53).
  */
 export declare function planCancelCascade(input: {
     readonly t: Tx;
@@ -155,7 +146,7 @@ export declare function planCancelCascade(input: {
 /**
  * Cancel sibling work under a Parallel/Map parent when one branch fails (PAR-R6).
  * Agent turns listed in `agentSessionIds` are returned for the caller to cancel;
- * pending actions → cancelled, claimed tool actions → uncertain.
+ * pending actions → cancelled, delivering tool actions → uncertain.
  * When `cancelEffectIds` is provided, those effects are marked cancelled and their
  * paths are included in the sibling path set.
  */
@@ -169,7 +160,8 @@ export declare function cancelSiblingWork(input: {
     readonly cancelEffectIds?: readonly string[];
 }): Promise<CancelSiblingResult>;
 /**
- * Apply cancel fencing to workflow-session actions (pending→cancelled, claimed→uncertain).
+ * Apply cancel fencing to workflow-session actions (pending→cancelled,
+ * delivering→uncertain).
  */
 export declare function fenceWorkflowActions(input: {
     readonly t: Tx;

package/dist/core/flow-host.js

@@ -23,8 +23,6 @@
  * - `wakeLinkedWorkflow({ t, agentSessionId, turnId, output?, failed?, cancelled?, error?, schedule }): Promise<void>`
  * - `pendingAgentEffects(t): Promise<FlowEffect[]>`
  * - `reconcilePendingAgentEffect({ t, effectId, schedule }): Promise<boolean>`
- * - `claimedFnVerifyActions(t): Promise<Action[]>`
- * - `reofferFnVerifyClaim(t, actionId): Promise<boolean>`
  * - `planCancelCascade({ t, workflowSessionId, turnId }): Promise<CascadeCancelPlan>`
  * - `cancelSiblingWork({ t, workflowSessionId, turnId, siblingPaths?, cancelEffectIds? }): Promise<CancelSiblingResult>`
  * - `fenceWorkflowActions({ t, workflowSessionId, turnId }): Promise<{ cancelled; uncertain }>`
@@ -91,11 +89,12 @@ export function isFlowEffect(request) {
         request.kind === "verify" ||
         isFlowToolEffect(request));
 }
-const OPEN_ACTION = ["pending", "claimed"];
+/** Actions still to be settled: waiting to be delivered, or being delivered. */
+const OPEN_ACTION = ["pending", "delivering"];
 function scheduleAfterCommit(t, schedule, id, wake) {
     t.afterCommit(() => schedule(id, wake));
 }
-/** Active agent turns + pending/claimed actions for one workflow turn. */
+/** Active agent turns + pending/delivering actions for one workflow turn. */
 export async function countActiveFlowWork(t, workflowSessionId, turnId) {
     const effects = await t.effectsForTurn(workflowSessionId, turnId);
     const openActions = new Set((await t.actionsForSession(workflowSessionId, {
@@ -254,34 +253,6 @@ export async function reconcilePendingAgentEffect(input) {
     });
     return true;
 }
-/** Claimed `fn`/`verify` Actions, for the re-offer after a Tenant opens. */
-export async function claimedFnVerifyActions(t) {
-    return t.actionsWithStatus(["claimed"], { kinds: ["fn", "verify"] });
-}
-/**
- * Re-offer one claimed `fn`/`verify` Action (SD-P7 / WF-C9): they are pure or repeat-safe, so
- * a claim left by an executor of an earlier process is offered again at once rather than
- * after its lease. The next claim bumps the generation, which fences a late result. Locks
- * only the Action's session. Returns true when it re-offered.
- */
-export async function reofferFnVerifyClaim(t, actionId) {
-    const found = await t.get("actions", actionId);
-    if (!found)
-        return false;
-    await t.lockSession(found.sessionId);
-    // Read again under the session lock.
-    const action = await t.get("actions", actionId);
-    if (!action ||
-        action.status !== "claimed" ||
-        (action.kind !== "fn" && action.kind !== "verify"))
-        return false;
-    action.status = "pending";
-    action.claimId = null;
-    action.leaseExpiresAt = null;
-    await t.put("actions", action.actionId, action);
-    t.signalWork();
-    return true;
-}
 /** Path depth for deepest-first cancel ordering. */
 export function pathDepth(path) {
     if (!path)
@@ -290,14 +261,14 @@ export function pathDepth(path) {
 }
 /**
  * Plan a cancel cascade for a workflow session: linked agents deepest first,
- * then pending → cancelled and claimed → uncertain actions (SD-P11 / WF-R53).
+ * then pending → cancelled and delivering → uncertain actions (SD-P11 / WF-R53).
  */
 export async function planCancelCascade(input) {
     const { t } = input;
     const agentEntries = (await t.linkedSessions(input.workflowSessionId)).map((linked) => ({ sessionId: linked.agentSessionId, path: linked.link.path }));
     agentEntries.sort((a, b) => pathDepth(b.path) - pathDepth(a.path));
     const pendingActionIds = [];
-    const claimedActionIds = [];
+    const deliveringActionIds = [];
     const actions = await t.actionsForSession(input.workflowSessionId, {
         ...(input.turnId !== null ? { turnId: input.turnId } : {}),
         statuses: OPEN_ACTION,
@@ -305,19 +276,20 @@ export async function planCancelCascade(input) {
     for (const action of actions) {
         if (action.status === "pending")
             pendingActionIds.push(action.actionId);
-        else if (action.status === "claimed")
-            claimedActionIds.push(action.actionId);
+        // Being delivered: the code may already be running.
+        else
+            deliveringActionIds.push(action.actionId);
     }
     return {
         agentSessionIds: agentEntries.map((e) => e.sessionId),
         pendingActionIds,
-        claimedActionIds,
+        deliveringActionIds,
     };
 }
 /**
  * Cancel sibling work under a Parallel/Map parent when one branch fails (PAR-R6).
  * Agent turns listed in `agentSessionIds` are returned for the caller to cancel;
- * pending actions → cancelled, claimed tool actions → uncertain.
+ * pending actions → cancelled, delivering tool actions → uncertain.
  * When `cancelEffectIds` is provided, those effects are marked cancelled and their
  * paths are included in the sibling path set.
  */
@@ -363,7 +335,8 @@ export async function cancelSiblingWork(input) {
     for (const action of actions) {
         if (!matchesSibling(action.path))
             continue;
-        const next = action.status === "claimed" ? "uncertain" : "cancelled";
+        // Delivered work may already have had an external effect.
+        const next = action.status === "pending" ? "cancelled" : "uncertain";
         action.status = next;
         await t.put("actions", action.actionId, action);
         const effect = await t.get("effects", action.actionId);
@@ -379,7 +352,8 @@ export async function cancelSiblingWork(input) {
     return { cancelledActions, uncertainActions, agentSessionIds };
 }
 /**
- * Apply cancel fencing to workflow-session actions (pending→cancelled, claimed→uncertain).
+ * Apply cancel fencing to workflow-session actions (pending→cancelled,
+ * delivering→uncertain).
  */
 export async function fenceWorkflowActions(input) {
     const { t } = input;
@@ -392,7 +366,8 @@ export async function fenceWorkflowActions(input) {
         statuses: OPEN_ACTION,
     });
     for (const action of actions) {
-        const next = action.status === "claimed" ? "uncertain" : "cancelled";
+        // Delivered work may already have had an external effect.
+        const next = action.status === "pending" ? "cancelled" : "uncertain";
         action.status = next;
         await t.put("actions", action.actionId, action);
         const effect = await t.get("effects", action.actionId);

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

@@ -27,18 +27,23 @@ export type SandboxRouteDeps = {
  */
 export declare function handleSessionSandboxTool(deps: SandboxRouteDeps, sessionId: string, toolName: string, body: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
 /**
- * `POST /v1/actions/:id/sandbox/:tool` — executor, authorized by the live claim.
- * Body must include claimId and generation matching the claimed action.
+ * `POST /v1/actions/:id/sandbox/:tool` — the Action endpoint, authorized by the delivery token
+ * of the Action's current delivery (`delivery.generation`). The body is the tool's input.
+ */
+export declare function handleActionSandboxTool(deps: SandboxRouteDeps, actionId: string, toolName: string, body: unknown, signal: AbortSignal, delivery: {
+    generation: number;
+}): Promise<SandboxToolOutcome>;
+/**
+ * Validate PutSession.sandbox attach: same owner, and a sandbox to share. A session whose
+ * definition declares a sandbox must declare the owner's spec; one whose definition declares
+ * none inherits it (`inherit`).
  */
-export declare function handleActionSandboxTool(deps: SandboxRouteDeps, actionId: string, toolName: string, body: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
-/** Validate PutSession.sandbox attach: same owner, identical specs. */
 export declare function validateSandboxAttach(body: {
     ownerUserId: string;
-    sandbox?: {
-        session: string;
-    };
+    sandbox?: unknown;
 }, 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;
+    inherit?: boolean;
 }): string | undefined;

package/dist/core/sandbox-routes.js

@@ -3,7 +3,7 @@
  * Wired from TenantRuntime; keeps route bodies out of the hot runtime file.
  */
 import { isSandboxToolName, } from "@nylorun/core/define";
-import { capabilityForSandbox, owningSandboxSessionId, sandboxSpecOf, sandboxSpecsEqual, } from "../sandbox/share.js";
+import { capabilityForSandbox, owningSandboxSessionId, sandboxSpecOf, sandboxSpecsEqual, sessionSandboxSpec, } from "../sandbox/share.js";
 export class SandboxRouteError extends Error {
     status;
     constructor(status, message) {
@@ -15,7 +15,7 @@ export class SandboxRouteError extends Error {
 function resolveSpec(session, lookup) {
     const ownerId = owningSandboxSessionId(session, lookup);
     const owner = ownerId === session.id ? session : lookup(ownerId) ?? session;
-    const spec = sandboxSpecOf(owner.manifest) ?? sandboxSpecOf(session.manifest);
+    const spec = sessionSandboxSpec(owner) ?? sessionSandboxSpec(session);
     if (!spec)
         throw new SandboxRouteError(404, "Session has no sandbox");
     return spec;
@@ -31,7 +31,7 @@ function toolInput(body) {
     if (typeof body !== "object" || Array.isArray(body))
         throw new SandboxRouteError(400, "Sandbox tool body must be an object");
     const record = body;
-    const { claimId: _c, generation: _g, requestId: _r, ...input } = record;
+    const { requestId: _r, ...input } = record;
     return input;
 }
 async function runTool(deps, { session, lookup }, tool, input, signal) {
@@ -56,39 +56,36 @@ export async function handleSessionSandboxTool(deps, sessionId, toolName, body,
     return runTool(deps, read, tool, toolInput(body), signal);
 }
 /**
- * `POST /v1/actions/:id/sandbox/:tool` — executor, authorized by the live claim.
- * Body must include claimId and generation matching the claimed action.
+ * `POST /v1/actions/:id/sandbox/:tool` — the Action endpoint, authorized by the delivery token
+ * of the Action's current delivery (`delivery.generation`). The body is the tool's input.
  */
-export async function handleActionSandboxTool(deps, actionId, toolName, body, signal) {
+export async function handleActionSandboxTool(deps, actionId, toolName, body, signal, delivery) {
     if (!body || typeof body !== "object" || Array.isArray(body))
         throw new SandboxRouteError(400, "Sandbox tool body must be an object");
-    const record = body;
-    const claimId = record.claimId;
-    const generation = record.generation;
-    if (typeof claimId !== "string" || claimId.length === 0)
-        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 = await deps.getAction(actionId);
     if (!action)
         throw new SandboxRouteError(404, "Action not found");
-    if (action.status !== "claimed" ||
-        action.claimId !== claimId ||
-        action.generation !== generation ||
-        !action.leaseExpiresAt ||
-        Date.parse(action.leaseExpiresAt) <= Date.now())
-        throw new SandboxRouteError(409, "Stale or expired claim");
+    if (action.status !== "delivering" ||
+        action.generation !== delivery.generation ||
+        Date.parse(action.deadlineAt ?? "") <= Date.now())
+        throw new SandboxRouteError(409, "The delivery was cancelled, lost or delivered again");
     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, read, tool, toolInput(body), signal);
+    return runTool(deps, read, parseTool(toolName), toolInput(body), signal);
 }
-/** Validate PutSession.sandbox attach: same owner, identical specs. */
+/**
+ * Validate PutSession.sandbox attach: same owner, and a sandbox to share. A session whose
+ * definition declares a sandbox must declare the owner's spec; one whose definition declares
+ * none inherits it (`inherit`).
+ */
 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;
+    const request = body.sandbox;
+    const share = typeof request === "object" && request !== null && "session" in request
+        ? String(request.session)
+        : undefined;
     if (!share)
         return undefined;
     const owner = lookup(share);
@@ -96,10 +93,12 @@ options = {}) {
         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");
-    const ownerSpec = sandboxSpecOf(owner.manifest);
-    const newSpec = sandboxSpecOf(newManifest);
+    const ownerSpec = sessionSandboxSpec(owner);
     if (!ownerSpec)
         throw new SandboxRouteError(400, "Target session has no sandbox to share");
+    if (options.inherit)
+        return owningSandboxSessionId(owner, lookup);
+    const newSpec = sandboxSpecOf(newManifest);
     if (!newSpec)
         throw new SandboxRouteError(400, "Session must declare a sandbox identical to the shared session");
     if (!sandboxSpecsEqual(ownerSpec, newSpec))

package/dist/execution/memory.d.ts

@@ -2,9 +2,9 @@ import { type DurableExecution, type Wake, type WorkerHandlers } from "./types.j
 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. */
+    /** First retry delay after `advance` or `deliver` throws; doubles per attempt. Default 50. */
     retryDelayMs?: number;
-    /** Attempts before giving up on a throwing `advance` and reporting it. Default 5. */
+    /** Attempts before giving up on a throwing handler and reporting it. Default 5. */
     maxAttempts?: number;
     /** How long a dedupe key merges repeated wakes. Default 24 hours. */
     dedupeRetentionMs?: number;
@@ -32,21 +32,24 @@ export declare class MemoryExecution implements DurableExecution {
     private readonly onError;
     constructor(options?: MemoryExecutionOptions);
     wake(tenantId: string, sessionId: string, wake: Wake): Promise<void>;
+    deliver(tenantId: string, actionId: string): 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.
+     * Resolves once no advance or delivery is running or queued and no busy or
+     * retry re-run 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 runOnce;
+    /** Runs the key's handler; resolves to a delay when the key must run again. */
+    private call;
     private armTimer;
     private scheduleSweep;
     private later;

package/dist/execution/memory.js

@@ -41,7 +41,10 @@ export class MemoryExecution {
                 return;
             this.seen.set(dedupe, now);
         }
-        this.enqueue(tenantId, sessionId);
+        this.enqueue("advance", tenantId, sessionId);
+    }
+    async deliver(tenantId, actionId) {
+        this.enqueue("deliver", tenantId, actionId);
     }
     async timer(tenantId, key, at) {
         const id = `${tenantId}\u0000${key}`;
@@ -96,8 +99,8 @@ export class MemoryExecution {
             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.
+     * Resolves once no advance or delivery is running or queued and no busy or
+     * retry re-run is pending. Timers and sweeps are not waited for. Test helper.
      */
     async idle() {
         while (this.delayed.size > 0 ||
@@ -105,13 +108,14 @@ export class MemoryExecution {
             [...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);
+    enqueue(kind, tenantId, id) {
+        const key = stateKey(kind, tenantId, id);
         let state = this.keys.get(key);
         if (!state)
             this.keys.set(key, (state = {
+                kind,
                 tenantId,
-                sessionId,
+                id,
                 running: false,
                 queued: false,
                 attempts: 0,
@@ -126,14 +130,14 @@ export class MemoryExecution {
             try {
                 while (state.queued && this.handlers) {
                     state.queued = false;
-                    await this.advanceOnce(state, this.handlers);
+                    await this.runOnce(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);
+                const key = stateKey(state.kind, state.tenantId, state.id);
                 if (!state.queued && state.attempts === 0 && this.keys.get(key) === state)
                     this.keys.delete(key);
             }
@@ -147,14 +151,15 @@ export class MemoryExecution {
             this.seen.delete(dedupe);
         }
     }
-    async advanceOnce(state, handlers) {
+    async runOnce(state, handlers) {
         const controller = new AbortController();
         state.controller = controller;
+        const again = () => this.enqueue(state.kind, state.tenantId, state.id);
         try {
-            const result = await handlers.advance(state.tenantId, state.sessionId, controller.signal);
+            const retryAfterMs = await this.call(state, handlers, controller.signal);
             state.attempts = 0;
-            if (result.status === "busy")
-                this.later(result.retryAfterMs, () => this.enqueue(state.tenantId, state.sessionId));
+            if (retryAfterMs !== undefined)
+                this.later(retryAfterMs, again);
         }
         catch (error) {
             state.attempts += 1;
@@ -163,12 +168,23 @@ export class MemoryExecution {
                 this.onError(error);
             }
             else
-                this.later(this.retryDelayMs * 2 ** (state.attempts - 1), () => this.enqueue(state.tenantId, state.sessionId));
+                this.later(this.retryDelayMs * 2 ** (state.attempts - 1), again);
         }
         finally {
             state.controller = undefined;
         }
     }
+    /** Runs the key's handler; resolves to a delay when the key must run again. */
+    async call(state, handlers, signal) {
+        if (state.kind === "advance") {
+            const result = await handlers.advance(state.tenantId, state.id, signal);
+            return result.status === "busy" ? result.retryAfterMs : undefined;
+        }
+        if (!handlers.deliver)
+            throw new Error("WorkerHandlers.deliver is required for deliveries");
+        const result = await handlers.deliver(state.tenantId, state.id, signal);
+        return result.status === "retry" ? result.retryAfterMs : undefined;
+    }
     armTimer(id, timer) {
         timer.handle = setTimeout(() => {
             if (this.timers.get(id) !== timer)
@@ -215,3 +231,7 @@ export class MemoryExecution {
         void promise.finally(() => this.inflight.delete(promise));
     }
 }
+/** Advances and deliveries are queued apart: a session id and an Action id may be equal. */
+function stateKey(kind, tenantId, id) {
+    return `${kind}\u0000${sessionKey(tenantId, id)}`;
+}