@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/cause.js

@@ -0,0 +1,45 @@
+/** Thrown by migrations, the Tenant bootstrap and the Tenant Runtime when the Tenant cannot open. */
+export class TenantOpenError extends Error {
+    code;
+    repair;
+    /** The Tenant, when it was read before opening failed (`/v1/admin/status` names it). */
+    envelope;
+    constructor(fields) {
+        super(fields.message);
+        this.name = "TenantOpenError";
+        this.code = fields.code;
+        this.repair = fields.repair;
+    }
+    toCause() {
+        return { code: this.code, message: this.message, repair: this.repair };
+    }
+}
+/** A `TenantOpenError` with the standard repair for `code`. */
+export function openError(code, message) {
+    return new TenantOpenError({ code, message, repair: repairFor(code) });
+}
+/** The cause an error carries, when it is a `TenantOpenError`. */
+export function causeOf(error) {
+    return error instanceof TenantOpenError ? error.toCause() : undefined;
+}
+/** What an operator does about each cause. */
+export function repairFor(code) {
+    switch (code) {
+        case "kek-missing":
+            return "restore the vault key (vault-kek in the Host root's keys/ directory) from a backup, then restart the Runtime and its gateway: the Tenant's ciphertext cannot be opened without it";
+        case "corrupt":
+            return "restore the database from a backup, then restart the Runtime";
+        case "schema-too-new":
+            return "the database was migrated by a newer Runtime: run that version or newer";
+        case "migration-failed":
+            return "inspect the Runtime log for the failed migration, fix it, then restart the Runtime";
+        case "envelope-invalid":
+            return "the nylorun.tenant row is missing or invalid: restore the database from a backup";
+        case "open-timeout":
+            return "opening the Tenant timed out: inspect the Runtime log and Postgres, then restart the Runtime";
+        case "open-failed":
+            return "inspect the Runtime log, repair what it names, then restart the Runtime";
+        case "database-layout-old":
+            return "this release starts fresh: point the Runtime at a new database (a new stack: `nylorun start`); the old database is left as it is";
+    }
+}

package/dist/tenant/commands.d.ts

@@ -1,3 +1,19 @@
-import type { SessionCommand } from "@nylorun/core/contracts";
-import { type AuthScope, type TenantContext } from "./context.js";
+import type { Action, ActionOutcome, LiveEvent, SessionCommand } from "@nylorun/core/contracts";
+import type { Tx } from "../store/types.js";
+import { type AuthScope, type Session, type TenantContext } from "./context.js";
+/** `outcome`, or a failed one when a tool's output does not match its stored output schema. */
+export declare function acceptedOutcome(action: Action, outcome: ActionOutcome): ActionOutcome;
 export declare function command(ctx: TenantContext, id: string, input: SessionCommand, scope: AuthScope): Promise<unknown>;
+/**
+ * Completes a delivered Action with `outcome`, in the caller's transaction, which
+ * holds the lock of the Action's session `s`: the Action and its effect, the
+ * `action.completed` event (and `loop.verified` or `loop.decided`), the wake that resumes the
+ * turn, and queued workflow effects. The Action deliverer and the background-result callback
+ * both record outcomes here. It sets `s.status`; the caller writes `s`.
+ */
+export declare function recordActionOutcome(t: Tx, ctx: TenantContext, s: Session, action: Action, received: ActionOutcome, options?: {
+    requestId?: string;
+}): Promise<{
+    event: LiveEvent;
+    receipt: Record<string, unknown>;
+}>;

package/dist/tenant/commands.js

