@nylorun/runtime 0.9.0-beta → 0.11.0-beta

package/dist/streams/relay.d.ts

@@ -0,0 +1,37 @@
+import type { SessionStore } from "../store/types.js";
+import { type DurableStreams } from "./types.js";
+/** A session's outbox starts past the end of its stream: events are missing from the stream. */
+export declare class StreamGapError extends Error {
+    constructor(sessionId: string, first: number, tail: number);
+}
+export interface RelayOptions {
+    store: SessionStore;
+    streams: DurableStreams;
+    /** The Tenant whose basin receives the events; must match `store.tenantId`. */
+    tenantId: string;
+    /** Receives append and delete failures. The rows they concern stay in the outbox. */
+    onError?: (error: unknown) => void;
+}
+export interface Relay {
+    /**
+     * Appends leftover outbox rows (at most `limit`, default 1000) per session in
+     * sequence order: the Tenant sweep's recovery after a crash or an S2 outage.
+     * Resolves with the number of rows now in S2 and removed from the outbox.
+     * Per-session failures go to `onError`; those rows stay.
+     */
+    drain(limit?: number): Promise<number>;
+    /** Resolves when every relay started so far has settled. */
+    idle(): Promise<void>;
+    /** Stops listening to commits and waits for in-flight relays. */
+    close(): Promise<void>;
+}
+export declare function createRelay(options: RelayOptions): Relay;
+/** Appends a `work_available` signal to `tenant/work`. Not relayed through the outbox. */
+export declare function signalWork(streams: DurableStreams, tenantId: string): Promise<void>;
+/** Appends a `session.cancel` signal to `tenant/control`. Not relayed through the outbox. */
+export declare function signalCancel(streams: DurableStreams, tenantId: string, sessionId: string): Promise<void>;
+/**
+ * Appends a `sessions.reset` signal to `tenant/control`: every process with the Tenant open
+ * checks its session feeds against the Session Store.
+ */
+export declare function signalSessionsReset(streams: DurableStreams, tenantId: string): Promise<void>;

package/dist/streams/relay.js

