@nylorun/runtime 0.9.0-beta → 0.11.0-beta

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

@@ -0,0 +1,40 @@
+import type { Action } from "@nylorun/core/contracts";
+import type { SandboxManager } from "../sandbox/manager.js";
+import type { SandboxToolOutcome } from "../sandbox/tools.js";
+import { type SessionSandboxRef } from "../sandbox/share.js";
+export declare class SandboxRouteError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+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;
+    /** 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.
+ * Refused while the session has an active agent turn.
+ */
+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.
+ */
+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;
+    };
+}, newManifest: SessionSandboxRef["manifest"], lookup: (id: string) => SessionSandboxRef | undefined): string | undefined;

package/dist/core/sandbox-routes.js

@@ -0,0 +1,106 @@
+/**
+ * HTTP handlers for session-scoped and claim-scoped sandbox tool endpoints.
+ * 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";
+export class SandboxRouteError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "SandboxRouteError";
+    }
+}
+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);
+    if (!spec)
+        throw new SandboxRouteError(404, "Session has no sandbox");
+    return spec;
+}
+function parseTool(tool) {
+    if (!isSandboxToolName(tool))
+        throw new SandboxRouteError(400, `Unknown sandbox tool '${tool}'`);
+    return tool;
+}
+function toolInput(body) {
+    if (body === undefined || body === null)
+        return {};
+    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;
+    return input;
+}
+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,
+        manifest: session.manifest,
+    };
+    return deps.sandbox.run(ref, capabilityForSandbox(spec), tool, input, signal);
+}
+/**
+ * `POST /v1/sessions/:id/sandbox/:tool` — application principal.
+ * Refused while the session has an active agent turn.
+ */
+export async function handleSessionSandboxTool(deps, sessionId, toolName, body, signal) {
+    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, 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.
+ */
+export async function handleActionSandboxTool(deps, actionId, toolName, body, signal) {
+    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");
+    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);
+}
+/** Validate PutSession.sandbox attach: same owner, identical specs. */
+export function validateSandboxAttach(body, newManifest, lookup) {
+    const share = body.sandbox?.session;
+    if (!share)
+        return undefined;
+    const owner = lookup(share);
+    if (!owner)
+        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);
+    if (!ownerSpec)
+        throw new SandboxRouteError(400, "Target session has no sandbox to share");
+    if (!newSpec)
+        throw new SandboxRouteError(400, "Session must declare a sandbox identical to the shared session");
+    if (!sandboxSpecsEqual(ownerSpec, newSpec))
+        throw new SandboxRouteError(409, "Sandbox specs must be identical to share a sandbox");
+    return owningSandboxSessionId(owner, lookup);
+}

package/dist/core/turn-manifest.d.ts

@@ -0,0 +1,50 @@
+import { type AgentManifest } from "@nylorun/core/contracts";
+export type TurnManifestStore = {
+    /** Look up a previously pinned turn variant by hash. */
+    get(hash: string): AgentManifest | undefined;
+    /** Persist a validated turn variant for replay / Studio. */
+    put(hash: string, manifest: AgentManifest): void;
+};
+export type TurnManifestOk = {
+    readonly ok: true;
+    readonly manifest: AgentManifest;
+    readonly hash: string;
+};
+export type TurnManifestErr = {
+    readonly ok: false;
+    readonly code: "loop.invalid-agent";
+    readonly message: string;
+};
+/**
+ * Parse `message.manifest`, require it to be a variant of the session pin,
+ * hash it, and store it. Applies to that turn only (caller must not latch).
+ */
+export declare function pinTurnManifest(args: {
+    readonly candidate: unknown;
+    readonly pinned: AgentManifest;
+    readonly store: TurnManifestStore;
+}): TurnManifestOk | TurnManifestErr;
+/** Resolve the manifest a turn runs with: optional message field, else the pin. */
+export declare function resolveMessageManifest(args: {
+    readonly pinned: AgentManifest;
+    readonly pinnedHash: string;
+    readonly messageManifest?: unknown;
+    readonly store: TurnManifestStore;
+}): TurnManifestOk | TurnManifestErr;
+/**
+ * At turn start: if state's hash differs from the turn's, set `state.manifestHash`
+ * to the turn's when both are the pin or validated variants (`loops.md` §4.2).
+ * Leaves state unchanged when either hash is unrelated (runDurable still rejects).
+ */
+export declare function rebaseTurnState<S extends {
+    manifestHash?: string;
+}>(args: {
+    readonly state: S | undefined;
+    readonly turnManifestHash: string;
+    readonly isAllowedHash: (hash: string) => boolean;
+}): S | undefined;
+/** Allowed hashes: the session pin plus every stored turn variant. */
+export declare function allowedManifestHashes(args: {
+    readonly pinnedHash: string;
+    readonly variantHashes: Iterable<string>;
+}): Set<string>;

package/dist/core/turn-manifest.js

@@ -0,0 +1,66 @@
+import { AgentManifestSchema, } from "@nylorun/core/contracts";
+import { hashManifest } from "@nylorun/core/compatibility";
+import { isVariantOf } from "@nylorun/core/define";
+/**
+ * Parse `message.manifest`, require it to be a variant of the session pin,
+ * hash it, and store it. Applies to that turn only (caller must not latch).
+ */
+export function pinTurnManifest(args) {
+    const parsed = AgentManifestSchema.safeParse(args.candidate);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            code: "loop.invalid-agent",
+            message: "Turn manifest failed AgentManifestSchema validation",
+        };
+    }
+    const manifest = parsed.data;
+    if (!isVariantOf(manifest, args.pinned)) {
+        return {
+            ok: false,
+            code: "loop.invalid-agent",
+            message: "Turn manifest is not a variant of the session's pinned manifest",
+        };
+    }
+    const hash = hashManifest(manifest);
+    args.store.put(hash, manifest);
+    return { ok: true, manifest, hash };
+}
+/** Resolve the manifest a turn runs with: optional message field, else the pin. */
+export function resolveMessageManifest(args) {
+    if (args.messageManifest === undefined) {
+        return {
+            ok: true,
+            manifest: args.pinned,
+            hash: args.pinnedHash,
+        };
+    }
+    return pinTurnManifest({
+        candidate: args.messageManifest,
+        pinned: args.pinned,
+        store: args.store,
+    });
+}
+/**
+ * At turn start: if state's hash differs from the turn's, set `state.manifestHash`
+ * to the turn's when both are the pin or validated variants (`loops.md` §4.2).
+ * Leaves state unchanged when either hash is unrelated (runDurable still rejects).
+ */
+export function rebaseTurnState(args) {
+    const state = args.state;
+    if (!state?.manifestHash)
+        return state;
+    if (state.manifestHash === args.turnManifestHash)
+        return state;
+    if (!args.isAllowedHash(state.manifestHash) ||
+        !args.isAllowedHash(args.turnManifestHash))
+        return state;
+    return { ...state, manifestHash: args.turnManifestHash };
+}
+/** Allowed hashes: the session pin plus every stored turn variant. */
+export function allowedManifestHashes(args) {
+    const set = new Set([args.pinnedHash]);
+    for (const hash of args.variantHashes)
+        set.add(hash);
+    return set;
+}

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;
+};