@nylorun/runtime 0.12.0-beta → 0.14.0-beta

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 }>`
@@ -61,6 +59,9 @@ export function deriveSessionId(workflowSessionId, path, ...parts) {
  * (path, turnId, iterations) so prior verdicts cannot leak across Loop iterations.
  */
 export function deriveAgentEffectSessionId(workflowSessionId, path, request) {
+    // A flow agent used as a tool starts fresh on every call, like any agent used as a tool.
+    if (request.context?.role === "delegate")
+        return deriveSessionId(workflowSessionId, path, "delegate", String(request.context.delegationId ?? request.turnId));
     if (request.context?.role === "verify-agent") {
         const iterations = request.iterations ?? "-";
         const iterParts = iterations !== "-" && iterations.length > 0 ? iterations.split(".") : [];
@@ -88,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, {
@@ -251,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)
@@ -287,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,
@@ -302,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.
  */
@@ -360,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);
@@ -376,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;
@@ -389,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)}`;
+}

package/dist/execution/types.d.ts

@@ -27,21 +27,31 @@
  *   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.
+ *   armed Tenant is a no-op. The sweep settles lapsed deliveries and re-wakes
+ *   orphaned `runnable` sessions.
+ * - **One delivery per Action at a time.** `deliver` runs
+ *   `WorkerHandlers.deliver` for the key `<tenantId>:<actionId>` at least once
+ *   after it resolves. Two deliveries for one key never overlap; repeated
+ *   `deliver` calls may each run it, so the handler reads the Action's state
+ *   and does nothing when there is nothing to deliver.
+ * - **Retry after `retry`.** A delivery that returns `retry` is run again for
+ *   the same key after `retryAfterMs`. This is how an Action endpoint that is
+ *   down or busy is retried; the handler throws only on infrastructure errors.
  */
 /** 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. */
+/** An Action's outcome was recorded (a delivery's answer or a background 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";
+ | "recover"
+/** A long turn ended a segment at a step boundary and continues in the next (Model Calls §10). */
+ | "rollover";
 export declare const WAKE_REASONS: readonly WakeReason[];
 export interface Wake {
     reason: WakeReason;
@@ -59,6 +69,14 @@ export type AdvanceResult = {
     status: "busy";
     retryAfterMs: number;
 };
+export type DeliverResult = {
+    status: "done";
+}
+/** The Action is still to be delivered; run again for this key after `retryAfterMs`. */
+ | {
+    status: "retry";
+    retryAfterMs: number;
+};
 /** What a Worker runs when Durable Session Execution calls it. */
 export interface WorkerHandlers {
     /**
@@ -71,6 +89,11 @@ export interface WorkerHandlers {
     sweep(tenantId: string): Promise<void>;
     /** A durable timer set with `timer` fired. Required when `timer` is used. */
     fire?(tenantId: string, key: string): Promise<void>;
+    /**
+     * Delivers one Action to its Action endpoint. `signal` aborts when the Worker
+     * stops. Throw only on infrastructure errors. Required when `deliver` is used.
+     */
+    deliver?(tenantId: string, actionId: string, signal: AbortSignal): Promise<DeliverResult>;
 }
 export interface DurableExecution {
     /** At-least-once. `dedupeKey` merges repeated wakes for the same cause. */
@@ -81,6 +104,12 @@ export interface DurableExecution {
      * implementation can; `fire` must be idempotent either way.
      */
     timer(tenantId: string, key: string, at: Date): Promise<void>;
+    /**
+     * At-least-once: `WorkerHandlers.deliver(tenantId, actionId)` runs after this
+     * resolves, never overlapping another delivery of the same Action. Send it
+     * after the transaction that made the Action pending commits.
+     */
+    deliver(tenantId: string, actionId: string): 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. */
@@ -109,14 +138,17 @@ export interface StuckInvocation {
     /** Service name without any prefix, e.g. `NylorunSession`. */
     service: string;
     handler: string;
-    /** Object key: `<tenantId>:<sessionId>`, `<tenantId>` or `<tenantId>:<timer key>`. */
+    /**
+     * Object key: `<tenantId>:<sessionId>`, `<tenantId>`, `<tenantId>:<timer key>` or
+     * `<tenantId>:<actionId>`.
+     */
     key: string;
     tenantId?: string;
     retryCount: number;
     lastFailure?: string;
     modifiedAt?: string;
 }
-/** The key one advance at a time is serialized on. */
+/** The key one advance (or one delivery, with an Action id) 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): {

package/dist/execution/types.js

@@ -27,8 +27,16 @@
  *   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.
+ *   armed Tenant is a no-op. The sweep settles lapsed deliveries and re-wakes
+ *   orphaned `runnable` sessions.
+ * - **One delivery per Action at a time.** `deliver` runs
+ *   `WorkerHandlers.deliver` for the key `<tenantId>:<actionId>` at least once
+ *   after it resolves. Two deliveries for one key never overlap; repeated
+ *   `deliver` calls may each run it, so the handler reads the Action's state
+ *   and does nothing when there is nothing to deliver.
+ * - **Retry after `retry`.** A delivery that returns `retry` is run again for
+ *   the same key after `retryAfterMs`. This is how an Action endpoint that is
+ *   down or busy is retried; the handler throws only on infrastructure errors.
  */
 export const WAKE_REASONS = [
     "message",
@@ -38,8 +46,9 @@ export const WAKE_REASONS = [
     "linked",
     "flow",
     "recover",
+    "rollover",
 ];
-/** The key one advance at a time is serialized on. */
+/** The key one advance (or one delivery, with an Action id) at a time is serialized on. */
 export function sessionKey(tenantId, sessionId) {
     return `${tenantId}:${sessionId}`;
 }

package/dist/host/admin-api.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The Admin API (`/v1/admin/**`): Tenants and the Host's status, for a caller with the admin
+ * key. The Host checks the listener, the protocol and the admin key first (`app.ts`); what
+ * gets here is authorized. Routes are declared once, for serving and for the OpenAPI document.
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { type AdminStatus } from "@nylorun/core/contracts";
+import { type NodeBindings, type TenantModule } from "../tenant/types.js";
+export interface AdminApiOptions {
+    module: TenantModule;
+    /** `GET /v1/admin/status`. */
+    status(): Promise<AdminStatus>;
+    /** Stops the Host once the shutdown answer is sent. */
+    shutdown(): void;
+    /** `GET /v1/admin/openapi.json`: this API's OpenAPI document (`api/openapi.ts`). */
+    document?(): unknown;
+}
+type AdminEnv = {
+    Bindings: NodeBindings;
+};
+export declare function createAdminApi(options: AdminApiOptions): OpenAPIHono<AdminEnv>;
+export {};