@@ -1,5 +1,5 @@
 /**
- * The session command service: `message`, `approve`/`respond`, `action_result` and `cancel`,
+ * The session command service: `message`, `approve`/`respond` and `cancel`,
  * with per-session idempotency keys. A command locks its session and commits its state
  * change, events and wakes in one transaction (the store publishes the events and runs the
  * `afterCommit` wakes), then aborts a cancelled advance and cascades workflow cancels to the
@@ -7,8 +7,9 @@
  *
  * Wakes (`ctx.wake`, architecture §12.3) carry the command type as the reason and a dedupe
  * key naming the cause: `<type>:<turnId>:<segment>` for `message`, `approve` and `respond`
- * (every accepted one writes a new checkpoint segment), and
- * `action_result:<turnId>:<actionId>:<generation>` for executor results.
+ * (every accepted one writes a new checkpoint segment). An Action's outcome
+ * (`recordActionOutcome`, from the deliverer) wakes with
+ * `action_result:<turnId>:<actionId>:<generation>`.
  *
  * Cancel commits `cancelled` first; the engine host sees it before its next effect and before
  * settlement on any Worker. It then aborts an advance running on this process
@@ -22,19 +23,21 @@ import { resolveMessageManifest } from "../core/turn-manifest.js";
 import { canonical } from "../store/canonical.js";
 import { lockedSession, } from "./context.js";
 import { fail } from "./http.js";
-import { ownerOf, scoped } from "./auth.js";
+import { accessOf } from "./auth.js";
+import { chargeTurn } from "./subject-limits.js";
 import { actionTarget, rebaseSessionState, turnManifestOf, variantStore, } from "./session.js";
 import { signalSessionCancel } from "./streams.js";
 import { toolIds } from "./transcript.js";
-/** A tool result whose output does not match the Action's stored output schema fails the tool. */
-function acceptedToolResult(action, command) {
+import { slimModelEffects } from "./slim.js";
+/** `outcome`, or a failed one when a tool's output does not match its stored output schema. */
+export function acceptedOutcome(action, outcome) {
     if (action.kind !== "tool" || !action.outputSchema)
-        return command;
-    const value = command.outcome.value;
+        return outcome;
+    const value = outcome.value;
     // Only a result carries output: failures, denials, interactions and deferrals pass as sent.
     if (!isResultToolValue(value))
-        return command;
-    // Executors wrap successful tool output as `{ kind: "completed", output }`.
+        return outcome;
+    // Endpoints wrap successful tool output as `{ kind: "completed", output }`.
     // Validate the tool payload, not the outcome envelope.
     const candidate = completedToolOutput(value);
     let matches = false;
@@ -45,16 +48,13 @@ function acceptedToolResult(action, command) {
         matches = false;
     }
     if (matches)
-        return command;
+        return outcome;
     return {
-        ...command,
-        outcome: {
-            ...command.outcome,
-            value: {
-                kind: "failed",
-                code: "tool.invalid-output",
-                message: "Tool result does not match the output schema stored on the action",
-            },
+        ...outcome,
+        value: {
+            kind: "failed",
+            code: "tool.invalid-output",
+            message: "Tool result does not match the output schema stored on the action",
         },
     };
 }
@@ -89,18 +89,15 @@ export async function command(ctx, id, input, scope) {
     const { store } = ctx;
     const cascadeCancelIds = [];
     const response = await store.tx(async (t) => {
-        const s = await lockedSession(t, id, ownerOf(scope));
-        let command = input;
-        if (command.type === "action_result") {
-            const a = (await t.get("actions", command.actionId)) ??
-                fail(404, "Action not found");
-            if (a.sessionId !== id)
-                fail(403, "Action belongs to another session");
-            scoped(scope, a);
-            command = acceptedToolResult(a, command);
-        }
-        else if (scope.kind === "executor")
-            fail(403, "Application credential required");
+        const s = await lockedSession(t, id, accessOf(scope));
+        const command = input;
+        // A person's token may not replace the instructions of a turn.
+        if (scope.kind === "token" &&
+            command.type === "message" &&
+            command.manifest !== undefined)
+            fail(403, "A subject token cannot send message.manifest", {
+                code: "scope_required",
+            });
         const key = commandKey(id, command.idempotencyKey);
         const existing = await t.get("commands", key);
         if (existing) {
@@ -111,85 +108,7 @@ export async function command(ctx, id, input, scope) {
         let event;
         // The turn a `cancel` ended, if one was active.
         let cancelledTurnId = null;
-        if (command.type === "action_result") {
-            const action = (await t.get("actions", command.actionId));
-            const prior = await t.get("effects", command.actionId);
-            if (action.status === "completed") {
-                if (action.claimId !== command.claimId ||
-                    action.generation !== command.generation ||
-                    canonical(prior.outcome) !== canonical(command.outcome))
-                    fail(409, "Conflicting action result");
-                await t.put("commands", key, { command, response: prior.receipt });
-                return prior.receipt;
-            }
-            if (s.status === "cancelled" ||
-                s.activeTurnId !== action.turnId ||
-                action.status !== "claimed" ||
-                action.claimId !== command.claimId ||
-                action.generation !== command.generation ||
-                Date.parse(action.leaseExpiresAt) <= Date.now())
-                fail(409, "Stale, expired, or cancelled claim");
-            action.status = "completed";
-            await t.put("actions", action.actionId, action);
-            prior.status = "completed";
-            prior.outcome = command.outcome;
-            s.status = "runnable";
-            const resultWake = {
-                reason: "action_result",
-                dedupeKey: `action_result:${action.turnId}:${action.actionId}:${action.generation}`,
-            };
-            t.afterCommit(() => ctx.wake(id, resultWake));
-            event = await t.event(id, s.activeTurnId, "action.completed", {
-                actionId: action.actionId,
-                ...actionTarget(action),
-                kind: action.kind,
-                ...(action.kind === "tool" ? toolIds(action.context) : {}),
-                result: command.outcome.value,
-            });
-            if (action.kind === "verify") {
-                const verdict = command.outcome.value;
-                if (verdict?.kind !== "failed") {
-                    await t.event(id, s.activeTurnId, "loop.verified", {
-                        path: String(action.context?.loopPath ?? action.path ?? ""),
-                        n: Number(action.context?.n ?? 1),
-                        pass: Boolean(verdict?.pass),
-                        ...(verdict?.feedback !== undefined
-                            ? { feedback: verdict.feedback }
-                            : {}),
-                        ...(verdict?.data !== undefined ? { data: verdict.data } : {}),
-                    });
-                }
-            }
-            else if (action.kind === "fn" && action.context?.role === "decide") {
-                const decision = command.outcome.value;
-                await t.event(id, s.activeTurnId, "loop.decided", {
-                    path: String(action.context?.loopPath ?? action.path ?? ""),
-                    n: Number(action.context?.n ?? 1),
-                    next: "output" in decision && !("input" in decision)
-                        ? "output"
-                        : "input",
-                    patched: Boolean(decision.agent),
-                });
-            }
-            const receipt = {
-                status: "accepted",
-                turnId: s.activeTurnId,
-                cursor: event.cursor,
-                requestId: command.requestId,
-            };
-            prior.receipt = receipt;
-            await t.put("effects", action.actionId, prior);
-            if (isWorkflowManifest(s.manifest) && s.activeTurnId) {
-                await wakeForQueuedEffects({
-                    t,
-                    workflowSessionId: id,
-                    turnId: s.activeTurnId,
-                    limits: ctx.flowLimits,
-                    schedule: ctx.wake,
-                });
-            }
-        }
-        else if (command.type === "cancel") {
+        if (command.type === "cancel") {
             cancelledTurnId = s.activeTurnId;
             const workflowCancel = isWorkflowManifest(s.manifest);
             // Linked sessions this one started: a workflow's agents, or flow agents an agent
@@ -210,10 +129,10 @@ export async function command(ctx, id, input, scope) {
             else if (cancelledTurnId !== null) {
                 for (const a of await t.actionsForSession(id, {
                     turnId: cancelledTurnId,
-                    statuses: ["pending", "claimed"],
+                    statuses: ["pending", "delivering"],
                 })) {
-                    // Claimed work may already have an external effect. Preserve it for reconciliation.
-                    a.status = a.status === "claimed" ? "uncertain" : "cancelled";
+                    // Delivered work may already have an external effect. Preserve it for reconciliation.
+                    a.status = a.status === "pending" ? "cancelled" : "uncertain";
                     await t.put("actions", a.actionId, a);
                     const effect = await t.get("effects", a.actionId);
                     if (effect) {
@@ -232,8 +151,9 @@ export async function command(ctx, id, input, scope) {
             event = await t.event(id, cancelledTurnId, "turn.cancelled", {
                 reason: command.reason,
             });
+            await slimModelEffects(t, id, cancelledTurnId);
             // The process running the advance aborts it on `session.cancel` (tenant/control).
-            t.afterCommit(() => signalSessionCancel(ctx, id));
+            t.afterCommit(() => signalSessionCancel(ctx, id, cancelledTurnId));
             s.activeTurnId = null;
             if (cancelledTurnId !== null)
                 s.lastTurnId = cancelledTurnId;
@@ -258,7 +178,13 @@ export async function command(ctx, id, input, scope) {
             if (command.type === "message") {
                 if (!["idle", "completed", "failed", "cancelled"].includes(s.status))
                     fail(409, "Session has active or unresolved work");
+                // After the replay check above, so a retried message is never charged twice.
+                if (scope.kind === "token" && scope.limits)
+                    await chargeTurn(t, scope.subject, scope.limits);
                 s.turnStartState = s.state;
+                // A new turn folds from the latest snapshot: a cancel or failure only reverts this turn.
+                if (s.history?.snapshot !== undefined)
+                    s.history = { ...s.history, from: s.history.snapshot };
                 s.activeTurnId = randomUUID();
                 if (isWorkflowManifest(s.manifest)) {
                     const input = "content" in command ? command.content : command.data;
@@ -340,7 +266,6 @@ export async function command(ctx, id, input, scope) {
                     segment: (s.checkpoint?.segment ?? 0) + 1,
                 });
             }
-            await t.put("checkpoints", JSON.stringify([id, s.activeTurnId, s.checkpoint.segment]), { checkpoint: s.checkpoint, status: "runnable" });
             s.status = "runnable";
             s.waits = undefined;
             const commandWake = {
@@ -389,3 +314,74 @@ export async function command(ctx, id, input, scope) {
     }
     return response;
 }
+/**
+ * Completes a delivered Action with `outcome`, in the caller's transaction, which
+ * holds the lock of the Action's session `s`: the Action and its effect, the
+ * `action.completed` event (and `loop.verified` or `loop.decided`), the wake that resumes the
+ * turn, and queued workflow effects. The Action deliverer and the background-result callback
+ * both record outcomes here. It sets `s.status`; the caller writes `s`.
+ */
+export async function recordActionOutcome(t, ctx, s, action, received, options = {}) {
+    const outcome = acceptedOutcome(action, received);
+    const prior = await t.get("effects", action.actionId);
+    action.status = "completed";
+    await t.put("actions", action.actionId, action);
+    prior.status = "completed";
+    prior.outcome = outcome;
+    s.status = "runnable";
+    const resultWake = {
+        reason: "action_result",
+        dedupeKey: `action_result:${action.turnId}:${action.actionId}:${action.generation}`,
+    };
+    t.afterCommit(() => ctx.wake(s.id, resultWake));
+    const event = await t.event(s.id, s.activeTurnId, "action.completed", {
+        actionId: action.actionId,
+        ...actionTarget(action),
+        kind: action.kind,
+        ...(action.kind === "tool" ? toolIds(action.context) : {}),
+        result: outcome.value,
+    });
+    if (action.kind === "verify") {
+        const verdict = outcome.value;
+        if (verdict?.kind !== "failed") {
+            await t.event(s.id, s.activeTurnId, "loop.verified", {
+                path: String(action.context?.loopPath ?? action.path ?? ""),
+                n: Number(action.context?.n ?? 1),
+                pass: Boolean(verdict?.pass),
+                ...(verdict?.feedback !== undefined
+                    ? { feedback: verdict.feedback }
+                    : {}),
+                ...(verdict?.data !== undefined ? { data: verdict.data } : {}),
+            });
+        }
+    }
+    else if (action.kind === "fn" && action.context?.role === "decide") {
+        const decision = outcome.value;
+        await t.event(s.id, s.activeTurnId, "loop.decided", {
+            path: String(action.context?.loopPath ?? action.path ?? ""),
+            n: Number(action.context?.n ?? 1),
+            next: "output" in decision && !("input" in decision)
+                ? "output"
+                : "input",
+            patched: Boolean(decision.agent),
+        });
+    }
+    const receipt = {
+        status: "accepted",
+        turnId: s.activeTurnId,
+        cursor: event.cursor,
+        ...(options.requestId === undefined ? {} : { requestId: options.requestId }),
+    };
+    prior.receipt = receipt;
+    await t.put("effects", action.actionId, prior);
+    if (isWorkflowManifest(s.manifest) && s.activeTurnId) {
+        await wakeForQueuedEffects({
+            t,
+            workflowSessionId: s.id,
+            turnId: s.activeTurnId,
+            limits: ctx.flowLimits,
+            schedule: ctx.wake,
+        });
+    }
+    return { event, receipt };
+}

package/dist/tenant/context.d.ts

@@ -5,7 +5,7 @@
  *
  * Business code changes state only inside `ctx.store.tx(async (t) => …)` and follows the
  * seam rules: events through `t.event(...)` (the relay appends them to Durable Streams after
- * commit), executor wakes through `t.signalWork()`, and advances through
+ * commit), deliveries through `t.afterCommit(() => ctx.deliver(actionId))`, and advances through
  * `t.afterCommit(() => ctx.wake(id, { reason, dedupeKey }))`. It never publishes or notifies
  * itself; `runtime.ts` wires the streams with `wireStreams()`. No external I/O runs inside a
  * tx.
@@ -13,22 +13,26 @@
  * `wake` goes to `DurableExecution.wake`, which calls the Tenant's `advance` (`advance.ts`)
  * under ownership (§10.6); `abortLocal` aborts an advance running on this process.
  */
-import type { SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
+import type { SessionHistory } from "./history.js";
+import type { RoleLimits, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
 import type { DurableCheckpoint, FlowCheckpoint } from "@nylorun/harness/run";
-import type { AgentManifest, JsonValue } from "@nylorun/core/define";
+import type { AgentManifest, JsonValue, SandboxManifest } from "@nylorun/core/define";
 import type { CredentialSelection } from "@nylorun/core/contracts";
 import type { SessionStore, Tx } from "../store/types.js";
-import type { ExecutorRecord, ExecutorRegistry } from "../core/executors.js";
 import type { FlowLimits } from "../core/limits.js";
 import type { ModelProvider } from "../core/provider.js";
+import type { ModelGate } from "../gates/model-gate.js";
+import type { ToolGate } from "../gates/tool-gate.js";
+import type { Keys } from "../keys/keys.js";
 import type { VaultService } from "../vault/service.js";
 import type { McpPool } from "../mcp/pool.js";
 import type { McpDiagnostic, McpSnapshot } from "../mcp/snapshot.js";
 import type { SandboxManager } from "../sandbox/manager.js";
 import type { TenantConfig } from "./types.js";
-import type { LiveHub } from "./live.js";
+import type { SessionStreams } from "./session-streams.js";
 import type { StuckInvocation, Wake } from "../execution/types.js";
 import type { WorkState } from "./scheduler.js";
+import type { SigningKeys } from "./signing-keys.js";
 export interface Session {
     id: string;
     agentId: string;
@@ -43,8 +47,11 @@ export interface Session {
     status: string;
     activeTurnId: string | null;
     checkpoint?: DurableCheckpoint | FlowCheckpoint;
+    /** The engine state; its transcript is folded from the record (`history.ts`), not stored. */
     state?: any;
     turnStartState?: any;
+    /** Where the transcript's fold starts in the session's record (`history.ts`). */
+    history?: SessionHistory;
     waits?: unknown;
     error?: string;
     /** Last completed turn output (for linked agent → workflow settle). */
@@ -64,45 +71,102 @@ export interface Session {
     /** Session id that keys the shared sandbox; absent means this session owns it. */
     sandboxOwnerId?: string;
     /**
-     * The incarnation naming this session's event stream (`sessions/<id>/<incarnation>`), set at
-     * creation and never changed. Absent only on sessions created before incarnations.
+     * The sandbox chosen when the session was opened, resolved against the Tenant's limits, or
+     * inherited from the session it shares with. Absent when the session has no sandbox or its
+     * definition declares one (`.sandbox()`).
      */
-    streamIncarnation?: string;
+    sandbox?: SandboxManifest;
+    /** Where `sandbox` came from. */
+    sandboxSource?: "default" | "inline" | "shared";
 }
 export type AuthScope = {
     kind: "application";
     principalId: string;
 }
+/**
+ * A subject token (Host feature `subject-tokens`): one subject, the role's scopes and agents
+ * narrowed by the token, until `expiresAt` (ms) or the subject's epoch moves past `epoch`.
+ */
+ | {
+    kind: "token";
+    subject: string;
+    scopes: ReadonlySet<SubjectScope>;
+    agents: ReadonlySet<string> | "*";
+    role: string;
+    limits?: RoleLimits;
+    epoch: number;
+    expiresAt: number;
+    tokenId: string;
+    keyId: string;
+}
 /** An application principal acting for `subject` (`Nylorun-Subject`), narrowed to `scopes`. */
  | {
     kind: "subject";
     principalId: string;
     subject: string;
     scopes: ReadonlySet<SubjectScope>;
-} | {
-    kind: "executor";
-    executor: ExecutorRecord;
+}
+/** No credential, on a route that serves public data (`RouteAccess.anonymous`). */
+ | {
+    kind: "anonymous";
+}
+/**
+ * A delivery token (Action endpoints): the Runtime's own token for one delivery of one
+ * Action, presented back by the Action endpoint on that Action's callbacks only.
+ */
+ | {
+    kind: "delivery";
+    actionId: string;
+    agentId: string;
+    generation: number;
+    expiresAt: number;
+    tokenId: string;
+    keyId: string;
+}
+/**
+ * A publishable key with no bearer (Host feature `browser-access`): what the policy grants
+ * `anon`, at most `agents:read`. It owns no session or vault.
+ */
+ | {
+    kind: "publishable";
+    keyId: string;
+    scopes: ReadonlySet<SubjectScope>;
+    agents: ReadonlySet<string> | "*";
 };
 export interface TenantContext {
     readonly config: TenantConfig;
     readonly envelope: TenantEnvelope;
     readonly store: SessionStore;
     readonly vault: VaultService;
-    readonly registry: ExecutorRegistry;
     readonly mcp: McpPool;
     readonly sandbox: SandboxManager;
     readonly flowLimits: FlowLimits;
     readonly modelProvider: ModelProvider;
-    /** True when the model comes from the Tenant vault selection (pi-ai adapter). */
+    /** True when the model comes from the Tenant vault selection, served by `modelGate`. */
     readonly useVaultModel: boolean;
+    /** Serves vault-backed model calls (blueprint §15): in this process, or the gates service. */
+    readonly modelGate: ModelGate;
+    /**
+     * Serves remote MCP servers and Action deliveries (blueprint §12, F4.1): in this process, or
+     * the gates service.
+     */
+    readonly toolGate: ToolGate;
+    /**
+     * Vault writes that touch a secret, and all token signing (blueprint §14, F4.2): in this
+     * process, or the gateway's keys service. Call it instead of `vault`'s sealing methods and
+     * `signingKeys`' private key.
+     */
+    readonly keys: Keys;
     /** Set by drain/close; reset clears it again. Stops new advances. */
     closing: boolean;
     /** Set once close has finished releasing resources. */
     closed: boolean;
     /** Advances running on this process, for `abortLocal`, drain and close. */
     readonly work: WorkState;
-    /** Live delivery over Durable Streams: session feeds, executor streams, the streams wiring. */
-    readonly live: LiveHub;
+    /** Live delivery over Durable Streams: one `SessionStream` per observed session, and the streams wiring. */
+    readonly sessionStreams: SessionStreams;
+    /** The Tenant's signing keys for subject tokens. */
+    readonly signingKeys: SigningKeys;
     /** The Worker id this process writes as session `owner` (§10.6). */
     readonly workerId: string;
     /** How long an advance's ownership lease lasts; the heartbeat renews it. */
@@ -113,19 +177,35 @@ export interface TenantContext {
      * re-wakes anything left runnable.
      */
     wake(sessionId: string, wake: Wake): Promise<void>;
-    /** Seam: abort the advance of a session running in this process, if any. */
-    abortLocal(sessionId: string): void;
+    /**
+     * Seam: abort the advance of a session running in this process, if any. With `turnId`, only
+     * an advance of that turn (a cancel signal names the turn it cancelled).
+     */
+    abortLocal(sessionId: string, turnId?: string): void;
+    /**
+     * Seam: deliver an Action to its agent's Action endpoint (`DurableExecution.deliver`). Call it
+     * from `t.afterCommit`. Dropped while the Tenant is closing; the sweep re-sends it.
+     */
+    deliver(actionId: string): Promise<void>;
     /** This Tenant's execution invocations that need an operator, for Tenant status. */
     readonly stuckInvocations?: () => Promise<StuckInvocation[]>;
     /** Callbacks the Tenant sweep runs after its own steps (`sweep.ts`). */
     readonly sweepHooks: ReadonlySet<() => Promise<void>>;
-    /** Adds a sweep callback (the outbox drain, Wave 2 / Y). Returns a function that removes it. */
+    /** Adds a sweep callback. Returns a function that removes it. */
     onSweep(hook: () => Promise<void>): () => void;
 }
+/**
+ * What a request acting for a person may reach: that person's sessions and vaults, and, for a
+ * subject token, only sessions of the agents its role allows. Undefined means the whole Tenant.
+ */
+export interface SessionAccess {
+    readonly owner: string;
+    readonly agents?: ReadonlySet<string>;
+}
 /** The session, or a 404. Reads without locking. */
-export declare function sessionOf(t: Tx, id: string, owner?: string): Promise<Session>;
+export declare function sessionOf(t: Tx, id: string, access?: SessionAccess): Promise<Session>;
 /** Locks the session for the rest of the transaction and returns it, or a 404. */
-export declare function lockedSession(t: Tx, id: string, owner?: string): Promise<Session>;
+export declare function lockedSession(t: Tx, id: string, access?: SessionAccess): Promise<Session>;
 /** An advance's hold on its session (§10.6): every write the advance makes presents `epoch`. */
 export interface Lease {
     readonly sessionId: string;
@@ -139,7 +219,7 @@ export interface Lease {
  */
 export declare function ownedSession(t: Tx, lease: Lease, id: string): Promise<Session>;
 /** The session read in its own transaction, or a 404. */
-export declare function loadSession(ctx: TenantContext, id: string, owner?: string): Promise<Session>;
+export declare function loadSession(ctx: TenantContext, id: string, access?: SessionAccess): Promise<Session>;
 /**
  * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for
  * the sandbox-sharing helpers, which walk that chain synchronously.

package/dist/tenant/context.js

@@ -1,20 +1,24 @@
 import { fail } from "./http.js";
 /**
- * `owner`, when set, is the subject the request acts for: another owner's session is the same
- * 404 as a missing one, so a subject cannot learn which session ids exist.
+ * `access`, when set, limits the request to the owner's sessions of the allowed agents:
+ * anything else is the same 404 as a missing session, so a subject cannot learn which session
+ * ids exist.
  */
-function owned(session, owner) {
-    if (!session || (owner !== undefined && session.ownerUserId !== owner))
+function owned(session, access) {
+    if (!session ||
+        (access !== undefined &&
+            (session.ownerUserId !== access.owner ||
+                (access.agents !== undefined && !access.agents.has(session.agentId)))))
         return fail(404, "Session not found");
     return session;
 }
 /** The session, or a 404. Reads without locking. */
-export async function sessionOf(t, id, owner) {
-    return owned(await t.get("sessions", id), owner);
+export async function sessionOf(t, id, access) {
+    return owned(await t.get("sessions", id), access);
 }
 /** Locks the session for the rest of the transaction and returns it, or a 404. */
-export async function lockedSession(t, id, owner) {
-    return owned(await t.lockSession(id), owner);
+export async function lockedSession(t, id, access) {
+    return owned(await t.lockSession(id), access);
 }
 /**
  * Locks `id` for the advance holding `lease`. The advance's own session is epoch-checked: a
@@ -27,8 +31,8 @@ export async function ownedSession(t, lease, id) {
     return lockedSession(t, id);
 }
 /** The session read in its own transaction, or a 404. */
-export function loadSession(ctx, id, owner) {
-    return ctx.store.tx((t) => sessionOf(t, id, owner));
+export function loadSession(ctx, id, access) {
+    return ctx.store.tx((t) => sessionOf(t, id, access));
 }
 /**
  * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for