@nylorun/runtime 0.17.0-beta → 0.19.0-beta

package/dist/tenant/effects.js

@@ -1,14 +1,14 @@
-import { embeddedAgent, flowDelegateManifest, hashManifest, isWorkflowManifestV2, } from "@nylorun/core/define";
-import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowToolEffect, isWorkflowManifest, linkedMessageKey, linkedTurnEnd, } from "../core/flow-host.js";
+import { embeddedAgent, flowDelegateManifest, hashManifest, } from "@nylorun/core/define";
+import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowToolEffect, isWorkflowManifest, linkedMessageInput, linkedMessageKey, linkedTurnEnd, settleAgentEffect, } from "../core/flow-host.js";
 import { mayDispatchMore } from "../core/limits.js";
 import { isRemoteMcpCall } from "../harness/calls.js";
+import { isHttpToolCall } from "../gates/http-tool.js";
 import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
 import { withSandboxCapability } from "../sandbox/session-sandbox.js";
 import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
-import { linkedAgentOutput, turnManifestOf } from "./session.js";
+import { turnManifestOf } from "./session.js";
 import { command } from "./commands.js";
-import { offerAction } from "./delivery.js";
 /**
  * The outcome of a flow `agent` effect once the linked turn it started ended, or undefined
  * while it has not. The linked session may still show an earlier iteration's turn.
@@ -18,7 +18,7 @@ export async function linkedOutcome(t, effect, agent) {
     if (!end || !agent)
         return undefined;
     if (end.status === "completed")
-        return { value: linkedAgentOutput(agent, end.output) };
+        return { value: end.output };
     return {
         value: {
             kind: "failed",
@@ -31,16 +31,17 @@ export async function linkedOutcome(t, effect, agent) {
     };
 }
 /**
- * True when this Tenant's remote MCP calls outlive the process that sent them (the gates
- * service, F4.1 G3): after a takeover or a shutdown, the journaled call is re-sent and joins
- * the running call or gets its answer, instead of becoming `uncertain`.
+ * True when this Tenant's remote MCP and HTTP tool calls outlive the process that sent them
+ * (the gates service, F4.1 G3): after a takeover or a shutdown, the journaled call is re-sent
+ * and joins the running call or gets its answer, instead of becoming `uncertain`.
  */
-export function recoversMcpCalls(ctx) {
+export function recoversToolCalls(ctx) {
     return ctx.toolGate.recovers === true;
 }
-/** True when `request` calls a tool of a remote (`streamable-http` or `sse`) MCP server. */
-export function isRemoteMcpEffect(s, request) {
-    return isRemoteMcpCall({ rootManifest: s.manifest, mcpSnapshot: s.mcpSnapshot }, request);
+/** True when `request` calls a tool of a declared MCP server (every one is remote) or an HTTP tool. */
+export function isGateToolEffect(s, request) {
+    return (isRemoteMcpCall({ rootManifest: s.manifest, mcpSnapshot: s.mcpSnapshot }, request) ||
+        isHttpToolCall(s.manifest, request));
 }
 /**
  * True when this Tenant's vault-backed model calls outlive the process that sent them (the
@@ -50,7 +51,7 @@ export function isRemoteMcpEffect(s, request) {
 export function recoversModelCalls(ctx) {
     return ctx.useVaultModel && ctx.modelGate.recovers === true;
 }
-/** Journal and dispatch a new flow effect (agent / tool node / fn / verify). */
+/** Journal and dispatch a new flow effect (agent or tool node). */
 export async function resolveNewFlowEffect(ctx, request, signal, lease) {
     const { store } = ctx;
     signal.throwIfAborted();
@@ -75,9 +76,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 const outcome = await linkedOutcome(t, existing, agent);
                 if (!outcome)
                     return resolved({ status: "pending" });
-                existing.status = "completed";
-                existing.outcome = outcome;
-                await t.put("effects", request.effectId, existing);
+                await settleAgentEffect({ t, effect: existing, outcome });
                 return resolved({ status: "completed", outcome });
             }
             else {
@@ -93,64 +92,25 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 });
             return resolved({ status: "pending" });
         }