@@ -0,0 +1,254 @@
+/**
+ * The outbox relay (architecture §12.4, "Writing: outbox and relay").
+ *
+ * The Session Store writes every event to its outbox in the same transaction
+ * as the state change. After the commit the relay appends the events to the
+ * stream of their session's incarnation (`sessions/<id>/<incarnation>`) with
+ * `matchSeq` set to each batch's first sequence, and deletes the rows S2 has:
+ *
+ * - **The right incarnation.** A committed event comes with the incarnation
+ *   its session had when the event was allocated (`Commit.incarnations`).
+ *   Leftover rows (`drain`, and a commit that finds earlier rows still
+ *   waiting) are read with the session's incarnation in one transaction that
+ *   locks the session; deleting a session deletes its outbox rows in the same
+ *   transaction, so those rows belong to the incarnation read. Either way a
+ *   session deleted and created again with the same id never gets the old
+ *   incarnation's events, or the reverse.
+ * - **ok**: the rows are deleted through the last appended sequence, only
+ *   while the session still has the incarnation appended to (one statement,
+ *   `deleteOutbox` with `incarnation`).
+ * - **`seq_mismatch` with the tail past the batch start**: an earlier attempt
+ *   (this process or another) already appended those events. The rows below
+ *   the tail are deleted, and whatever is left of the batch is appended from
+ *   the tail.
+ * - **`seq_mismatch` with the tail before the batch start**: earlier events of
+ *   the session are still in the outbox (an earlier append failed), and the
+ *   session's outbox is relayed in sequence order, which includes this batch.
+ *   If the outbox's first row is past the tail, events are missing from the
+ *   stream: the rows stay and the error goes to `onError`.
+ * - **append throws** (S2 unreachable, basin missing): the rows stay in the
+ *   outbox and the error goes to `onError`. The next commit of the session, or
+ *   the Tenant sweep's `drain`, appends them in order.
+ *
+ * Conditional appends make this exactly-once and in order per session however
+ * many processes relay the same rows. Within one process the relay also runs
+ * one relay at a time per session.
+ *
+ * `work_available`, `session.cancel` and `sessions.reset` are signals, not
+ * canonical events: they skip the outbox (`signalWork`, `signalCancel`,
+ * `signalSessionsReset`). A commit that called `t.signalWork()` is signalled
+ * by the relay after its events.
+ */
+import { decodeCursor } from "../store/cursor.js";
+import { CONTROL_STREAM, WORK_AVAILABLE, WORK_STREAM, streamOfSession, } from "./types.js";
+/** A session's outbox starts past the end of its stream: events are missing from the stream. */
+export class StreamGapError extends Error {
+    constructor(sessionId, first, tail) {
+        super(`Outbox of session ${sessionId} starts at ${first}, past the end of its stream at ${tail}; events before it are missing`);
+        this.name = "StreamGapError";
+    }
+}
+/** At most this many records per append (S2 allows 1000). */
+const MAX_BATCH_RECORDS = 500;
+/** At most this many bytes of JSON per append (S2 allows 1 MiB metered). */
+const MAX_BATCH_BYTES = 768 * 1024;
+/** Outbox rows read per page while relaying one session. */
+const DRAIN_PAGE = 1000;
+export function createRelay(options) {
+    const { store, streams, tenantId } = options;
+    if (store.tenantId !== tenantId)
+        throw new Error(`Relay tenant ${tenantId} does not match store tenant ${store.tenantId}`);
+    const onError = options.onError ?? (() => { });
+    /** sessionId → tail of that session's relay chain. */
+    const chains = new Map();
+    const pending = new Set();
+    let closed = false;
+    /** Runs `task` after every earlier task of the same session. */
+    function serialize(sessionId, task) {
+        const previous = chains.get(sessionId) ?? Promise.resolve();
+        const run = previous.then(task, task);
+        const settled = run.then(() => undefined, () => undefined);
+        chains.set(sessionId, settled);
+        pending.add(settled);
+        void settled.then(() => {
+            pending.delete(settled);
+            if (chains.get(sessionId) === settled)
+                chains.delete(sessionId);
+        });
+        return run;
+    }
+    /**
+     * Appends `rows` (one session, ascending, contiguous) to the stream of `incarnation`
+     * with `matchSeq`, and deletes what S2 has while the session still has that incarnation.
+     * Throws a `StreamGapError` when the stream's tail is before the first row still to append.
+     */
+    async function appendRows(sessionId, incarnation, rows) {
+        const stream = streamOfSession({
+            id: sessionId,
+            ...(incarnation === null ? {} : { streamIncarnation: incarnation }),
+        });
+        const deleteThrough = (seq) => store.tx((t) => t.deleteOutbox(sessionId, seq, incarnation));
+        let rest = rows;
+        while (rest.length > 0) {
+            const batch = takeBatch(rest);
+            const first = batch[0].seq;
+            const last = batch[batch.length - 1].seq;
+            const result = await streams.append(tenantId, stream, batch.map((row) => row.event), { matchSeq: first });
+            if (result.status === "ok") {
+                await deleteThrough(last);
+                rest = rest.slice(batch.length);
+            }
+            else if (result.tail > first) {
+                // Already appended by an earlier attempt: S2 has everything below the tail.
+                await deleteThrough(result.tail - 1);
+                rest = rest.filter((row) => row.seq >= result.tail);
+            }
+            else {
+                throw new StreamGapError(sessionId, first, result.tail);
+            }
+        }
+    }
+    /**
+     * Appends the session's outbox rows in sequence order, at most `limit`, reading them with
+     * the session's incarnation under its lock. Resolves with the number relayed.
+     */
+    async function relaySession(sessionId, limit = Infinity) {
+        let relayed = 0;
+        while (relayed < limit) {
+            const page = Math.min(DRAIN_PAGE, limit - relayed);
+            const read = await store.tx(async (t) => {
+                const session = await t.lockSession(sessionId);
+                // A deleted session took its outbox rows with it.
+                if (!session)
+                    return undefined;
+                return {
+                    incarnation: session.streamIncarnation ?? null,
+                    rows: await t.outbox(page, { sessionId }),
+                };
+            });
+            if (!read || read.rows.length === 0)
+                return relayed;
+            const run = contiguous(read.rows);
+            await appendRows(sessionId, read.incarnation, run);
+            relayed += run.length;
+            // A gap inside the outbox: the next page starts at it and reports it.
+            if (read.rows.length < page && run.length === read.rows.length)
+                return relayed;
+        }
+        return relayed;
+    }
+    /**
+     * Appends one commit's rows of a session to the stream of the incarnation they were
+     * written under. When earlier rows are still in the outbox, relays the whole outbox.
+     */
+    async function relayCommitted(sessionId, incarnation, rows) {
+        try {
+            await appendRows(sessionId, incarnation, contiguous(rows));
+        }
+        catch (error) {
+            if (!(error instanceof StreamGapError))
+                throw error;
+            await relaySession(sessionId);
+        }
+    }
+    function onCommit(commit) {
+        if (closed)
+            return;
+        /** `sessionId\0incarnation` → the commit's rows of that incarnation. */
+        const groups = new Map();
+        commit.events.forEach((event, i) => {
+            let seq;
+            try {
+                seq = decodeCursor(event.sessionId, event.cursor);
+            }
+            catch {
+                onError(new Error(`Event ${event.eventId} has an invalid cursor; left for the sweep`));
+                return;
+            }
+            const incarnation = commit.incarnations[i] ?? null;
+            const key = `${event.sessionId}\u0000${incarnation ?? ""}`;
+            let group = groups.get(key);
+            if (!group)
+                groups.set(key, (group = { sessionId: event.sessionId, incarnation, rows: [] }));
+            group.rows.push({ sessionId: event.sessionId, seq, event });
+        });
+        const relays = [...groups.values()].map(({ sessionId, incarnation, rows }) => {
+            rows.sort((a, b) => a.seq - b.seq);
+            return serialize(sessionId, () => relayCommitted(sessionId, incarnation, rows)).catch(onError);
+        });
+        if (commit.workAvailable) {
+            const signalled = Promise.all(relays)
+                .then(() => signalWork(streams, tenantId))
+                .catch(onError);
+            pending.add(signalled);
+            void signalled.then(() => pending.delete(signalled));
+        }
+    }
+    const unsubscribe = store.onCommit(onCommit);
+    async function idle() {
+        while (pending.size > 0)
+            await Promise.all([...pending]);
+    }
+    return {
+        async drain(limit = 1000) {
+            const rows = await store.tx((t) => t.outbox(limit));
+            const bySession = new Map();
+            for (const row of rows)
+                bySession.set(row.sessionId, (bySession.get(row.sessionId) ?? 0) + 1);
+            const counts = await Promise.all([...bySession].map(([sessionId, count]) => 
+            // Rows may have been relayed since they were read; the conditional
+            // appends skip those.
+            serialize(sessionId, () => relaySession(sessionId, count)).catch((error) => {
+                onError(error);
+                return 0;
+            })));
+            return counts.reduce((sum, n) => sum + n, 0);
+        },
+        idle,
+        async close() {
+            closed = true;
+            unsubscribe();
+            await idle();
+        },
+    };
+}
+/** Appends a `work_available` signal to `tenant/work`. Not relayed through the outbox. */
+export async function signalWork(streams, tenantId) {
+    await streams.append(tenantId, WORK_STREAM, [WORK_AVAILABLE]);
+}
+/** Appends a `session.cancel` signal to `tenant/control`. Not relayed through the outbox. */
+export async function signalCancel(streams, tenantId, sessionId) {
+    if (!sessionId)
+        throw new Error("sessionId is required");
+    const signal = { type: "session.cancel", sessionId };
+    await streams.append(tenantId, CONTROL_STREAM, [signal]);
+}
+/**
+ * Appends a `sessions.reset` signal to `tenant/control`: every process with the Tenant open
+ * checks its session feeds against the Session Store.
+ */
+export async function signalSessionsReset(streams, tenantId) {
+    const signal = { type: "sessions.reset" };
+    await streams.append(tenantId, CONTROL_STREAM, [signal]);
+}
+// ---------------------------------------------------------------------------
+/** The leading run of `rows` (ascending) without a sequence gap. */
+function contiguous(rows) {
+    let n = 1;
+    while (n < rows.length && rows[n].seq === rows[n - 1].seq + 1)
+        n += 1;
+    return rows.slice(0, n);
+}
+/** The leading rows that fit one append. Always at least one row. */
+function takeBatch(rows) {
+    let bytes = 0;
+    let n = 0;
+    while (n < rows.length && n < MAX_BATCH_RECORDS) {
+        const size = JSON.stringify(rows[n].event).length + 8;
+        if (n > 0 && bytes + size > MAX_BATCH_BYTES)
+            break;
+        bytes += size;
+        n += 1;
+    }
+    return rows.slice(0, n);
+}

