@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/session-streams.js

@@ -0,0 +1,404 @@
+import { decodeCursor, encodeCursor } from "../record/index.js";
+import { basinOf } from "../streams/basin.js";
+import { sessionStream, } from "../streams/types.js";
+import { fail } from "./http.js";
+export function createSessionStreams() {
+    return { wiring: undefined, generation: 0, sessions: new Map() };
+}
+const RETRY_MIN_MS = 100;
+const RETRY_MAX_MS = 2000;
+function frame(event) {
+    return `id: ${event.cursor}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+export function send(response, data) {
+    if (!response.write(data))
+        response.destroy();
+}
+/** The frame that tells a client why the Runtime ended its stream (no `id:`: not an event). */
+function closedFrame(reason) {
+    return `event: nylorun.closed\ndata: ${JSON.stringify({ reason })}\n\n`;
+}
+/** An observer sink writing SSE frames to `response`. */
+function sseSink(response) {
+    return {
+        write: (event) => send(response, frame(event)),
+        end: (reason) => {
+            if (reason && !response.writableEnded)
+                send(response, closedFrame(reason));
+            response.end();
+        },
+    };
+}
+/** Start an SSE response with keepalives; `onClose` runs once the client goes away. */
+export function openSse(request, response, onClose) {
+    response.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+        "x-accel-buffering": "no",
+    });
+    response.flushHeaders();
+    const timer = setInterval(() => send(response, ": keepalive\n\n"), 15000);
+    timer.unref();
+    request.on("close", () => {
+        clearInterval(timer);
+        onClose();
+    });
+}
+/** The resume cursor: `?cursor=` wins over `Last-Event-ID`. */
+export function requestCursor(request, url) {
+    return (url.searchParams.get("cursor") ??
+        (typeof request.headers["last-event-id"] === "string"
+            ? request.headers["last-event-id"]
+            : undefined));
+}
+/** The first sequence to read: after the cursor's, or the session's first event. */
+function startSeq(sessionId, cursor) {
+    return cursor ? decodeCursor(sessionId, cursor) + 1 : 0;
+}
+/** `agent` keeps only events of one agent used as a tool, by delegationId or path. */
+function belongsTo(event, agent) {
+    const ref = event.payload?.agent;
+    return ref?.delegationId === agent || ref?.path === agent;
+}
+/** The basin the Tenant's session streams are in now. */
+export function currentBasin(ctx) {
+    return basinOf(ctx.config.tenantId, ctx.sessionStreams.generation);
+}
+/** The session's stream now, or undefined when the session is gone. */
+async function currentStream(ctx, sessionId) {
+    const session = await ctx.store.tx((t) => t.get("sessions", sessionId));
+    return session && { basin: currentBasin(ctx), stream: sessionStream(sessionId) };
+}
+const sameStream = (feed, ref) => ref !== undefined && ref.basin === feed.basin && ref.stream === feed.stream;
+function streamsOf(ctx) {
+    return (ctx.sessionStreams.wiring?.streams ?? fail(503, "Session streams are unavailable"));
+}
+/**
+ * `GET /v1/sessions/:id/items`: the session stream after the cursor, up to its tail when the
+ * read starts. The cursor returned is the last record read (the request's cursor when none
+ * was), whatever the `agent` filter kept.
+ */
+export async function readHistory(ctx, sessionId, cursor, agent) {
+    const from = startSeq(sessionId, cursor);
+    const streams = streamsOf(ctx);
+    const ref = (await currentStream(ctx, sessionId)) ?? fail(404, "Session not found");
+    const items = [];
+    let last;
+    try {
+        for await (const record of streams.read(ref.basin, ref.stream, from, { follow: false })) {
+            last = record.seq;
+            if (served(record.body) && (agent === undefined || belongsTo(record.body, agent)))
+                items.push(record.body);
+        }
+    }
+    catch (error) {
+        ctx.config.logger.warn("session history read failed", {
+            sessionId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        fail(503, "Session history is unavailable");
+    }
+    return {
+        items,
+        cursor: last !== undefined ? encodeCursor(sessionId, last) : cursor ?? null,
+    };
+}
+/**
+ * `GET /v1/sessions/:id/events`: joins the session's shared read at the client's cursor and
+ * follows it until the client leaves, the session is reset or deleted, or the Tenant closes.
+ */
+export async function streamSessionEvents(ctx, request, response, sessionId, cursor, holder) {
+    const observer = {
+        sink: sseSink(response),
+        next: startSeq(sessionId, cursor),
+        ...(holder ? { holder } : {}),
+    };
+    const joined = await join(ctx, sessionId, observer);
+    openSse(request, response, () => leave(ctx.sessionStreams, joined, observer));
+    armDeadline(ctx.sessionStreams, joined, observer);
+}
+/** Thrown by `observeSession` when the Runtime ended the stream for its token. */
+export class StreamClosed extends Error {
+    reason;
+    cursor;
+    constructor(reason, 
+    /** The cursor of the last event delivered, if any. */
+    cursor) {
+        super(`The stream ended: ${reason}`);
+        this.reason = reason;
+        this.cursor = cursor;
+        this.name = "StreamClosed";
+    }
+}
+/**
+ * A session's events from `cursor`, in process: the same shared read and deadlines as an SSE
+ * client (`streamSessionEvents`). Ends when `signal` aborts or the feed ends; throws
+ * `StreamClosed` when the Runtime ends it for its token (expiry or revocation).
+ */
+export async function* observeSession(ctx, sessionId, cursor, options) {
+    const queue = [];
+    let ended;
+    let wake;
+    const notify = () => {
+        const resolve = wake;
+        wake = undefined;
+        resolve?.();
+    };
+    const observer = {
+        sink: {
+            write: (event) => {
+                queue.push(event);
+                notify();
+            },
+            end: (reason) => {
+                ended = reason ? { reason } : {};
+                notify();
+            },
+        },
+        next: startSeq(sessionId, cursor),
+        ...(options.holder ? { holder: options.holder } : {}),
+    };
+    const joined = await join(ctx, sessionId, observer);
+    armDeadline(ctx.sessionStreams, joined, observer);
+    const stop = () => {
+        leave(ctx.sessionStreams, joined, observer);
+        notify();
+    };
+    options.signal.addEventListener("abort", stop, { once: true });
+    let last = cursor;
+    try {
+        for (;;) {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                last = event.cursor;
+                yield event;
+            }
+            if (options.signal.aborted)
+                return;
+            if (ended) {
+                if (ended.reason)
+                    throw new StreamClosed(ended.reason, last);
+                return;
+            }
+            await new Promise((resolve) => (wake = resolve));
+        }
+    }
+    finally {
+        options.signal.removeEventListener("abort", stop);
+        leave(ctx.sessionStreams, joined, observer);
+    }
+}
+/** Ends the observer when its token expires. */
+function armDeadline(hub, feed, observer) {
+    if (!observer.holder)
+        return;
+    observer.deadline = setTimeout(() => endObserver(hub, feed, observer, "token_expired"), Math.max(0, observer.holder.expiresAt - Date.now()));
+    observer.deadline.unref();
+}
+/**
+ * Adds `observer` to the session's shared read, starting or restarting it from the
+ * observer's position when needed. 404 when the session has no stream.
+ */
+async function join(ctx, sessionId, observer) {
+    const from = observer.next;
+    streamsOf(ctx);
+    const ref = (await currentStream(ctx, sessionId)) ?? fail(404, "Session not found");
+    const hub = ctx.sessionStreams;
+    let feed = hub.sessions.get(sessionId);
+    if (feed && !sameStream(feed, ref)) {
+        // The Tenant moved to a new basin since that feed started: it follows an abandoned stream.
+        endFeed(hub, feed);
+        feed = undefined;
+    }
+    if (!feed) {
+        feed = {
+            sessionId,
+            basin: ref.basin,
+            stream: ref.stream,
+            next: from,
+            observers: new Set(),
+            read: new AbortController(),
+        };
+        hub.sessions.set(sessionId, feed);
+        runFeed(ctx, feed);
+    }
+    else if (from < feed.next) {
+        // Behind the shared read: restart it here; observers ahead skip what they have.
+        feed.read.abort();
+        feed.read = new AbortController();
+        feed.next = from;
+        runFeed(ctx, feed);
+    }
+    feed.observers.add(observer);
+    return feed;
+}
+/** Ends one observer early (its token expired or was revoked). */
+function endObserver(hub, feed, observer, reason) {
+    if (!feed.observers.has(observer))
+        return;
+    leave(hub, feed, observer);
+    observer.sink.end(reason);
+}
+function leave(hub, feed, observer) {
+    if (observer.deadline)
+        clearTimeout(observer.deadline);
+    if (!feed.observers.delete(observer))
+        return;
+    if (feed.observers.size > 0)
+        return;
+    feed.read.abort();
+    if (hub.sessions.get(feed.sessionId) === feed)
+        hub.sessions.delete(feed.sessionId);
+}
+function deliver(observer, record) {
+    if (record.seq < observer.next)
+        return;
+    observer.next = record.seq + 1;
+    if (served(record.body))
+        observer.sink.write(record.body);
+}
+/** Internal events (`transcript.updated`) are recorded and streamed but never served. */
+export function served(event) {
+    return event.visibility !== "internal";
+}
+/**
+ * Follows the feed's stream from `feed.next` for the current `feed.read`, retrying failed
+ * reads from where it stopped while the session still has that stream. A read that ends by
+ * itself (the stream's Tenant is gone or the streams closed), or a session that is gone or
+ * whose Tenant moved to a new basin, ends the observers.
+ */
+function runFeed(ctx, feed) {
+    const read = feed.read;
+    const signal = read.signal;
+    void (async () => {
+        let delay = RETRY_MIN_MS;
+        while (!signal.aborted) {
+            const streams = ctx.sessionStreams.wiring?.streams;
+            if (!streams)
+                break;
+            try {
+                for await (const record of streams.read(feed.basin, feed.stream, feed.next, { signal })) {
+                    // A restart replaced this read: the new one owns `feed.next`.
+                    if (signal.aborted || feed.read !== read)
+                        return;
+                    if (record.seq < feed.next)
+                        continue;
+                    feed.next = record.seq + 1;
+                    delay = RETRY_MIN_MS;
+                    for (const observer of feed.observers)
+                        deliver(observer, record);
+                }
+                if (signal.aborted)
+                    return;
+                break;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                ctx.config.logger.warn("session stream read failed; retrying", {
+                    sessionId: feed.sessionId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            if (!(await stillCurrent(ctx, feed)))
+                break;
+            await sleep(delay, signal);
+            delay = Math.min(delay * 2, RETRY_MAX_MS);
+        }
+        if (signal.aborted || feed.read !== read)
+            return;
+        endFeed(ctx.sessionStreams, feed);
+    })();
+}
+/** False when the feed's session is gone or the Tenant moved to a new basin. True when unsure. */
+async function stillCurrent(ctx, feed) {
+    try {
+        return sameStream(feed, await currentStream(ctx, feed.sessionId));
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Ends every feed in this process whose session is gone or whose Tenant moved to a new basin
+ * generation, and moves this process to the Tenant's current generation. Run on a
+ * `sessions.reset` signal and periodically, so feeds on nodes other than the one that reset
+ * the Tenant end too.
+ */
+export async function checkSessionStreams(ctx) {
+    const feeds = [...ctx.sessionStreams.sessions.values()];
+    // Also a backstop for lost `subject.revoked` signals: the holders' current epochs.
+    const subjects = new Set();
+    for (const feed of feeds)
+        for (const observer of feed.observers)
+            if (observer.holder)
+                subjects.add(observer.holder.subject);
+    const { exists, epochs, generation } = await ctx.store.tx(async (t) => {
+        const exists = new Set();
+        for (const feed of feeds)
+            if (await t.get("sessions", feed.sessionId))
+                exists.add(feed.sessionId);
+        return {
+            exists,
+            generation: (await t.basinGenerations()).current,
+            epochs: subjects.size === 0
+                ? new Map()
+                : await t.subjectEpochs([...subjects]),
+        };
+    });
+    if (generation !== ctx.sessionStreams.generation)
+        ctx.sessionStreams.wiring?.moveTo(generation);
+    for (const feed of feeds)
+        if (ctx.sessionStreams.sessions.get(feed.sessionId) === feed &&
+            !sameStream(feed, exists.has(feed.sessionId)
+                ? { basin: currentBasin(ctx), stream: sessionStream(feed.sessionId) }
+                : undefined))
+            endFeed(ctx.sessionStreams, feed);
+    for (const [subject, epoch] of epochs)
+        endSubjectStreams(ctx.sessionStreams, subject, epoch);
+}
+/**
+ * Ends the streams of `subject` opened with a token older than `epoch` (a revocation), on
+ * this process. Other processes do the same on the `subject.revoked` signal.
+ */
+export function endSubjectStreams(hub, subject, epoch) {
+    for (const feed of [...hub.sessions.values()])
+        for (const observer of [...feed.observers])
+            if (observer.holder?.subject === subject && observer.holder.epoch < epoch)
+                endObserver(hub, feed, observer, "revoked");
+}
+function endFeed(hub, feed) {
+    feed.read.abort();
+    if (hub.sessions.get(feed.sessionId) === feed)
+        hub.sessions.delete(feed.sessionId);
+    for (const observer of feed.observers) {
+        if (observer.deadline)
+            clearTimeout(observer.deadline);
+        observer.sink.end();
+    }
+    feed.observers.clear();
+}
+/** Reset or close: end every session observer and stop every shared read. */
+export function clearObservers(hub) {
+    for (const feed of [...hub.sessions.values()])
+        endFeed(hub, feed);
+    hub.sessions.clear();
+}
+/** Close: end every session observer. */
+export function endAllStreams(hub) {
+    clearObservers(hub);
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}

package/dist/tenant/sessions.d.ts

@@ -5,7 +5,7 @@
  */
 import { type PutAgentRequest, type PutSessionRequest } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
-import { type Session, type TenantContext } from "./context.js";
+import { type Session, type SessionAccess, type TenantContext } from "./context.js";
 export declare function listDefinitions(ctx: TenantContext): Promise<{
     agents: {
         agentId: any;
@@ -14,13 +14,27 @@ export declare function listDefinitions(ctx: TenantContext): Promise<{
         implementationVersion: string;
     }[];
 }>;
+/**
+ * The agents a subject token or publishable key may see: id, name and description only, never
+ * instructions, tools or MCP servers, and only the agents allowed.
+ */
+export declare function listAgentsPublic(ctx: TenantContext, agents: ReadonlySet<string> | "*"): Promise<{
+    agents: {
+        agentId: string;
+        name?: any;
+        description?: any;
+    }[];
+}>;
 export declare function putDefinition(ctx: TenantContext, agentId: string, body: PutAgentRequest): Promise<{
     agentId: string;
     manifestHash: string;
     implementationVersion: string;
 }>;
-/** `owner`, when the request acts for a subject, limits the list to that subject's sessions. */
-export declare function listSessions(ctx: TenantContext, agentId: string | null, owner?: string): Promise<{
+/**
+ * `access`, when the request acts for a person, limits the list to that person's sessions of
+ * the agents they may use.
+ */
+export declare function listSessions(ctx: TenantContext, agentId: string | null, access?: SessionAccess): Promise<{
     sessions: {
         id: string;
         agentId: string;
@@ -34,7 +48,17 @@ export declare function listSessions(ctx: TenantContext, agentId: string | null,
  * the request acts for a subject, must be the session's owner: another owner's session id is
  * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
  * sandboxes.
+ *
+ * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
+ * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
+ * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
  */
-export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, owner?: string): Promise<Session>;
+export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, access?: SessionAccess, options?: {
+    /**
+     * Create the session if it is missing and otherwise leave it as it is (an AG-UI thread's
+     * session): an existing one must have the same owner and agent, or it is a 404.
+     */
+    createOnly?: boolean;
+}): Promise<Session>;
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export declare function sessionView(t: Tx, s: Session): Promise<unknown>;

package/dist/tenant/sessions.js

@@ -7,9 +7,12 @@ import { DefinitionDocumentSchema, } from "@nylorun/core/contracts";
 import { hashManifest } from "@nylorun/core/compatibility";
 import { aggregateWaits, isWorkflowManifest } from "../core/flow-host.js";
 import { canonical } from "../store/canonical.js";
-import { newStreamIncarnation } from "../streams/types.js";
 import { validateSandboxAttach } from "../core/sandbox-routes.js";
-import { sandboxLookup } from "./context.js";
+import { resolveSandbox } from "../sandbox/resolve.js";
+import { withSandboxCapability } from "../sandbox/session-sandbox.js";
+import { declaredSandboxes, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
+import { sandboxLookup, } from "./context.js";
 import { fail } from "./http.js";
 /** A session's creation identity: everything but the request id and vault attachments. */
 const sessionIdentity = (value) => {
@@ -27,10 +30,31 @@ export async function listDefinitions(ctx) {
         })),
     };
 }
+/**
+ * The agents a subject token or publishable key may see: id, name and description only, never
+ * instructions, tools or MCP servers, and only the agents allowed.
+ */
+export async function listAgentsPublic(ctx, agents) {
+    const definitions = await ctx.store.tx((t) => t.listDefinitions());
+    return {
+        agents: definitions
+            .filter((d) => agents === "*" || agents.has(d.manifest.id))
+            .map((d) => ({
+            agentId: d.manifest.id,
+            ...(typeof d.manifest.name === "string" ? { name: d.manifest.name } : {}),
+            ...(typeof d.manifest.description === "string"
+                ? { description: d.manifest.description }
+                : {}),
+        })),
+    };
+}
 export async function putDefinition(ctx, agentId, body) {
     if (body.manifest.id !== agentId)
         fail(400, "Agent id mismatch");
     DefinitionDocumentSchema.parse(body.manifest);
+    const declared = declaredSandboxes(body.manifest);
+    if (declared.length > 0)
+        fail(400, `${declared.join(", ")} declares a sandbox. Agents no longer declare one: remove .sandbox() and open the session with it, createSession({ sandbox: { image, network: { allow }, resources } }), or set the Tenant's default sandbox. See MIGRATION.md.`);
     const definition = {
         ...body,
         manifestHash: hashManifest(body.manifest),
@@ -42,14 +66,20 @@ export async function putDefinition(ctx, agentId, body) {
         implementationVersion: body.implementationVersion,
     };
 }
-/** `owner`, when the request acts for a subject, limits the list to that subject's sessions. */
-export async function listSessions(ctx, agentId, owner) {
+/**
+ * `access`, when the request acts for a person, limits the list to that person's sessions of
+ * the agents they may use.
+ */
+export async function listSessions(ctx, agentId, access) {
     const sessions = await ctx.store.tx((t) => t.listSessions({
         ...(agentId === null ? {} : { agentId }),
-        ...(owner === undefined ? {} : { ownerUserId: owner }),
+        ...(access === undefined ? {} : { ownerUserId: access.owner }),
     }));
+    const allowed = access?.agents;
     return {
-        sessions: sessions.map((s) => ({
+        sessions: sessions
+            .filter((s) => allowed === undefined || allowed.has(s.agentId))
+            .map((s) => ({
             id: s.id,
             agentId: s.agentId,
             ownerUserId: s.ownerUserId,
@@ -63,24 +93,33 @@ export async function listSessions(ctx, agentId, owner) {
  * the request acts for a subject, must be the session's owner: another owner's session id is
  * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
  * sandboxes.
+ *
+ * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
+ * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
+ * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
  */
-export function putSession(ctx, id, body, owner) {
+export async function putSession(ctx, id, body, access, options = {}) {
     const vaultIds = body.vaultIds ?? [];
     const credentialSelections = body.credentialSelections ?? [];
-    const opaque = owner !== undefined;
-    if (opaque && body.ownerUserId !== owner)
+    const opaque = access !== undefined;
+    if (opaque && body.ownerUserId !== access.owner)
         fail(403, "ownerUserId must be the subject");
+    // An agent the subject may not use is the 404 of a missing definition.
+    if (access?.agents !== undefined && !access.agents.has(body.agentId))
+        fail(404, "Definition not found");
     return ctx.store.tx(async (t) => {
         const prior = await t.lockSession(id);
-        if (opaque && prior && prior.ownerUserId !== owner)
+        if (opaque &&
+            prior &&
+            (prior.ownerUserId !== access.owner ||
+                (access.agents !== undefined && !access.agents.has(prior.agentId))))
             fail(404, "Session not found");
-        const definition = prior === undefined || body.sandbox
-            ? (await t.get("definitions", body.agentId)) ??
-                fail(404, "Definition not found")
-            : undefined;
-        const sandboxOwnerId = body.sandbox
-            ? validateSandboxAttach(body, (definition ?? prior).manifest, await sandboxLookup(t, body.sandbox.session), { opaque })
-            : undefined;
+        if (prior && options.createOnly) {
+            if (prior.ownerUserId !== body.ownerUserId ||
+                prior.agentId !== body.agentId)
+                fail(404, "Session not found");
+            return prior;
+        }
         await ctx.vault.assertAttachment(t, body.ownerUserId, vaultIds, credentialSelections, { opaque });
         if (prior) {
             if (sessionIdentity(prior.creation) !== sessionIdentity(body))
@@ -88,18 +127,19 @@ export function putSession(ctx, id, body, owner) {
             prior.vaultIds = vaultIds;
             prior.credentialSelections = credentialSelections;
             prior.creation = body;
-            if (sandboxOwnerId !== undefined)
-                prior.sandboxOwnerId = sandboxOwnerId;
             await t.put("sessions", id, prior);
             await ctx.vault.recordAttachment(t, id, vaultIds);
             return prior;
         }
+        const definition = (await t.get("definitions", body.agentId)) ??
+            fail(404, "Definition not found");
+        const sandbox = await sessionSandbox(t, body, definition, { opaque });
         const created = {
             id,
             agentId: body.agentId,
             ownerUserId: body.ownerUserId,
-            manifest: definition.manifest,
-            manifestHash: definition.manifestHash,
+            manifest: sandbox.manifest ?? definition.manifest,
+            manifestHash: sandbox.manifestHash ?? definition.manifestHash,
             implementationVersion: definition.implementationVersion,
             info: body.info,
             status: "idle",
@@ -108,14 +148,66 @@ export function putSession(ctx, id, body, owner) {
             vaultIds,
             credentialSelections,
             pluginRoots: definition.pluginRoots ?? {},
-            ...(sandboxOwnerId !== undefined ? { sandboxOwnerId } : {}),
-            streamIncarnation: newStreamIncarnation(),
+            ...(sandbox.sandboxOwnerId !== undefined
+                ? { sandboxOwnerId: sandbox.sandboxOwnerId }
+                : {}),
+            ...(sandbox.spec !== undefined
+                ? { sandbox: sandbox.spec, sandboxSource: sandbox.source }
+                : {}),
         };
         await t.put("sessions", id, created);
         await ctx.vault.recordAttachment(t, id, vaultIds);
         return created;
     });
 }
+function isShare(value) {
+    return typeof value === "object" && value !== null && "session" in value;
+}
+/** Decide a new session's sandbox and, for an agent, the manifest that carries its tools. */
+async function sessionSandbox(t, body, definition, options) {
+    const request = body.sandbox;
+    const declared = sandboxSpecOf(definition.manifest) !== undefined;
+    if (isShare(request)) {
+        const lookup = await sandboxLookup(t, request.session);
+        const sandboxOwnerId = validateSandboxAttach(body, definition.manifest, lookup, {
+            opaque: options.opaque,
+            inherit: !declared,
+        });
+        if (declared || sandboxOwnerId === undefined)
+            return { sandboxOwnerId };
+        const spec = sessionSandboxSpec(lookup(request.session));
+        return { ...(await pin(definition, spec, "shared")), sandboxOwnerId };
+    }
+    if (declared) {
+        if (request !== undefined)
+            fail(400, `'${body.agentId}' declares its own sandbox with .sandbox(). Remove it from the agent to choose the sandbox when opening the session, or omit sandbox here.`);
+        return {};
+    }
+    const resolved = resolveSandbox({
+        request,
+        config: effectiveSandboxConfig(await readSandboxConfig(t)),
+        actingForSubject: options.opaque,
+    });
+    if (resolved.kind === "none")
+        return {};
+    if (resolved.kind === "error")
+        return fail(resolved.status, resolved.errors.join(" "));
+    return pin(definition, resolved.spec, resolved.source);
+}
+async function pin(definition, spec, source) {
+    // A workflow's manifest stays as registered: Action endpoints match workflow actions by its hash.
+    if (isWorkflowManifest(definition.manifest))
+        return { spec, source };
+    const sandboxed = withSandboxCapability(definition.manifest, spec);
+    if (!sandboxed.ok)
+        return fail(400, sandboxed.message);
+    return {
+        spec,
+        source,
+        manifest: sandboxed.manifest,
+        manifestHash: sandboxed.manifestHash,
+    };
+}
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export async function sessionView(t, s) {
     let waits = Array.isArray(s.waits)
@@ -132,7 +224,7 @@ export async function sessionView(t, s) {
             waits = aggregated;
     }
     const actions = await t.actionsForSession(s.id, {
-        statuses: ["pending", "claimed", "uncertain"],
+        statuses: ["pending", "delivering", "uncertain"],
     });
     const uncertain = await t.effectsForSession(s.id, {
         statuses: ["uncertain"],
@@ -148,6 +240,8 @@ export async function sessionView(t, s) {
         vaultIds: s.vaultIds ?? [],
         credentialSelections: s.credentialSelections ?? [],
         sandboxOwnerId: s.sandboxOwnerId ?? null,
+        sandbox: s.sandbox ?? null,
+        ...(s.sandboxSource ? { sandboxSource: s.sandboxSource } : {}),
         mcpSnapshot: s.mcpSnapshot ?? null,
         mcpDiagnostics: s.mcpDiagnostics ?? [],
         waits,