-        if (request.kind === "fn" ||
-            request.kind === "verify" ||
-            isFlowToolEffect(request)) {
-            await t.put("effects", request.effectId, {
-                request,
-                status: "pending",
+        if (isFlowToolEffect(request)) {
+            // A tool stage without `http` would run the developer's code: refused at save, so this
+            // is a backstop (HTTP stages are executed by the harness, `harness-api/record.ts`). The
+            // stage fails; nothing runs.
+            const outcome = {
+                value: {
+                    kind: "failed",
+                    code: "tool.unavailable",
+                    message: `The tool stage '${request.key ?? request.path ?? ""}' runs your code, and the Runtime runs no code of yours during a session`,
+                },
+            };
+            await t.put("effects", request.effectId, { request, status: "completed", outcome });
+            await t.event(workflow.id, workflow.activeTurnId, "node.started", {
+                path: request.path,
+                kind: "tool",
+                key: request.key,
+                ...(request.iterations !== undefined ? { iterations: request.iterations } : {}),
             });
-            const action = request.kind === "fn" || request.kind === "verify"
-                ? {
-                    actionId: request.effectId,
-                    sessionId: request.sessionId,
-                    turnId: request.turnId,
-                    agentId: request.agentId,
-                    manifestHash: request.manifestHash,
-                    implementationVersion: workflow.implementationVersion,
-                    input: request.input,
-                    context: request.context,
-                    status: "pending",
-                    generation: 0,
-                    kind: request.kind,
-                    path: request.path,
-                    key: request.key,
-                }
-                : {
-                    actionId: request.effectId,
-                    sessionId: request.sessionId,
-                    turnId: request.turnId,
-                    agentId: request.agentId,
-                    manifestHash: request.manifestHash,
-                    implementationVersion: workflow.implementationVersion,
-                    input: request.input,
-                    context: request.context,
-                    status: "pending",
-                    generation: 0,
-                    kind: "tool",
-                    path: request.path,
-                    key: request.key,
-                };
-            await t.put("actions", action.actionId, action);
-            if (isFlowToolEffect(request)) {
-                await t.event(workflow.id, workflow.activeTurnId, "node.started", {
-                    path: request.path,
-                    kind: "tool",
-                    key: request.key,
-                    ...(request.iterations !== undefined
-                        ? { iterations: request.iterations }
-                        : {}),
-                });
-            }
-            await t.event(workflow.id, workflow.activeTurnId, "action.pending", {
-                actionId: action.actionId,
-                kind: action.kind,
-                path: action.path,
-                key: action.key,
-                input: action.input,
-            });
-            await offerAction(t, ctx, action);
-            return resolved({ status: "pending" });
+            return resolved({ status: "completed", outcome });
         }
         return { kind: "agent", workflow };
     });
@@ -183,7 +143,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         await ownedSession(t, lease, workflow.id);
         if (exists)
             return;
-        const definition = await leafDefinition(t, workflow, body, request);
+        const definition = leafDefinition(workflow, body, request);
         const lookup = await sandboxLookup(t, workflow.sandboxOwnerId);
         const sandboxOwnerId = sessionSandboxSpec(workflow) || workflow.sandboxOwnerId
             ? owningSandboxSessionId(workflow, lookup)
@@ -207,7 +167,6 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             },
             vaultIds: workflow.vaultIds,
             credentialSelections: workflow.credentialSelections,
-            pluginRoots: definition.pluginRoots ?? {},
             ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
             ...(inherited
                 ? { sandbox: inherited.spec, sandboxSource: "shared" }
@@ -217,21 +176,19 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
     });
     // Binds this effect to the one linked turn its message opens (`linkedTurnEnd`).
     const idempotencyKey = linkedMessageKey(request);