package/dist/streams/types.d.ts

@@ -0,0 +1,115 @@
+/** A record as read from a stream. */
+export interface StreamRecord<T = unknown> {
+    seq: number;
+    /** Milliseconds since the epoch, as assigned by the stream at append. */
+    timestamp: number;
+    body: T;
+}
+export interface AppendOptions {
+    /** Append only when the stream's tail equals this sequence. */
+    matchSeq?: number;
+}
+export interface AppendAck {
+    status: "ok";
+    /** Sequence of the first appended record. */
+    start: number;
+    /** Sequence after the last appended record (the new tail). */
+    end: number;
+}
+/** A conditional append found the stream elsewhere. Nothing was written. */
+export interface SeqMismatch {
+    status: "seq_mismatch";
+    /** The stream's current tail. */
+    tail: number;
+}
+export type AppendResult = AppendAck | SeqMismatch;
+export interface ReadOptions {
+    /** Ends the read. Iteration then finishes without throwing. */
+    signal?: AbortSignal;
+    /**
+     * `true` (default) keeps reading live records after the history. `false`
+     * stops at the tail observed when the read started (history requests).
+     */
+    follow?: boolean;
+}
+export interface DurableStreams {
+    /**
+     * Appends `records` as one batch. Rejects when the Tenant has no basin or
+     * `records` is empty.
+     */
+    append(tenantId: string, stream: string, records: readonly unknown[], options?: AppendOptions): Promise<AppendResult>;
+    /**
+     * Reads `stream` from `fromSeq`: history first, then (with `follow`) live
+     * records as they are appended, until `signal` aborts. Reading a stream that
+     * does not exist yet waits for its first record.
+     */
+    read<T = unknown>(tenantId: string, stream: string, fromSeq: number, options?: ReadOptions): AsyncIterable<StreamRecord<T>>;
+    /** The sequence the next record will get; 0 for a missing stream. */
+    tail(tenantId: string, stream: string): Promise<number>;
+    /** Creates the Tenant's basin. Idempotent. */
+    ensureTenant(tenantId: string): Promise<void>;
+    /** Deletes the Tenant's basin and all its streams. Idempotent. */
+    deleteTenant(tenantId: string): Promise<void>;
+    /** Deletes one stream (an abandoned session incarnation). Idempotent. */
+    deleteStream(tenantId: string, stream: string): Promise<void>;
+    /**
+     * Names of the Tenant's streams starting with `prefix`, in name order,
+     * without streams being deleted. Empty when the Tenant has no basin.
+     */
+    listStreams(tenantId: string, prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+    /**
+     * Resolves when the backing service answers, rejects otherwise (readiness,
+     * `infra/streams.ts`). Absent for in-process implementations, which are
+     * always reachable.
+     */
+    probe?(signal: AbortSignal): Promise<void>;
+}
+export declare const SESSION_STREAM_PREFIX = "sessions/";
+/** `work_available` signals for executor connections. */
+export declare const WORK_STREAM = "tenant/work";
+/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
+export declare const CONTROL_STREAM = "tenant/control";
+/**
+ * The incarnation of a session document written before incarnations existed.
+ * Random incarnations are 12 characters, so never this.
+ */
+export declare const LEGACY_INCARNATION = "0";
+/** A new session incarnation: 12 random base64url characters. */
+export declare function newStreamIncarnation(): string;
+/** The stream of one incarnation of a session: `sessions/<sessionId>/<incarnation>`. */
+export declare function sessionStream(sessionId: string, incarnation: string): string;
+/** The fields of a session document that name its stream. */
+export interface SessionStreamRef {
+    id: string;
+    /** Set when the session is created (`newStreamIncarnation`); never changed. */
+    streamIncarnation?: string;
+}
+/** The stream of a session as stored now. */
+export declare function streamOfSession(session: SessionStreamRef): string;
+/** The session id and incarnation of a session stream, or undefined for other streams. */
+export declare function parseSessionStream(stream: string): {
+    sessionId: string;
+    incarnation: string;
+} | undefined;
+/**
+ * Signals are not canonical events: they are appended without the outbox, and
+ * a lost signal costs latency, not correctness.
+ */
+export interface WorkSignal {
+    type: "work_available";
+}
+/** Ends the advance of `sessionId` on the process running it. */
+export interface SessionCancelSignal {
+    type: "session.cancel";
+    sessionId: string;
+}
+/**
+ * Session streams were abandoned (a Tenant reset): each process checks its
+ * session feeds and ends those whose session is gone or has a new incarnation.
+ */
+export interface SessionsResetSignal {
+    type: "sessions.reset";
+}
+export type ControlSignal = SessionCancelSignal | SessionsResetSignal;
+export declare const WORK_AVAILABLE: Readonly<WorkSignal>;

package/dist/streams/types.js

@@ -0,0 +1,86 @@
+/**
+ * The Durable Streams seam (architecture §12.4).
+ *
+ * Durable Streams tell everyone else what the Session Store recorded. Each
+ * Tenant has one S2 basin; inside it:
+ *
+ * | Stream | Contents | Written by | Read by |
+ * | --- | --- | --- | --- |
+ * | `sessions/<sessionId>/<incarnation>` | every `LiveEvent` of one incarnation of the session, in sequence | the relay, from the outbox | history and session SSE |
+ * | `tenant/work` | `work_available` signals | API nodes and Workers after committing pending Actions | executor SSE on every API node |
+ * | `tenant/control` | `session.cancel` and `sessions.reset` signals | API nodes | every process with the Tenant open |
+ *
+ * **Incarnations.** A session's stream name carries an incarnation, a random
+ * id stored on the session document when the session is created
+ * (`streamIncarnation`, see `streamOfSession`). A session deleted by a reset
+ * and created again with the same id gets a new incarnation, so a new stream
+ * starting at sequence 0: nothing ever deletes and re-creates the same stream.
+ * Abandoned streams are deleted best effort afterwards
+ * (`collectSessionStreams` in `tenant/streams.ts`). The cursor stays
+ * `base64url("<sessionId>:<seq>")`; readers resolve the incarnation from the
+ * session.
+ *
+ * S2 is the supported implementation (`adapters/streams/s2.ts`, the only file
+ * importing the S2 SDK); `streams/memory.ts` is the in-memory fake.
+ *
+ * ## Guarantees every implementation keeps
+ *
+ * - **Sequence numbers.** Each stream numbers its records from 0 without gaps.
+ *   The tail is the sequence the next appended record gets (0 for a stream
+ *   that does not exist yet).
+ * - **Conditional appends.** With `matchSeq`, a batch is appended only when the
+ *   tail equals `matchSeq`; otherwise nothing is written and the result is a
+ *   `SeqMismatch` carrying the current tail. The relay appends a session
+ *   stream with `matchSeq` set to the outbox row's sequence, so a retried
+ *   append after an unacknowledged success is detected and never duplicated.
+ * - **Batches are atomic.** A batch is appended entirely or not at all.
+ * - **Reads resume.** `read` from `fromSeq` yields every record with
+ *   `seq >= fromSeq` in order, with no gap between history and the live tail.
+ * - **Tenant scope.** `ensureTenant` creates the Tenant's basin (idempotent)
+ *   and must run before appends; streams are created on first append.
+ *   `deleteTenant` removes the basin and every stream in it.
+ * - **Records are JSON.** Bodies are JSON-serializable values; implementations
+ *   encode them as they need.
+ */
+import { randomBytes } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Stream names and signal records
+export const SESSION_STREAM_PREFIX = "sessions/";
+/** `work_available` signals for executor connections. */
+export const WORK_STREAM = "tenant/work";
+/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
+export const CONTROL_STREAM = "tenant/control";
+/**
+ * The incarnation of a session document written before incarnations existed.
+ * Random incarnations are 12 characters, so never this.
+ */
+export const LEGACY_INCARNATION = "0";
+/** A new session incarnation: 12 random base64url characters. */
+export function newStreamIncarnation() {
+    return randomBytes(9).toString("base64url");
+}
+/** The stream of one incarnation of a session: `sessions/<sessionId>/<incarnation>`. */
+export function sessionStream(sessionId, incarnation) {
+    if (!sessionId)
+        throw new Error("sessionId is required");
+    if (!incarnation || incarnation.includes("/"))
+        throw new Error("incarnation must be non-empty and contain no '/'");
+    return `${SESSION_STREAM_PREFIX}${sessionId}/${incarnation}`;
+}
+/** The stream of a session as stored now. */
+export function streamOfSession(session) {
+    return sessionStream(session.id, session.streamIncarnation ?? LEGACY_INCARNATION);
+}
+/** The session id and incarnation of a session stream, or undefined for other streams. */
+export function parseSessionStream(stream) {
+    if (!stream.startsWith(SESSION_STREAM_PREFIX))
+        return undefined;
+    const rest = stream.slice(SESSION_STREAM_PREFIX.length);
+    const slash = rest.lastIndexOf("/");
+    if (slash <= 0 || slash === rest.length - 1)
+        return undefined;
+    return { sessionId: rest.slice(0, slash), incarnation: rest.slice(slash + 1) };
+}
+export const WORK_AVAILABLE = Object.freeze({
+    type: "work_available",
+});

package/dist/tenant/actions.d.ts

@@ -0,0 +1,153 @@
+import type { IncomingMessage } from "node:http";
+import { type RegisterExecutorsRequestSchema } from "@nylorun/core/contracts";
+import { type ExecutorRecord } from "../core/executors.js";
+import { type SandboxRouteDeps } from "../core/sandbox-routes.js";
+import { type AuthScope, type TenantContext } from "./context.js";
+type RegisterExecutorsRequest = ReturnType<typeof RegisterExecutorsRequestSchema.parse>;
+/** Session and Action lookups for the sandbox route handlers. */
+export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;
+/** `GET /v1/actions`: the pending Actions of the executor's agent. */
+export declare function listPendingActions(ctx: TenantContext, executor: ExecutorRecord): Promise<{
+    actions: ({
+        actionId: string;
+        sessionId: string;
+        turnId: string;
+        agentId: string;
+        manifestHash: string;
+        implementationVersion: string;
+        input: unknown;
+        context: Record<string, unknown>;
+        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
+        generation: number;
+        claimId: string | null;
+        leaseExpiresAt: string | null;
+        agent?: {
+            id: string;
+            path: string;
+            delegationId?: string | undefined;
+        } | undefined;
+        kind: "tool";
+        capabilityId: string;
+        toolName: string;
+        inputSchema?: Record<string, unknown> | undefined;
+        outputSchema?: Record<string, unknown> | undefined;
+    } | {
+        actionId: string;
+        sessionId: string;
+        turnId: string;
+        agentId: string;
+        manifestHash: string;
+        implementationVersion: string;
+        input: unknown;
+        context: Record<string, unknown>;
+        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
+        generation: number;
+        claimId: string | null;
+        leaseExpiresAt: string | null;
+        agent?: {
+            id: string;
+            path: string;
+            delegationId?: string | undefined;
+        } | undefined;
+        kind: "tool";
+        path: string;
+        key: string;
+        inputSchema?: Record<string, unknown> | undefined;
+        outputSchema?: Record<string, unknown> | undefined;
+    } | {
+        actionId: string;
+        sessionId: string;
+        turnId: string;
+        agentId: string;
+        manifestHash: string;
+        implementationVersion: string;
+        input: unknown;
+        context: Record<string, unknown>;
+        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
+        generation: number;
+        claimId: string | null;
+        leaseExpiresAt: string | null;
+        agent?: {
+            id: string;
+            path: string;
+            delegationId?: string | undefined;
+        } | undefined;
+        kind: "hook";
+        hook: {
+            at: "after" | "before";
+            scope: "step" | "turn";
+            capabilityIds: string[];
+        };
+    } | {
+        actionId: string;
+        sessionId: string;
+        turnId: string;
+        agentId: string;
+        manifestHash: string;
+        implementationVersion: string;
+        input: unknown;
+        context: Record<string, unknown>;
+        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
+        generation: number;
+        claimId: string | null;
+        leaseExpiresAt: string | null;
+        agent?: {
+            id: string;
+            path: string;
+            delegationId?: string | undefined;
+        } | undefined;
+        kind: "fn";
+        path: string;
+        key: string;
+    } | {
+        actionId: string;
+        sessionId: string;
+        turnId: string;
+        agentId: string;
+        manifestHash: string;
+        implementationVersion: string;
+        input: unknown;
+        context: Record<string, unknown>;
+        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
+        generation: number;
+        claimId: string | null;
+        leaseExpiresAt: string | null;
+        agent?: {
+            id: string;
+            path: string;
+            delegationId?: string | undefined;
+        } | undefined;
+        kind: "verify";
+        path: string;
+        key: string;
+    })[];
+}>;
+/** `POST /v1/actions/:id/sandbox/:tool`: a claim-scoped sandbox tool call. */
+export declare function actionSandboxTool(ctx: TenantContext, scope: AuthScope, actionId: string, toolName: string, request: IncomingMessage): Promise<import("../sandbox/tools.js").SandboxToolOutcome>;
+/** `POST /v1/actions/:id/claim` and `/heartbeat`; anything else under the Action is a 404. */
+export declare function updateAction(ctx: TenantContext, scope: AuthScope, actionId: string, method: string | undefined, operation: string | undefined, body: unknown): Promise<unknown>;
+/** `GET /v1/executors`. */
+export declare function listExecutors(ctx: TenantContext): {
+    executors: {
+        agentId: string;
+        implementationVersion: string;
+        manifestHash?: string | undefined;
+        connected: boolean;
+        updatedAt: string;
+    }[];
+};
+/** `PUT /v1/executors`: persist the batch, then update the registry and end rotated streams. */
+export declare function registerExecutors(ctx: TenantContext, principalId: string, body: RegisterExecutorsRequest): Promise<{
+    executors: {
+        agentId: string;
+        implementationVersion: string;
+        rotated: boolean;
+        replacedBy?: "different-credential" | undefined;
+    }[];
+}>;
+/** `DELETE /v1/executors/:agentId`: forget the executor and end its streams. */
+export declare function deleteExecutor(ctx: TenantContext, agentId: string): Promise<{
+    agentId: string;
+    deleted: boolean;
+}>;
+export {};