@nylorun/runtime 0.19.1-beta → 0.21.0-beta

package/dist/store/types.d.ts

@@ -59,7 +59,7 @@ import type { RecordReader } from "../streams/relay/types.js";
 import type { EventPayload, EventType, LiveEvent, SandboxEvent, SandboxEventPayload, SandboxEventType, SandboxKind, SandboxPodDesired, SandboxPodObserved, SessionEventOf } from "@nylorun/core/contracts";
 import type { SandboxManifest } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
-import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, OAuthPendingRow } from "./postgres/schema.js";
+import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
 export type DocTable = "definitions" | "sessions" | "commands" | "effects" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
@@ -195,7 +195,7 @@ export type CommitListener = (commit: Commit) => void;
  * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
  * Tenant's signing keys, a model call in the usage ledger and a model budget.
  */
-export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, OAuthPendingRow, };
+export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
 /** Which rows of the usage ledger a total covers. */
 export interface ModelUsageQuery {
     scope: "tenant" | "agent" | "turn";
@@ -261,6 +261,39 @@ export interface SessionStore {
     record(): RecordReader;
     /** Reachability and schema check for Tenant status and `/ready`. Never throws. */
     health(): Promise<StoreHealth>;
+    /**
+     * Follows the control bus (D21): calls `onSignal` once for each signal committed after the
+     * returned promise resolves, on every process that follows. Delivery is by notification,
+     * backed by a poll of recent signals (every `pollMs`, and each time the listener connects
+     * again) that catches the notifications a dropped connection missed. `onSignal` must not
+     * throw; what it throws goes to `onError`, as do listener failures.
+     */
+    followSignals(onSignal: (signal: ControlSignal) => void, options?: FollowSignalsOptions): Promise<SignalFollower>;
+    close(): Promise<void>;
+}
+/**
+ * A signal on the control bus (D21, D48): one process tells the others with the Tenant open.
+ * Signals are not events: they are never recorded in a session's log or streamed, and a
+ * lost one costs latency, never correctness. They never go through S2.
+ */
+export type ControlSignal = {
+    /** The process running the session's advance aborts it. */
+    type: "session.cancel";
+    sessionId: string;
+    /** The cancelled turn: an advance of another turn keeps running. Absent: any advance. */
+    turnId?: string;
+} | {
+    /** The Tenant's sessions were reset and it moved to basin generation `generation`. */
+    type: "sessions.reset";
+    generation: number;
+};
+export interface FollowSignalsOptions {
+    /** How often recent signals are read back. Default 5 s. */
+    pollMs?: number;
+    onError?: (error: unknown) => void;
+}
+export interface SignalFollower {
+    /** Stops following and ends the listener's connection. */
     close(): Promise<void>;
 }
 export interface StoreHealth {
@@ -393,6 +426,13 @@ export interface Tx {
     /** Links of one workflow session joined to their existing agent sessions, ordered by agent session id. */
     linkedSessions<S extends SessionDoc = SessionDoc>(workflowSessionId: string): Promise<LinkedSession<S>[]>;
     counts(): Promise<StoreCounts>;
+    /**
+     * Puts `signal` on the control bus: a row, and a notification Postgres sends every
+     * following process when this transaction commits (and never on rollback).
+     */
+    signal(signal: ControlSignal): Promise<void>;
+    /** Deletes signals written before `before`. Returns how many. */
+    pruneSignals(before: Date): Promise<number>;
     basinGenerations(): Promise<BasinGenerations>;
     /** Forgets a retired generation once its basin is deleted. */
     forgetRetiredGeneration(generation: number): Promise<void>;
@@ -443,12 +483,6 @@ export interface Tx {
     getVaultIdempotency(id: string): Promise<VaultIdempotencyRow | undefined>;
     /** Rejects when the id exists. */
     insertVaultIdempotency(row: VaultIdempotencyRow): Promise<void>;
-    /** An MCP OAuth connect's start (F9 C2). Rejects on a duplicate state or an unknown vault. */
-    insertOAuthPending(row: OAuthPendingRow): Promise<void>;
-    /** Deletes and returns the pending connect of `stateHash`, expired or not: each is used once. */
-    takeOAuthPending(stateHash: string): Promise<OAuthPendingRow | undefined>;
-    /** Deletes the pending connects that expired before `now` (ISO); returns how many. */
-    deleteExpiredOAuthPending(now: string): Promise<number>;
     /**
      * Serializes signing key changes: held until the transaction ends. Take it before reading
      * the keys a change depends on, so concurrent first uses or rotations do not collide.

package/dist/streams/types.d.ts

@@ -7,7 +7,10 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
+ *
+ * S2 serves API listeners only (history, SSE, AG-UI, A2A): nothing inside the Runtime signals
+ * through it or waits on it (D48). Signals between processes go over the control bus on
+ * Postgres (`store/postgres/control.ts`).
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
@@ -104,38 +107,12 @@ export interface DurableStreams {
     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
+     * Resolves when the backing service answers, rejects otherwise (the Tenant's status,
+     * `streamsStatus` in `tenant/streams.ts`; never readiness, D48). Absent for in-process implementations, which are
      * always reachable.
      */
     probe?(signal: AbortSignal): Promise<void>;
 }
 export declare const SESSION_STREAM_PREFIX = "sessions/";
-/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
-export declare const CONTROL_STREAM = "tenant/control";
 /** The stream of a session: `sessions/<sessionId>`. */
 export declare function sessionStream(sessionId: string): string;
-/**
- * Signals are not events: they are appended directly, never recorded, and a
- * lost signal costs latency, not correctness.
- */
-/** Ends the advance of `sessionId` on the process running it. */
-export interface SessionCancelSignal {
-    type: "session.cancel";
-    sessionId: string;
-    /**
-     * The cancelled turn. Only an advance of this turn stops, so a signal delivered late (an
-     * append retried after S2 returns) never stops a later turn. Absent: any advance stops.
-     */
-    turnId?: string;
-}
-/**
- * The Tenant was reset and moved to basin generation `generation`. Appended to the old
- * generation's `tenant/control`: each process switches its readers to the new basin and
- * ends the streams of sessions the reset deleted.
- */
-export interface SessionsResetSignal {
-    type: "sessions.reset";
-    generation?: number;
-}
-export type ControlSignal = SessionCancelSignal | SessionsResetSignal;

package/dist/streams/types.js

@@ -7,7 +7,10 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
+ *
+ * S2 serves API listeners only (history, SSE, AG-UI, A2A): nothing inside the Runtime signals
+ * through it or waits on it (D48). Signals between processes go over the control bus on
+ * Postgres (`store/postgres/control.ts`).
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
@@ -39,10 +42,8 @@
  *   encode them as they need.
  */
 // ---------------------------------------------------------------------------
-// Stream names and signal records
+// Stream names
 export const SESSION_STREAM_PREFIX = "sessions/";
-/** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
-export const CONTROL_STREAM = "tenant/control";
 /** The stream of a session: `sessions/<sessionId>`. */
 export function sessionStream(sessionId) {
     if (!sessionId)

package/dist/tenant/artifact-tool.d.ts

@@ -1,5 +1,13 @@
 import type { SandboxToolOutcome } from "@nylorun/core/contracts";
+import { type ToolResultFile } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
 import { type TenantContext } from "./context.js";
-export { isSaveArtifactCall } from "../harness/calls.js";
+export { isReadArtifactCall, isSaveArtifactCall } from "../harness/calls.js";
 export declare function callSaveArtifact(ctx: TenantContext, request: HostEffect, signal: AbortSignal): Promise<SandboxToolOutcome>;
+/** What `read_artifact` returns: a page of a text artifact, or an image as a file. */
+interface ReadOutcome {
+    readonly kind: "completed";
+    readonly output: Record<string, unknown>;
+    readonly files?: readonly ToolResultFile[];
+}
+export declare function callReadArtifact(ctx: TenantContext, request: HostEffect, signal: AbortSignal): Promise<ReadOutcome | SandboxToolOutcome>;

package/dist/tenant/artifact-tool.js

@@ -1,20 +1,28 @@
 /**
- * `nylorun.save_artifact` (F8.1): our engine's built-in tool that saves a file as an artifact
- * of its session. The `nylorun.artifacts` capability comes with a session's sandbox
- * (`sandbox/session-sandbox.ts`); the Runtime runs the tool itself, like the sandbox tools:
+ * Our engine's built-in artifact tools, of the `nylorun.artifacts` capability
+ * (`sandbox/session-sandbox.ts`). The Runtime runs them itself, like the sandbox tools.
  *
+ * `save_artifact` (F8.1), which comes with a session's sandbox, saves a file as an artifact of
+ * its session:
  * - `path`: a file in the session's sandbox, read as bytes in the sandbox's queue;
  * - `content`: text the model passes.
- *
  * The version commits with `artifact.created` (or `artifact.version.created`) on the session's
- * stream, carrying the turn and the tool call. Expected problems (no such file, too large, the
- * Tenant's total reached) are failed outcomes the model sees; only infrastructure errors throw.
+ * stream, carrying the turn and the tool call.
+ *
+ * `read_artifact` (R2b C11, Q24), which an agent with a remote MCP server or an HTTP tool has,
+ * reads a text artifact of its own session in pages of at most 32 KiB, from a byte `offset`:
+ * how the model reads a tool result the Runtime stored because it was too large to show
+ * (`tool-results.ts`). An image is shown to a model that reads images, as a file of the result.
+ * It reaches only the session's own artifacts, never a Tenant-wide one or another session's.
+ *
+ * Expected problems (no such file, too large, the Tenant's total reached, not text) are failed
+ * outcomes the model sees; only infrastructure errors throw.
  */
 import { basename } from "node:path";
-import { SANDBOX_CAPABILITY_ID } from "@nylorun/core/define";
+import { READ_ARTIFACT_MAX_BYTES, SANDBOX_CAPABILITY_ID, } from "@nylorun/core/define";
 import { isArtifactId } from "@nylorun/core/compatibility";
 import { readArtifactLimits } from "../artifacts/config.js";
-import { contentTypeFor, normalizeContentType } from "../artifacts/media-types.js";
+import { MODEL_FILE_MAX_BYTES, contentTypeFor, essence, isModelImage, isText, normalizeContentType, } from "../artifacts/media-types.js";
 import { uploadArtifact } from "../artifacts/service.js";
 import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
 import { sandboxCapabilityOf } from "../sandbox/manager.js";
@@ -22,8 +30,9 @@ import { sandboxWorkspaceOf } from "../sandbox/share.js";
 import { sandboxLookup, sessionOf } from "./context.js";
 import { HttpError } from "./http.js";
 import { manifestFor } from "./session.js";
+import { jsonBytes, utf8Boundary } from "./tool-results.js";
 import { toolIds } from "./transcript.js";
-export { isSaveArtifactCall } from "../harness/calls.js";
+export { isReadArtifactCall, isSaveArtifactCall } from "../harness/calls.js";
 const failed = (code, message) => ({
     kind: "failed",
     code,
@@ -117,3 +126,98 @@ export async function callSaveArtifact(ctx, request, signal) {
         throw error;
     }
 }
+export async function callReadArtifact(ctx, request, signal) {
+    const input = (request.input ?? {});
+    const artifactId = typeof input.artifactId === "string" ? input.artifactId : "";
+    const offset = input.offset ?? 0;
+    const length = input.length ?? READ_ARTIFACT_MAX_BYTES;
+    if (artifactId === "" ||
+        typeof offset !== "number" ||
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        typeof length !== "number" ||
+        !Number.isSafeInteger(length) ||
+        length < 1 ||
+        length > READ_ARTIFACT_MAX_BYTES)
+        return failed("artifact.invalid_input", `Give artifactId, an offset of 0 or more, and a length of 1 to ${READ_ARTIFACT_MAX_BYTES}.`);
+    const found = await ctx.store.tx(async (t) => {
+        const s = await sessionOf(t, request.sessionId);
+        if (!isArtifactId(artifactId))
+            return undefined;
+        // Only an artifact of this session: never a Tenant-wide one, nor another session's.
+        const artifact = await t.artifact(artifactId);
+        if (!artifact || artifact.sessionId !== s.id)
+            return undefined;
+        const version = await t.artifactVersion(artifact.id, artifact.latestVersion);
+        return version ? { artifact, version } : undefined;
+    });
+    if (!found)
+        return failed("artifact.not_found", `Artifact ${artifactId} is not an artifact of this session.`);
+    const { artifact, version } = found;
+    const about = {
+        artifactId: artifact.id,
+        version: version.version,
+        name: artifact.name,
+        contentType: version.contentType,
+        size: version.size,
+    };
+    if (artifact.kind !== "file")
+        return failed("artifact.not_text", `${artifact.name} is a folder; read_artifact reads a file.`);
+    if (isModelImage(version.contentType) && version.size <= MODEL_FILE_MAX_BYTES)
+        return {
+            kind: "completed",
+            output: about,
+            files: [
+                {
+                    mediaType: version.contentType,
+                    reference: { artifactId: artifact.id, version: version.version, name: artifact.name },
+                },
+            ],
+        };
+    if (!isText(version.contentType))
+        return failed("artifact.not_text", `${artifact.name} is ${essence(version.contentType)}, not text; read_artifact reads text and shows images.`);
+    if (offset > version.size || (offset === version.size && version.size > 0))
+        return failed("artifact.invalid_input", `Offset ${offset} is past the end of ${artifact.name}, which is ${version.size} bytes.`);
+    const end = Math.min(offset + length, version.size);
+    const bytes = end === offset ? new Uint8Array() : await readRange(ctx, version.blobKey, offset, end - 1, signal);
+    const page = textPage(bytes, end === version.size);
+    const next = offset + page.bytes;
+    return {
+        kind: "completed",
+        output: {
+            ...about,
+            offset,
+            content: page.text,
+            ...(next < version.size ? { nextOffset: next } : {}),
+        },
+    };
+}
+/** Bytes `start` to `end` (both inclusive) of a version's blob. */
+async function readRange(ctx, blobKey, start, end, signal) {
+    const got = await ctx.blobs.get(blobKey, { range: { start, end }, signal });
+    if (!got)
+        throw new Error("The artifact's bytes are missing from the Object store");
+    return new Uint8Array(await new Response(got.body).arrayBuffer());
+}
+/**
+ * The text of a page of UTF-8 `bytes` in whole characters, at most `READ_ARTIFACT_MAX_BYTES`
+ * once escaped as JSON, and how many bytes it used: the next page starts there. A page that
+ * starts inside a character skips its rest, and one that ends inside one (not `last`) stops
+ * before it.
+ */
+function textPage(bytes, last) {
+    const from = utf8Boundary(bytes, 0, "up");
+    let to = last ? bytes.byteLength : utf8Boundary(bytes, bytes.byteLength, "down");
+    // A page shorter than one character: take what there is.
+    if (to <= from)
+        to = bytes.byteLength;
+    const decode = () => Buffer.from(bytes.subarray(from, to)).toString("utf8");
+    let text = decode();
+    // Escaped (quotes, newlines, control characters), text takes more room than its bytes: each
+    // byte left out frees at least one.
+    for (let size = jsonBytes(text); to > from && size > READ_ARTIFACT_MAX_BYTES; size = jsonBytes(text)) {
+        to = utf8Boundary(bytes, Math.max(from, to - (size - READ_ARTIFACT_MAX_BYTES)), "down");
+        text = decode();
+    }
+    return { text, bytes: to };
+}

package/dist/tenant/auth.d.ts

@@ -1,9 +1,10 @@
 /**
  * Tenant request authentication and authorization: a bearer token resolves to an application
- * principal or a trusted issuer's token; anything else is the opaque 404
- * (D5). An application principal may act for a subject (`Nylorun-Subject`, `Nylorun-Scopes`);
- * an issuer token names its subject itself. `requireScopes` limits them to the routes their
- * scopes allow, decided from the route alone.
+ * principal or a trusted issuer's token. Anything else is `401` with a `Bearer` challenge
+ * (protocol 9, `resource-server.ts`): `credential_required` without one, `credential_invalid`
+ * for one the Tenant refuses, its reason only logged. An application principal may act for a
+ * subject (`Nylorun-Subject`, `Nylorun-Scopes`); an issuer token names its subject itself.
+ * `requireScopes` limits them to the routes their scopes allow, decided from the route alone.
  *
  * Browsers: a request with `Origin` may carry an issuer token (CORS is the operator's proxy's),
  * never an application key, which is a server secret.
@@ -21,6 +22,11 @@ export interface KeyAccess {
 }
 /** Every route that does not say otherwise is a Runtime API route. */
 export declare const RUNTIME_KEYS: KeyAccess;
+/**
+ * The `resource_metadata` a route's challenges point at: a Runtime API route's, when the Runtime
+ * trusts issuers. The Management API is no OAuth resource.
+ */
+export declare function challengeMetadata(ctx: TenantContext, request: IncomingMessage, keys: KeyAccess): string | undefined;
 export declare function authenticate(ctx: TenantContext, request: IncomingMessage, keys?: KeyAccess): Promise<AuthScope>;
 /**
  * What a subject needs for a route: any one of the scopes, nothing grants it (`never`), or
@@ -30,9 +36,13 @@ export declare function authenticate(ctx: TenantContext, request: IncomingMessag
 export type SubjectAccess = readonly SubjectScope[] | "never" | "any";
 /**
  * A subject or a token caller reaches a route only with one of the scopes it declares:
- * `403 scope_required`, decided from the route alone before anything is read.
+ * `403 scope_required`, decided from the route alone before anything is read. A token caller
+ * also gets the OAuth challenge (`error="insufficient_scope"` and the scopes that would do), so
+ * its client can ask its identity provider for them; a route no scope reaches has none.
  */
-export declare function requireScopes(scope: AuthScope, access: SubjectAccess): void;
+export declare function requireScopes(scope: AuthScope, access: SubjectAccess, 
+/** The route's `resource_metadata` (`challengeMetadata`), for a token caller's challenge. */
+resourceMetadata?: string): void;
 export declare function accessOf(scope: AuthScope): SessionAccess | undefined;
 /** The subject whose sessions the request is limited to, if it acts for one. */
 export declare function ownerOf(scope: AuthScope): string | undefined;

package/dist/tenant/auth.js

@@ -1,9 +1,10 @@
 import { SCOPES_HEADER, SUBJECT_HEADER, } from "@nylorun/core/compatibility";
-import { parseSubjectHeaders } from "@nylorun/core/contracts";
+import { parseSubjectHeaders, TOKEN_SCOPES } from "@nylorun/core/contracts";
 import { hashToken } from "../core/bearer.js";
-import { fail, failOpaque } from "./http.js";
+import { fail } from "./http.js";
 import { verifyIssuerToken } from "./issuers.js";
 import { looksLikeToken } from "./jwt.js";
+import { bearerChallenge, failCredential, protectedResourceMetadataUrl } from "./resource-server.js";
 const SUBJECT_INVALID = { code: "subject_invalid" };
 /** One header's value, or `undefined`; a header sent twice is refused. */
 function singleHeader(request, name) {
@@ -18,20 +19,30 @@ function singleHeader(request, name) {
 }
 /** Every route that does not say otherwise is a Runtime API route. */
 export const RUNTIME_KEYS = { application: true, management: false };
+/** The bearer of an `Authorization` header: the scheme is case-insensitive (RFC 9110 §11.1). */
+const BEARER = /^bearer +(\S+) *$/i;
+/**
+ * The `resource_metadata` a route's challenges point at: a Runtime API route's, when the Runtime
+ * trusts issuers. The Management API is no OAuth resource.
+ */
+export function challengeMetadata(ctx, request, keys) {
+    return keys.application ? protectedResourceMetadataUrl(ctx.config, request) : undefined;
+}
 export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
-    const header = request.headers.authorization;
-    const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
-    if (!token || !header?.startsWith("Bearer ")) {
+    const metadata = challengeMetadata(ctx, request, keys);
+    const token = BEARER.exec(request.headers.authorization ?? "")?.[1];
+    // No credential, or another scheme: the client may not know it needs one (no error code).
+    if (!token) {
         ctx.config.logger.warn("credential rejected", {
             reason: "missing_bearer",
         });
-        return failOpaque();
+        return failCredential("required", metadata);
     }
     // A trusted issuer's token (Host feature `trusted-issuers`), from a server or a browser: its
     // unverified `iss` names an issuer of the identity file, and only that issuer verifies it.
     const issuer = ctx.config.issuers?.claimed(token);
     if (issuer) {
-        const scope = await verifyIssuerToken(ctx, issuer, token);
+        const scope = await verifyIssuerToken(ctx, issuer, token, metadata);
         if (singleHeader(request, SUBJECT_HEADER) !== undefined ||
             singleHeader(request, SCOPES_HEADER) !== undefined)
             fail(403, "An issuer token cannot act for another subject");
@@ -40,7 +51,7 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
     // Any other JWT: no issuer of this Host signed it (subject tokens are gone, protocol 7).
     if (looksLikeToken(token)) {
         ctx.config.logger.warn("credential rejected", { reason: "token_unknown_issuer" });
-        return failOpaque();
+        return failCredential("invalid", metadata);
     }
     // Application keys never come from a browser or a shipped app: refused before they are even
     // looked up.
@@ -54,9 +65,9 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
         ctx.config.logger.warn("credential rejected", {
             reason: "unknown_token",
         });
-        return failOpaque();
+        return failCredential("invalid", metadata);
     }
-    // Read only after authentication, so an unknown caller sees the opaque 404 either way.
+    // Read only after authentication, so an unknown caller learns nothing of them.
     const subject = singleHeader(request, SUBJECT_HEADER);
     const scopes = singleHeader(request, SCOPES_HEADER);
     // A management key acts as itself on the Management API; Studio's key does too on a route
@@ -92,9 +103,13 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
 }
 /**
  * A subject or a token caller reaches a route only with one of the scopes it declares:
- * `403 scope_required`, decided from the route alone before anything is read.
+ * `403 scope_required`, decided from the route alone before anything is read. A token caller
+ * also gets the OAuth challenge (`error="insufficient_scope"` and the scopes that would do), so
+ * its client can ask its identity provider for them; a route no scope reaches has none.
  */
-export function requireScopes(scope, access) {
+export function requireScopes(scope, access, 
+/** The route's `resource_metadata` (`challengeMetadata`), for a token caller's challenge. */
+resourceMetadata) {
     if (scope.kind !== "subject" && scope.kind !== "token")
         return;
     if (access === "any")
@@ -105,11 +120,20 @@ export function requireScopes(scope, access) {
             details: { scopes: [] },
         });
     const held = scope.scopes;
-    if (!access.some((name) => held.has(name)))
-        fail(403, `Scope ${access.join(" or ")} required`, {
-            code: "scope_required",
-            details: { scopes: access },
-        });
+    if (!access.some((name) => held.has(name))) {
+        // Any one of the route's scopes reaches it, but OAuth's list is of scopes held together:
+        // the challenge names the first a token can carry, or none when no token reaches the route.
+        const askable = access.find((name) => TOKEN_SCOPES.includes(name));
+        fail(403, `Scope ${access.join(" or ")} required`, { code: "scope_required", details: { scopes: access } }, scope.kind === "token" && askable
+            ? {
+                "www-authenticate": bearerChallenge({
+                    error: "insufficient_scope",
+                    scope: askable,
+                    resourceMetadata,
+                }),
+            }
+            : {});
+    }
 }
 export function accessOf(scope) {
     switch (scope.kind) {

package/dist/tenant/commands.js

@@ -10,9 +10,10 @@
  * (every accepted one writes a new checkpoint segment), except that a workflow's `approve` and
  * `respond` name `<type>:<turnId>:<interactionId>`: a flow resumes in the same segment.
  *
- * 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
- * (`ctx.abortLocal`); reaching an advance on another process is the control stream's job.
+ * Cancel commits `cancelled` first, with a `session.cancel` signal on the control bus in the
+ * same transaction; the engine host sees it before its next effect and before settlement on
+ * any Worker. It then aborts an advance running on this process (`ctx.abortLocal`); every
+ * other process aborts its own on the signal (`control.ts`).
  */
 import { randomUUID } from "node:crypto";
 import { createDurableCheckpoint, createFlowCheckpoint, resumeFlowCheckpoint, } from "@nylorun/harness/run";
@@ -24,7 +25,6 @@ import { fail } from "./http.js";
 import { accessOf } from "./auth.js";
 import { checkSandboxTurn } from "./sandboxes.js";
 import { rebaseSessionState, turnManifestOf, variantStore } from "./session.js";
-import { signalSessionCancel } from "./streams.js";
 import { slimModelEffects } from "./slim.js";
 import { resolveMessageParts } from "../artifacts/parts.js";
 /** A command's identity for idempotency: everything but the request id. */
@@ -83,8 +83,12 @@ export async function command(ctx, id, input, scope) {
                 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, cancelledTurnId));
+            // The process running the advance aborts it on this signal (control.ts), sent at commit.
+            await t.signal({
+                type: "session.cancel",
+                sessionId: id,
+                ...(cancelledTurnId !== null ? { turnId: cancelledTurnId } : {}),
+            });
             s.activeTurnId = null;
             if (cancelledTurnId !== null)
                 s.lastTurnId = cancelledTurnId;

package/dist/tenant/context.d.ts

@@ -24,7 +24,6 @@ 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 { CredentialSources } from "../vault/sources.js";
 import type { McpPool } from "../mcp/pool.js";
 import type { McpDiagnostic, McpSnapshot } from "../mcp/snapshot.js";
 import type { HarnessApiServer } from "../harness-api/server.js";
@@ -46,6 +45,11 @@ export interface Session {
     /** Session pin — the manifest the session was created with. */
     manifest: any;
     manifestHash: string;
+    /**
+     * The hash of the definition the session was opened from; `manifestHash` differs when the
+     * Runtime pinned its own capabilities beside it (R2b C11). Absent on older sessions.
+     */
+    definitionHash?: string;
     /** Validated turn-manifest variants, keyed by hash (loops.md §4.2). */
     variants?: Record<string, AgentManifest>;
     implementationVersion: string;
@@ -139,11 +143,6 @@ export interface TenantContext {
     readonly envelope: TenantEnvelope;
     readonly store: SessionStore;
     readonly vault: VaultService;
-    /**
-     * A session's MCP credentials, for the in-process MCP pool: its attached vaults, then the
-     * operator's credential resolver (`TenantConfig.resolver`, F9 C1).
-     */
-    readonly credentials: CredentialSources;
     /**
      * The MCP pool of the Tenant's in-process harness. Absent when harnesses run elsewhere
      * (`NYLORUN_HARNESS=remote`): each keeps its own (F6.2).
@@ -201,6 +200,10 @@ export interface TenantContext {
     readonly work: WorkState;
     /** Live delivery over Durable Streams: one `SessionStream` per observed session, and the streams wiring. */
     readonly sessionStreams: SessionStreams;
+    /** This process's follower of the control bus (`control.ts`), once wired. */
+    control?: {
+        close(): Promise<void>;
+    };
     /** The Tenant's signing keys: capability links, run and host tokens. */
     readonly signingKeys: SigningKeys;
     /** The Worker id this process writes as session `owner` (§10.6). */

package/dist/tenant/control.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The control bus of an open Tenant (blueprint D21, D48): the signals one process sends the
+ * others with the Tenant open, on Postgres (`Tx.signal`, `SessionStore.followSignals`). They
+ * never go through S2, which only serves API listeners.
+ *
+ * - `session.cancel` is written by the cancel's own transaction (`commands.ts`): every process
+ *   aborts the cancelled turn's advance if it runs there (`ctx.abortLocal`).
+ * - `sessions.reset` is written by the reset's transaction (`reset.ts`): every process moves
+ *   its session streams to the new basin generation and ends those of deleted sessions
+ *   (`checkSessionStreams`).
+ *
+ * A lost signal costs latency, never correctness: the advance checks the Session Store before
+ * every effect, and the session streams are checked periodically (`streams.ts`).
+ */
+import type { TenantContext } from "./context.js";
+export interface WireControlOptions {
+    /** How often the follower reads recent signals back (`FollowSignalsOptions.pollMs`). */
+    pollMs?: number;
+}
+/**
+ * Follows the control bus for this process and keeps the follower on `ctx.control`. Call it
+ * once, after `ctx` is built; signals committed from its return on reach this process.
+ */
+export declare function wireControl(ctx: TenantContext, options?: WireControlOptions): Promise<void>;
+/** Close: stops following the control bus. */
+export declare function closeControl(ctx: TenantContext): Promise<void>;

package/dist/tenant/control.js

@@ -0,0 +1,35 @@
+import { checkSessionStreams } from "./session-streams.js";
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Follows the control bus for this process and keeps the follower on `ctx.control`. Call it
+ * once, after `ctx` is built; signals committed from its return on reach this process.
+ */
+export async function wireControl(ctx, options = {}) {
+    if (ctx.control)
+        throw new Error("The control bus is already wired");
+    let closed = false;
+    // Nothing is reported once closed: the Tenant (and its log directory) may be gone.
+    const report = (what) => (error) => {
+        if (!closed)
+            ctx.config.logger.warn(what, { message: messageOf(error) });
+    };
+    const follower = await ctx.store.followSignals((signal) => {
+        if (signal.type === "session.cancel")
+            ctx.abortLocal(signal.sessionId, signal.turnId);
+        else
+            void checkSessionStreams(ctx).catch(report("session stream check failed"));
+    }, {
+        ...(options.pollMs !== undefined ? { pollMs: options.pollMs } : {}),
+        onError: report("control bus unavailable; retrying"),
+    });
+    ctx.control = {
+        async close() {
+            closed = true;
+            await follower.close();
+        },
+    };
+}
+/** Close: stops following the control bus. */
+export async function closeControl(ctx) {
+    await ctx.control?.close();
+}

package/dist/tenant/effects.d.ts

@@ -14,7 +14,7 @@ import type { EffectOutcome } from "@nylorun/core/contracts";
 import type { EffectResolution, HostEffect } from "@nylorun/harness/run";
 import type { Tx } from "../store/types.js";
 import type { AuthorizeResult } from "../vault/service.js";
-import type { McpCredentialRequest } from "../vault/sources.js";
+import { type McpCredentialRequest } from "../vault/sources.js";
 import { type Lease, type Session, type TenantContext } from "./context.js";
 /**
  * The outcome of a flow `agent` effect once the linked turn it started ended, or undefined
@@ -42,6 +42,6 @@ export declare function recoversModelCalls(ctx: TenantContext): boolean;
 export declare function resolveNewFlowEffect(ctx: TenantContext, request: HostEffect, signal: AbortSignal, lease: Lease): Promise<EffectResolution>;
 /**
  * The credential of an MCP server or HTTP tool request made on behalf of a session: from its
- * attached vaults, else the operator's credential resolver (`vault/sources.ts`).
+ * attached vaults (`vault/sources.ts`).
  */
 export declare function authorize(ctx: TenantContext, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;