-    const messageInput = body.input;
+    const messageInput = linkedMessageInput(body);
     const messageCommand = typeof messageInput === "string"
         ? {
             type: "message",
             content: messageInput,
             requestId: `flow-${request.effectId}`,
             idempotencyKey,
-            ...(body.manifest ? { manifest: body.manifest } : {}),
         }
         : {
             type: "message",
             data: messageInput,
             requestId: `flow-${request.effectId}`,
             idempotencyKey,
-            ...(body.manifest ? { manifest: body.manifest } : {}),
         };
     const accepted = (await command(ctx, agentSessionId, messageCommand, {
         kind: "application",
@@ -241,8 +198,8 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
     return store.tx(async (t) => {
         const s = await ownedSession(t, lease, request.sessionId);
         const agent = await sessionOf(t, agentSessionId);
-        // Only a Loop's own agent turns are iterations; a step elsewhere in the flow is not.
-        if (typeof request.context.loopPath === "string")
+        // Only a Loop body's agent turns are iterations: not its verifier, nor a step elsewhere.
+        if (typeof request.context.loopPath === "string" && request.context.role !== "verify-agent")
             await t.event(s.id, s.activeTurnId, "loop.iteration", {
                 path: request.context.loopPath,
                 n,
@@ -259,11 +216,10 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         // May already be settled if the agent was fast / replayed.
         const outcome = await linkedOutcome(t, { request, agentSessionId }, agent);
         if (outcome) {
-            await t.put("effects", request.effectId, {
-                request,
-                status: "completed",
+            await settleAgentEffect({
+                t,
+                effect: { request, status: "pending", agentSessionId },
                 outcome,
-                agentSessionId,
             });
             return { status: "completed", outcome };
         }
@@ -286,19 +242,18 @@ function inheritedSandbox(owner, definition) {
     return { spec, manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
 }
 /**
- * The credential of an MCP server request made on behalf of a session: from its attached vaults,
- * else the operator's credential resolver (`vault/sources.ts`).
+ * 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`).
  */
 export async function authorize(ctx, sessionId, request) {
     const s = await loadSession(ctx, sessionId);
     return ctx.credentials.authorize({ ...s, id: sessionId }, request);
 }
 /**
- * The definition a flow leaf's session runs. A v2 workflow embeds its leaves, so they
- * come from the workflow's own manifest and can't drift from it; v1 leaves come from the
- * registry by id.
+ * The definition a flow leaf's session runs. A flow agent embeds its leaves, so they come
+ * from the workflow's own manifest and can't drift from it.
  */
-async function leafDefinition(t, workflow, body, request) {
+function leafDefinition(workflow, body, request) {
     // A flow agent used as a tool: its manifest is inlined in the parent's pinned tool.
     if (request.context.role === "delegate" && !isWorkflowManifest(workflow.manifest)) {
         const flow = flowDelegateManifest(turnManifestOf(workflow), body.agentId);
@@ -308,35 +263,17 @@ async function leafDefinition(t, workflow, body, request) {
             manifest: flow,
             manifestHash: hashManifest(flow),
             implementationVersion: workflow.implementationVersion,
-            pluginRoots: leafPluginRoots(workflow.pluginRoots, body.agentId),
         };
     }
-    if (isWorkflowManifestV2(workflow.manifest)) {
-        const leaf = embeddedAgent(workflow.manifest, body.flow ?? [], body.agentId);
-        if (!leaf || isWorkflowManifestV2(leaf))
-            fail(404, `Agent '${body.agentId}' is not embedded in workflow '${workflow.manifest.id}'`);
-        const manifest = leaf;
-        return {
-            manifest,
-            manifestHash: hashManifest(manifest),
-            implementationVersion: workflow.implementationVersion,
-            pluginRoots: leafPluginRoots(workflow.pluginRoots, body.agentId),
-        };
-    }
-    const definition = await t.get("definitions", body.agentId);
-    if (!definition)
-        fail(404, "Definition not found");
-    return definition;
-}
-/**
- * A v2 workflow keys its leaves' plugin roots `<agentId>/<capability>`, and an agent keys
- * a flow agent it uses as a tool the same way (`<flowId>/<leafId>/<capability>`).
- */
-function leafPluginRoots(roots, agentId) {
-    const own = {};
-    const prefix = `${agentId}/`;
-    for (const [key, root] of Object.entries(roots ?? {}))
-        if (key.startsWith(prefix))
-            own[key.slice(prefix.length)] = root;
-    return own;
+    const leaf = isWorkflowManifest(workflow.manifest)
+        ? embeddedAgent(workflow.manifest, body.flow ?? [], body.agentId)
+        : undefined;
+    if (!leaf || isWorkflowManifest(leaf))
+        return fail(404, `Agent '${body.agentId}' is not embedded in workflow '${workflow.manifest.id}'`);
+    const manifest = leaf;
+    return {
+        manifest,
+        manifestHash: hashManifest(manifest),
+        implementationVersion: workflow.implementationVersion,
+    };
 }

package/dist/tenant/ephemeral.d.ts

@@ -15,6 +15,11 @@ export interface StartEphemeralRuntimeOptions {
     name?: string;
     /** An application key for an application principal of the Tenant. Default: a new key. */
     applicationKey?: string;
+    /**
+     * A management key (protocol 8), registered as the key `bootstrap` like
+     * `NYLORUN_MANAGEMENT_KEY_FILE`. Default: a new key.
+     */
+    managementKey?: string;
     adminKey?: string;
     principalId?: string;
     /**
@@ -22,14 +27,10 @@ export interface StartEphemeralRuntimeOptions {
      * admin key derives (`deriveStudioToken` in `@nylorun/admin`).
      */
     studioCredentialHash?: string;
-    /** Allowlisted baseline for childEnv (e.g. PATH). Never read from ambient here. */
-    baseline?: Readonly<Record<string, string>>;
     model?: TenantModelConfig;
     sandboxBackend?: "auto" | "virtual";
     /** When true, close() leaves hostRoot on disk. */
     retainRoot?: boolean;
-    /** Serve the Admin API on its own loopback listener (`adminUrl`). Default off. */
-    operatorListener?: boolean;
     /**
      * Trusted issuers whose JWTs the Tenant API accepts (Host feature `trusted-issuers`): the
      * issuers of an identity file (`parseIdentityFile`), or ones already built with
@@ -52,10 +53,10 @@ export interface StartEphemeralRuntimeOptions {
 }
 export interface EphemeralRuntime {
     url: string;
-    /** Where the Admin API answers: `url`, or the operator listener when requested. */
-    adminUrl: string;
     tenantId: string;
     applicationKey: string;
+    /** The Management API's key (`/v1/tenant/*`), principal `bootstrap`. */
+    managementKey: string;
     adminKey: string;
     principalId: string;
     hostRoot: string;

package/dist/tenant/ephemeral.js

@@ -65,7 +65,6 @@ export async function startEphemeralRuntime(options) {
             warn() { },
             error() { },
         };
-    const baseline = options.baseline ?? {};
     const model = options.model ?? { kind: "scripted", output: "ok" };
     const issuers = options.issuers === undefined
         ? undefined
@@ -84,11 +83,6 @@ export async function startEphemeralRuntime(options) {
             model,
             ...(issuers ? { issuers } : {}),
             ...(options.resolver ? { resolver: options.resolver } : {}),
-            childEnv: Object.freeze({
-                ...baseline,
-                HOME: tenant.home,
-                TMPDIR: tenant.tmp,
-            }),
             logger: createTenantLogger({
                 tenantId,
                 logPath: tenant.log,
@@ -100,6 +94,7 @@ export async function startEphemeralRuntime(options) {
         ? createPostgresClient(options.database)
         : undefined;
     const applicationKey = options.applicationKey ?? mintBearerToken();
+    const managementKey = options.managementKey ?? mintBearerToken();
     const principalId = options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
     const module = createTenantModule({
         open: createPostgresTenantOpener({
@@ -111,6 +106,7 @@ export async function startEphemeralRuntime(options) {
                 principals: hostPrincipals({
                     adminKey,
                     application: { principalId, key: applicationKey },
+                    bootstrapKey: managementKey,
                     ...(options.studioCredentialHash
                         ? { studioCredentialHash: options.studioCredentialHash }
                         : {}),
@@ -147,12 +143,8 @@ export async function startEphemeralRuntime(options) {
             hostRoot,
             module,
             config: hostConfig,
-            credentials,
             logger,
             coreVersion: coreVersion(),
-            ...(options.operatorListener
-                ? { operator: { host: "127.0.0.1", port: 0 } }
-                : {}),
         });
         // Opens the Tenant: creates it in the database first when it holds none.
         await host.listen();
@@ -173,9 +165,9 @@ export async function startEphemeralRuntime(options) {
     let closed = false;
     return {
         url: started.url,
-        adminUrl: started.adminUrl,
         tenantId,
         applicationKey,
+        managementKey,
         adminKey,
         principalId,
         hostRoot,

package/dist/tenant/host-token.js

@@ -17,7 +17,7 @@
  * The host token is accepted only by the Harness API listener (a connection serving that one
  * sandbox, and `host.renew`); the egress token only by egress-gate, as the proxy credential
  * (`Proxy-Authorization`). Neither is a bearer anywhere else: the Tenant API's bearer check
- * accepts trusted issuers' and delivery tokens only, and the gates run tokens only.
+ * accepts trusted issuers' tokens only, and the gates run tokens only.
  *
  * Verification reads the key row on every call (a revoked key refuses at once) and, with
  * `currentHost`, the sandbox's row (one indexed read): the epoch must be the sandbox's, the

package/dist/tenant/jwt.js

@@ -1,5 +1,5 @@
 /**
- * What the Runtime's own tokens share (delivery tokens, capability links, run and host tokens):
+ * What the Runtime's own tokens share (capability links, run and host tokens):
  * the Tenant's ES256 JWTs, recognised by shape, told apart by their `typ`, and refused before
  * any key is read when the header is not one the Runtime issues.
  */

package/dist/tenant/module.d.ts

@@ -1,4 +1,3 @@
-import type { StreamRelayStatus } from "@nylorun/core/contracts";
 import { TenantUnavailableError, type Logger, type TenantHandle, type TenantModule, type TenantOpener } from "./types.js";
 export interface CreateTenantModuleOptions {
     /** Opens the Host's Tenant (`store-pg.ts`). */
@@ -11,15 +10,13 @@ export interface CreateTenantModuleOptions {
      * Tenant's id (its stream relay). A failure is logged; the Tenant stays open.
      */
     onOpen?: (handle: TenantHandle) => void | Promise<void>;
-    /** This process's stream relay, for the Host aggregate (a Host with S2 runs one). */
-    relayStatus?: () => Promise<StreamRelayStatus>;
 }
 /**
  * Deep Tenant module (§8): the Host's one Tenant over an injected opener (tenancy.md §5).
  *
  * `start` opens it once, even when requests or Worker calls ask at the same time. An open that
  * fails for a reason in the Tenant (a `TenantOpenError`, or a timeout) is kept as the Tenant's
- * cause: the Host is not ready, `/v1/admin/status` names it, requests get the opaque 404.
+ * cause: the Host is not ready, `nylorun-operate status` names it, requests get the opaque 404.
  * One that fails outside the Tenant (`TenantUnavailableError`) is retried in the background
  * with backoff, and by the next request, which gets 503 meanwhile.
  */

package/dist/tenant/module.js

@@ -10,7 +10,7 @@ const RETRY_MAX_MS = 30_000;
  *
  * `start` opens it once, even when requests or Worker calls ask at the same time. An open that
  * fails for a reason in the Tenant (a `TenantOpenError`, or a timeout) is kept as the Tenant's
- * cause: the Host is not ready, `/v1/admin/status` names it, requests get the opaque 404.
+ * cause: the Host is not ready, `nylorun-operate status` names it, requests get the opaque 404.
  * One that fails outside the Tenant (`TenantUnavailableError`) is retried in the background
  * with backoff, and by the next request, which gets 503 meanwhile.
  */
@@ -148,18 +148,9 @@ export function createTenantModule(options) {
                     return { id: null, name: null, state: "unavailable", envelope: null };
             }
         },
-        async summarize() {
+        harnessStatus() {
             const now = current();
-            const summary = now.kind === "open" ? await now.handle.summary() : undefined;
-            const relay = await options.relayStatus?.().catch(() => undefined);
-            return {
-                runningSessions: summary?.runningSessions ?? 0,
-                inFlightDeliveries: summary?.inFlightDeliveries ?? 0,
-                pendingActions: summary?.pendingActions ?? 0,
-                uncertainEffects: summary?.uncertainEffects ?? 0,
-                ...(relay ? { relay } : {}),
-                ...(summary?.harness ? { harness: summary.harness } : {}),
-            };
+            return now.kind === "open" ? now.handle.harnessStatus?.() : undefined;
         },
         async close() {
             const previous = current();

package/dist/tenant/operator-keys.d.ts

@@ -1,18 +1,44 @@
+/**
+ * The Tenant's keys by name (F9 I1), managed through the Management API (`/v1/tenant/keys`,
+ * application keys only) and `nylorun-operate keys`. A key is a principal (F9-D11): its id is the key's name
+ * (`APPLICATION_KEY_ID_PATTERN`), the key is 64 hex characters (`mintBearerToken`), and the
+ * Tenant keeps only its SHA-256. Putting a key creates the principal or rotates its key;
+ * deleting it removes the row. Either way the old key stops authenticating on its next request,
+ * since authentication reads the principal on every request (`auth.ts`).
+ *
+ * `studio` is derived from the admin key (F9-D9): it is never put or deleted here. `bootstrap` is
+ * the management key a Host registers from `NYLORUN_MANAGEMENT_KEY_FILE`: its file is its only
+ * source. A key has a role (protocol 8): `application` reaches the Runtime API, `management` the
+ * Management API; a key keeps its role when it is rotated.
+ */
+import { type KeyRole } from "@nylorun/core/compatibility";
 import type { OperatorKey, PutOperatorKeyResponse } from "@nylorun/core/contracts";
 import type { SessionStore } from "../store/types.js";
-/** Why a key id is refused: not a key name, or the reserved `studio`. */
+/**
+ * Why a key is refused: not a key name, a reserved id (`studio`, `bootstrap`), or an id that
+ * holds the other role (`role`).
+ */
 export type OperatorKeyRefusal = {
-    reason: "invalid" | "reserved";
+    reason: "invalid" | "reserved" | "role";
     message: string;
 };
-/** The refusal for `id`, or undefined when operator keys may use it. */
-export declare function refuseOperatorKeyId(id: string): OperatorKeyRefusal | undefined;
+/**
+ * The refusal for `id`, or undefined when it may be `put` or deleted. `bootstrap` is never put
+ * here (its file is its only source) but may be deleted on the machine (AP18).
+ */
+export declare function refuseOperatorKeyId(id: string, purpose?: "put" | "delete"): OperatorKeyRefusal | undefined;
 export interface OperatorKeys {
     /** Every principal of the Tenant, by id (Studio's and derived ones included). */
     list(): Promise<OperatorKey[]>;
-    /** Creates key `id` or rotates it; the key is returned this once. */
-    put(id: string): Promise<PutOperatorKeyResponse | OperatorKeyRefusal>;
-    /** Deletes key `id`: false when there is none. */
-    delete(id: string): Promise<boolean | OperatorKeyRefusal>;
+    /**
+     * Creates key `id` with `role` (default `application`) or rotates it; the key is returned
+     * this once. An id that holds the other role is refused.
+     */
+    put(id: string, role?: Exclude<KeyRole, "studio">): Promise<PutOperatorKeyResponse | OperatorKeyRefusal>;
+    /**
+     * Deletes key `id`: false when there is none. With `role`, a key of another role is refused
+     * (the Management API deletes application keys only).
+     */
+    delete(id: string, role?: Exclude<KeyRole, "studio">): Promise<boolean | OperatorKeyRefusal>;
 }
 export declare function operatorKeys(store: SessionStore, now?: () => string): OperatorKeys;

package/dist/tenant/operator-keys.js

@@ -1,18 +1,25 @@
 /**
- * Operator keys (F9 I1, Host feature `operator-keys`): the Tenant's application keys, managed
- * by name through the Admin API. A key is a principal (F9-D11): its id is the key's name
+ * The Tenant's keys by name (F9 I1), managed through the Management API (`/v1/tenant/keys`,
+ * application keys only) and `nylorun-operate keys`. A key is a principal (F9-D11): its id is the key's name
  * (`APPLICATION_KEY_ID_PATTERN`), the key is 64 hex characters (`mintBearerToken`), and the
  * Tenant keeps only its SHA-256. Putting a key creates the principal or rotates its key;
  * deleting it removes the row. Either way the old key stops authenticating on its next request,
  * since authentication reads the principal on every request (`auth.ts`).
  *
- * `studio` is derived from the admin key (F9-D9): it is never put or deleted here.
+ * `studio` is derived from the admin key (F9-D9): it is never put or deleted here. `bootstrap` is
+ * the management key a Host registers from `NYLORUN_MANAGEMENT_KEY_FILE`: its file is its only
+ * source. A key has a role (protocol 8): `application` reaches the Runtime API, `management` the
+ * Management API; a key keeps its role when it is rotated.
  */
-import { APPLICATION_KEY_ID_PATTERN } from "@nylorun/core/compatibility";
+import { APPLICATION_KEY_ID_PATTERN, BOOTSTRAP_KEY_ID, } from "@nylorun/core/compatibility";
 import { hashToken, mintBearerToken } from "../core/bearer.js";
+import { PrincipalRoleConflict } from "../store/ownership.js";
 import { STUDIO_PRINCIPAL_ID } from "./principals.js";
-/** The refusal for `id`, or undefined when operator keys may use it. */
-export function refuseOperatorKeyId(id) {
+/**
+ * The refusal for `id`, or undefined when it may be `put` or deleted. `bootstrap` is never put
+ * here (its file is its only source) but may be deleted on the machine (AP18).
+ */
+export function refuseOperatorKeyId(id, purpose = "put") {
     if (!APPLICATION_KEY_ID_PATTERN.test(id))
         return {
             reason: "invalid",
@@ -23,6 +30,11 @@ export function refuseOperatorKeyId(id) {
             reason: "reserved",
             message: "The studio key is derived from the admin key: it is not put or deleted here",
         };
+    if (id === BOOTSTRAP_KEY_ID && purpose === "put")
+        return {
+            reason: "reserved",
+            message: "The bootstrap key comes from NYLORUN_MANAGEMENT_KEY_FILE: change that file to rotate it",
+        };
     return undefined;
 }
 export function operatorKeys(store, now = () => new Date().toISOString()) {
@@ -31,25 +43,45 @@ export function operatorKeys(store, now = () => new Date().toISOString()) {
             const rows = await store.tx((t) => t.listPrincipals());
             return rows.map(({ id, role, createdAt }) => ({ id, role, createdAt }));
         },
-        async put(id) {
+        async put(id, role = "application") {
             const refused = refuseOperatorKeyId(id);
             if (refused)
                 return refused;
             const key = mintBearerToken();
-            const { row, rotated } = await store.tx(async (t) => {
-                const existing = await t.principalById(id);
-                return {
-                    row: await t.putPrincipal(id, hashToken(key), now()),
-                    rotated: existing !== undefined,
-                };
-            });
-            return { id: row.id, role: row.role, createdAt: row.createdAt, key, rotated };
+            try {
+                const { row, rotated } = await store.tx(async (t) => {
+                    const existing = await t.principalById(id);
+                    return {
+                        row: await t.putPrincipal(id, hashToken(key), now(), role),
+                        rotated: existing !== undefined,
+                    };
+                });
+                return { id: row.id, role: row.role, createdAt: row.createdAt, key, rotated };
+            }
+            catch (error) {
+                if (error instanceof PrincipalRoleConflict)
+                    return {
+                        reason: "role",
+                        message: `Key ${id} is not a${role === "application" ? "n application" : " management"} key: delete it first, or choose another name`,
+                    };
+                throw error;
+            }
         },
-        async delete(id) {
-            const refused = refuseOperatorKeyId(id);
+        async delete(id, role) {
+            const refused = refuseOperatorKeyId(id, "delete");
             if (refused)
                 return refused;
-            return await store.tx((t) => t.deletePrincipal(id));
+            return await store.tx(async (t) => {
+                if (role !== undefined) {
+                    const existing = await t.principalById(id);
+                    if (existing && existing.role !== role)
+                        return {
+                            reason: "role",
+                            message: `Key ${id} is a ${existing.role} key: only the Tenant's machine manages it (nylorun-operate)`,
+                        };
+                }
+                return await t.deletePrincipal(id);
+            });
         },
     };
 }

package/dist/tenant/outbound.d.ts

@@ -36,11 +36,15 @@ export declare const MAX_RESPONSE_BYTES: number;
 export declare function isPrivateAddress(address: string): boolean;
 /** Why the Host refuses `url`, or `undefined` when it may be called. */
 export declare function refusal(url: URL, policy: OutboundPolicy): string | undefined;
-/** POSTs `body` to `url` under `policy`. Never throws; `signal` aborts the request. */
+/**
+ * POSTs (or, with `method`, PUTs or PATCHes) the JSON `body` to `url` under `policy`. Never
+ * throws; `signal` aborts the request.
+ */
 export declare function post(target: string, body: string, headers: Record<string, string>, options: {
     policy: OutboundPolicy;
     signal: AbortSignal;
     maxResponseBytes?: number;
+    method?: "POST" | "PUT" | "PATCH";
 }): Promise<OutboundResult>;
 /**
  * A refusal of `guardedFetch`: the Host's policy forbids the URL or every address it resolves
@@ -67,8 +71,13 @@ export declare const FETCH_TIMEOUT_MS = 30000;
  * unless the caller passes a signal. The gateway calls OAuth discovery, registration, the code
  * exchange and refresh with it. A refused URL or address rejects with `OutboundRefused`, any
  * other failure with `OutboundFailed`.
+ *
+ * `stream`: the Response resolves once the headers arrive and its body streams, unbounded and
+ * with no timeout but the caller's signal: remote MCP servers, whose answers and event streams
+ * stay open (`mcp/connect.ts`).
  */
 export declare function guardedFetch(policy: OutboundPolicy, options?: {
     maxResponseBytes?: number;
     timeoutMs?: number;
+    stream?: boolean;
 }): typeof fetch;