@nylorun/runtime 0.6.0-beta → 0.8.0-beta

package/dist/core/runtime.js

@@ -1,12 +1,26 @@
 import { createServer, } from "node:http";
 import { randomUUID, timingSafeEqual } from "node:crypto";
-import { mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync, } from "node:fs";
-import { dirname } from "node:path";
-import { AgentManifestSchema, PutAgentRequestSchema, PutSessionRequestSchema, SessionCommandSchema, ActionClaimRequestSchema, ActionHeartbeatRequestSchema, } from "@nylorun/core/contracts";
+import { mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync, realpathSync, mkdtempSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { AgentManifestSchema, CreateCredentialRequestSchema, CreateVaultRequestSchema, PutAgentRequestSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutSessionRequestSchema, RegisterExecutorsRequestSchema, RotateCredentialRequestSchema, SessionCommandSchema, ActionClaimRequestSchema, ActionHeartbeatRequestSchema, } from "@nylorun/core/contracts";
 import { createDurableCheckpoint, runDurable, } from "@nylorun/harness/run";
 import { hashManifest } from "@nylorun/core/compatibility";
+import { schemaFromJSON, } from "@nylorun/core/define";
 import { Store, canonical } from "./store.js";
+import { ExecutorRegistry, assertExecutorCredential, hashToken, } from "./executors.js";
+import { RUNTIME_VERSION } from "../version.js";
+import { hostModelCatalog } from "../model/catalog.js";
+import { piModel } from "../model/pi-model.js";
 import { scriptedModel } from "./provider.js";
+import { scrub } from "../redact.js";
+import { createKekFile, defaultKekPath, readVaultKek } from "../vault/kek.js";
+import { VaultError } from "../vault/error.js";
+import { VaultService } from "../vault/service.js";
+import { McpPool } from "../mcp/pool.js";
+import { SandboxManager, sandboxCapabilityOf } from "../sandbox/manager.js";
+import { defaultSandboxBackends } from "../sandbox/select.js";
 class HttpError extends Error {
     status;
     constructor(status, message) {
@@ -17,10 +31,82 @@ class HttpError extends Error {
 const fail = (status, message) => {
     throw new HttpError(status, message);
 };
+function sessionToolsOf(snapshot) {
+    if (!snapshot?.mcpTools.length)
+        return undefined;
+    return snapshot.mcpTools.map((tool) => ({
+        capabilityId: tool.capabilityId,
+        name: tool.name,
+        ...(tool.description === undefined
+            ? {}
+            : { description: tool.description }),
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined
+            ? {}
+            : { outputSchema: tool.outputSchema }),
+    }));
+}
+function mcpToolOf(session, capabilityId, toolName) {
+    return session.mcpSnapshot?.mcpTools.find((tool) => tool.capabilityId === capabilityId && tool.name === toolName);
+}
+function pinnedTool(manifest, capabilityId, toolName) {
+    const capability = manifest.capabilities.find((item) => item.id === capabilityId);
+    return capability?.tools?.find((tool) => tool.name === toolName);
+}
+function acceptedToolResult(action, command) {
+    if (action.kind !== "tool" || !action.outputSchema)
+        return command;
+    const value = command.outcome.value;
+    if (isFailedToolValue(value))
+        return command;
+    // Executors wrap successful tool output as `{ kind: "completed", output }`.
+    // Validate the tool payload, not the outcome envelope.
+    const candidate = completedToolOutput(value);
+    let matches = false;
+    try {
+        matches = schemaFromJSON(action.outputSchema).validate(candidate).ok;
+    }
+    catch {
+        matches = false;
+    }
+    if (matches)
+        return command;
+    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",
+            },
+        },
+    };
+}
+function completedToolOutput(value) {
+    if (value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.kind === "completed" &&
+        "output" in value) {
+        return value.output;
+    }
+    return value;
+}
+function isFailedToolValue(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.kind === "failed");
+}
 const semantic = (value) => {
     const { requestId: _, ...body } = value;
     return canonical(body);
 };
+const sessionIdentity = (value) => {
+    const { requestId: _requestId, vaultIds: _vaultIds, credentialSelections: _selections, ...body } = value ?? {};
+    return canonical(body);
+};
 const equals = (a, b) => {
     const aa = Buffer.from(a), bb = Buffer.from(b);
     return aa.length === bb.length && timingSafeEqual(aa, bb);
@@ -28,12 +114,21 @@ const equals = (a, b) => {
 export class CoreRuntime {
     options;
     store;
+    vault;
+    kek;
+    kekPath;
     running = new Map();
     pending = new Set();
     observers = new Map();
-    executors = new Set();
+    // Keyed by token hash so a rotation can end exactly the streams that the replaced token owns.
+    executorStreams = new Map();
+    registry = new ExecutorRegistry();
+    scopeId;
+    mcp;
+    sandbox;
     server;
     closing = false;
+    closed = false;
     lockPath;
     timer;
     constructor(options) {
@@ -46,12 +141,8 @@ export class CoreRuntime {
             throw new Error("Executor tokens must be unique");
         if (!options.serverToken || options.serverToken.length < 16)
             throw new Error("A server token of at least 16 characters is required");
-        if (options.executors.some((e) => e.token.length < 16 ||
-            equals(e.token, options.serverToken) ||
-            !e.agentId ||
-            !e.manifestHash ||
-            !e.implementationVersion))
-            throw new Error("Executor tokens require independent credentials and exact definition scope");
+        for (const executor of options.executors)
+            assertExecutorCredential(executor, options.serverToken);
         if (options.sqlitePath !== ":memory:") {
             mkdirSync(dirname(options.sqlitePath), { recursive: true });
             this.lockPath = options.sqlitePath + ".runtime-lock";
@@ -78,14 +169,93 @@ export class CoreRuntime {
             writeFileSync(fd, String(process.pid));
             closeSync(fd);
         }
+        this.kekPath = options.vaultKekPath ?? defaultKekPath();
+        let store;
         try {
-            this.store = new Store(options.sqlitePath);
+            store = new Store(options.sqlitePath);
+            this.kek = readVaultKek({
+                vaultKek: options.vaultKek,
+                vaultKekPath: this.kekPath,
+            });
+            if (store.credentialCount() > 0 && !this.kek)
+                throw new Error("Vault key-encryption key is required to open this database");
+            this.store = store;
         }
         catch (e) {
+            store?.db.close();
             if (this.lockPath)
                 unlinkSync(this.lockPath);
             throw e;
         }
+        // A short digest of the resolved database path identifies this scope to the CLI without
+        // disclosing the path itself over the unauthenticated health route.
+        this.scopeId =
+            options.sqlitePath === ":memory:"
+                ? "memory"
+                : createHash("sha256")
+                    .update(realpathSync(options.sqlitePath))
+                    .digest("hex")
+                    .slice(0, 16);
+        // Registrations persisted by PUT /v1/executors load first; scopes supplied through
+        // NYLORUN_EXECUTORS_JSON then overlay them for this process only and are never written back.
+        this.registry.seed(this.store.allExecutors().map((row) => ({
+            agentId: row.agentId,
+            implementationVersion: row.implementationVersion,
+            ...(row.manifestHash === undefined
+                ? {}
+                : { manifestHash: row.manifestHash }),
+            tokenHash: row.tokenHash,
+            persisted: true,
+            updatedAt: row.updatedAt,
+        })));
+        const now = new Date().toISOString();
+        for (const executor of options.executors) {
+            const tokenHash = hashToken(executor.token);
+            const collision = this.registry.find(tokenHash);
+            if (collision && collision.agentId !== executor.agentId) {
+                this.store.db.close();
+                if (this.lockPath)
+                    unlinkSync(this.lockPath);
+                throw new Error("Executor tokens must be unique");
+            }
+            this.registry.upsert({
+                agentId: executor.agentId,
+                implementationVersion: executor.implementationVersion,
+                ...(executor.manifestHash === undefined
+                    ? {}
+                    : { manifestHash: executor.manifestHash }),
+                tokenHash,
+                persisted: false,
+                updatedAt: now,
+            });
+        }
+        this.vault = new VaultService(this.store.db, (fn) => this.store.tx(fn), () => this.ensureKek(), options.vaultFetch ?? globalThis.fetch);
+        this.mcp = new McpPool({
+            dataDir: dirname(options.sqlitePath),
+            authorize: (sessionId, request) => this.authorize(sessionId, request),
+        });
+        const ephemeral = options.sqlitePath === ":memory:";
+        const sandboxRoot = options.sandbox?.root ??
+            (ephemeral
+                ? mkdtempSync(join(tmpdir(), "nylorun-sandboxes-"))
+                : join(dirname(options.sqlitePath), "sandboxes"));
+        this.sandbox = new SandboxManager({
+            scope: ephemeral ? `m${randomUUID().slice(0, 8)}` : this.scopeId,
+            store: this.store,
+            backends: options.sandbox?.backends ?? defaultSandboxBackends({ root: sandboxRoot }),
+            preference: options.sandbox?.backend ?? process.env.NYLORUN_SANDBOX,
+            ephemeral,
+            emit: (sessionId, turnId, type, payload) => {
+                if (this.closed)
+                    return;
+                const event = this.store.tx(() => this.store.event(sessionId, turnId, type, payload));
+                this.publish(event);
+            },
+        });
+        if (!ephemeral && this.sandbox.hasRecords())
+            void this.sandbox
+                .reconcile((id) => !this.closed && !!this.store.get("sessions", id))
+                .catch(() => undefined);
         this.store.tx(() => {
             for (const effect of this.store.all("effects"))
                 if (effect.status === "invoking") {
@@ -103,6 +273,7 @@ export class CoreRuntime {
                     }
                 }
         });
+        this.retireLegacyHooks();
         this.expireClaims();
         this.timer = setInterval(() => this.expireClaims(), Math.min(options.leaseMs ?? 30000, 5000));
         this.timer.unref();
@@ -122,15 +293,53 @@ export class CoreRuntime {
             response.destroy();
     }
     notify() {
-        for (const response of this.executors)
-            this.send(response, 'event: work_available\ndata: {"type":"work_available"}\n\n');
+        for (const streams of this.executorStreams.values())
+            for (const response of streams)
+                this.send(response, 'event: work_available\ndata: {"type":"work_available"}\n\n');
+    }
+    /**
+     * Manifest v4 replaced beforeModelCall/afterModelCall with scoped hooks. Turns started under
+     * an older manifest cannot continue, and their hook actions no longer parse, so end them.
+     */
+    retireLegacyHooks() {
+        this.store.tx(() => {
+            for (const action of this.store.all("actions"))
+                if ((action.kind === "beforeModelCall" || action.kind === "afterModelCall") &&
+                    (action.status === "pending" || action.status === "claimed")) {
+                    action.status = "cancelled";
+                    this.store.put("actions", action.actionId, action);
+                }
+            for (const s of this.store.all("sessions"))
+                if (s.activeTurnId && s.manifest?.manifestSchemaVersion !== 4) {
+                    this.store.event(s.id, s.activeTurnId, "turn.failed", {
+                        error: {
+                            code: "execution.incompatible",
+                            message: "This turn started under manifest schema 3; see MIGRATION.md for before/after hooks",
+                        },
+                    });
+                    s.status = "failed";
+                    s.activeTurnId = null;
+                    this.store.put("sessions", s.id, s);
+                }
+        });
     }
     expireClaims() {
         const events = [];
+        let redeliver = false;
         this.store.tx(() => {
             for (const action of this.store.all("actions"))
                 if (action.status === "claimed" &&
                     Date.parse(action.leaseExpiresAt) <= Date.now()) {
+                    if (action.kind === "hook") {
+                        // Hooks are pure by contract, so a lost claim is simply delivered again.
+                        // The next claim bumps the generation, which fences any late result.
+                        action.status = "pending";
+                        action.claimId = null;
+                        action.leaseExpiresAt = null;
+                        this.store.put("actions", action.actionId, action);
+                        redeliver = true;
+                        continue;
+                    }
                     action.status = "uncertain";
                     this.store.put("actions", action.actionId, action);
                     const effect = this.store.get("effects", action.actionId);
@@ -147,6 +356,8 @@ export class CoreRuntime {
                 }
         });
         events.forEach((e) => this.publish(e));
+        if (redeliver)
+            this.notify();
     }
     schedule(id) {
         if (this.closing)
@@ -166,10 +377,13 @@ export class CoreRuntime {
         const controller = new AbortController();
         this.running.set(id, controller);
         try {
+            await this.prepareMcp(id, controller.signal);
+            const current = this.session(id);
             const result = await runDurable({
-                manifest: s.manifest,
-                checkpoint: s.checkpoint,
+                manifest: current.manifest,
+                checkpoint: current.checkpoint,
                 signal: controller.signal,
+                sessionTools: sessionToolsOf(current.mcpSnapshot),
                 host: {
                     resolveEffect: (e) => this.resolveEffect(e, controller.signal),
                 },
@@ -258,8 +472,22 @@ export class CoreRuntime {
                 this.schedule(id);
         }
     }
+    invokeModel(request, signal) {
+        if (!this.options.useHostModel)
+            return (this.options.model ?? scriptedModel())(request, signal);
+        const adapter = piModel({
+            readHostModel: () => this.vault.readHostModel(),
+            writeHostCredential: (credential) => this.vault.updateHostCredential(credential),
+        });
+        return adapter(request.input, {
+            request: request.context.request,
+            invocationId: String(request.context.invocationId),
+            signal,
+            reportPreparedCall() { },
+        });
+    }
     async resolveEffect(request, signal) {
-        let invoke = false;
+        let invoke;
         let notify = false;
         let event;
         const resolution = this.store.tx(() => {
@@ -281,24 +509,32 @@ export class CoreRuntime {
                             : "pending",
                     };
             }
+            const mcpTool = request.kind === "tool"
+                ? mcpToolOf(s, request.capabilityId, request.toolName)
+                : undefined;
+            const sandboxTool = request.kind === "tool" && !mcpTool
+                ? sandboxCapabilityOf(s.manifest, request.capabilityId, request.toolName)
+                : undefined;
             this.store.put("effects", request.effectId, {
                 request,
-                status: request.kind === "model" ? "invoking" : "pending",
+                status: request.kind === "model" || mcpTool || sandboxTool
+                    ? "invoking"
+                    : "pending",
             });
-            if (request.kind === "model") {
-                invoke = true;
+            if (request.kind === "model" || mcpTool || sandboxTool) {
+                invoke = mcpTool ? "mcp" : sandboxTool ? "sandbox" : "model";
                 return undefined;
             }
-            const action = {
+            const tool = request.kind === "tool"
+                ? pinnedTool(s.manifest, request.capabilityId, request.toolName)
+                : undefined;
+            const base = {
                 actionId: request.effectId,
                 sessionId: request.sessionId,
                 turnId: request.turnId,
                 agentId: request.agentId,
                 manifestHash: request.manifestHash,
                 implementationVersion: s.implementationVersion,
-                kind: request.kind,
-                capabilityId: request.capabilityId,
-                ...(request.toolName ? { toolName: request.toolName } : {}),
                 input: request.input,
                 context: request.context,
                 status: "pending",
@@ -306,11 +542,29 @@ export class CoreRuntime {
                 claimId: null,
                 leaseExpiresAt: null,
             };
+            const action = request.kind === "hook"
+                ? {
+                    ...base,
+                    kind: "hook",
+                    hook: {
+                        at: request.hook.at,
+                        scope: request.hook.scope,
+                        capabilityIds: [...request.hook.capabilityIds],
+                    },
+                }
+                : {
+                    ...base,
+                    kind: "tool",
+                    capabilityId: request.capabilityId,
+                    toolName: request.toolName,
+                    ...(tool?.inputSchema ? { inputSchema: tool.inputSchema } : {}),
+                    ...(tool?.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+                };
             this.store.put("actions", action.actionId, action);
             event = this.store.event(s.id, s.activeTurnId, "action.pending", {
                 actionId: action.actionId,
                 kind: action.kind,
-                toolName: action.toolName,
+                ...actionTarget(action),
                 input: action.input,
             });
             notify = true;
@@ -323,7 +577,11 @@ export class CoreRuntime {
         if (!invoke)
             return resolution;
         try {
-            const value = await (this.options.model ?? scriptedModel())(request, signal);
+            const value = invoke === "mcp"
+                ? await this.callMcpTool(request)
+                : invoke === "sandbox"
+                    ? await this.callSandboxTool(request, signal)
+                    : await this.invokeModel(request, signal);
             return this.store.tx(() => {
                 const s = this.session(request.sessionId);
                 if (s.status === "cancelled" ||
@@ -359,18 +617,19 @@ export class CoreRuntime {
     scope(request) {
         const header = request.headers.authorization;
         const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
-        if (token && equals(token, this.options.serverToken))
+        if (!token)
+            return fail(401, "Invalid credentials");
+        if (equals(token, this.options.serverToken))
             return "server";
-        const executor = this.options.executors.find((e) => token && equals(token, e.token));
+        // The map is keyed by a digest of the presented token, so the lookup reveals nothing the
+        // caller does not already hold; the server token keeps its constant-time comparison.
+        const executor = this.registry.find(hashToken(token));
         if (!executor)
             return fail(401, "Invalid credentials");
         return executor;
     }
     scoped(scope, action) {
-        if (scope === "server" ||
-            scope.agentId !== action.agentId ||
-            scope.manifestHash !== action.manifestHash ||
-            scope.implementationVersion !== action.implementationVersion)
+        if (scope === "server" || scope.agentId !== action.agentId)
             fail(403, "Executor scope does not authorize this action");
     }
     async body(request) {
@@ -387,21 +646,23 @@ export class CoreRuntime {
             return fail(400, "Invalid JSON");
         }
     }
-    command(id, command, scope) {
+    command(id, input, scope) {
         let event;
         let schedule = false;
         const response = this.store.tx(() => {
             const s = this.session(id);
-            const key = JSON.stringify([id, command.idempotencyKey]);
+            let command = input;
             if (command.type === "action_result") {
                 const a = this.store.get("actions", command.actionId) ??
                     fail(404, "Action not found");
                 if (a.sessionId !== id)
                     fail(403, "Action belongs to another session");
                 this.scoped(scope, a);
+                command = acceptedToolResult(a, command);
             }
             else if (scope !== "server")
                 fail(403, "Application credential required");
+            const key = JSON.stringify([id, command.idempotencyKey]);
             const existing = this.store.get("commands", key);
             if (existing) {
                 if (semantic(existing.command) !== semantic(command))
@@ -434,7 +695,7 @@ export class CoreRuntime {
                 schedule = true;
                 event = this.store.event(id, s.activeTurnId, "action.completed", {
                     actionId: action.actionId,
-                    toolName: action.toolName,
+                    ...actionTarget(action),
                     kind: action.kind,
                     result: command.outcome.value,
                 });
@@ -544,13 +805,13 @@ export class CoreRuntime {
         });
         if (event)
             this.publish(event);
-        if (command.type === "cancel")
+        if (input.type === "cancel")
             this.running.get(id)?.abort();
         if (schedule)
             this.schedule(id);
         return response;
     }
-    sse(request, response, set) {
+    sse(request, response, set, whenEmpty) {
         response.writeHead(200, {
             "content-type": "text/event-stream",
             "cache-control": "no-cache",
@@ -564,6 +825,8 @@ export class CoreRuntime {
         request.on("close", () => {
             clearInterval(timer);
             set.delete(response);
+            if (!set.size)
+                whenEmpty?.();
         });
     }
     async handle(request, response) {
@@ -579,7 +842,13 @@ export class CoreRuntime {
                 .map(decodeURIComponent);
             const method = request.method;
             if (url.pathname === "/health")
-                return json({ status: "ok", service: "oss-runtime" });
+                return json({
+                    status: "ok",
+                    service: "oss-runtime",
+                    version: RUNTIME_VERSION,
+                    scopeId: this.scopeId,
+                    pid: process.pid,
+                });
             if (url.pathname === "/ready") {
                 this.store.db.prepare("SELECT 1").get();
                 return json({
@@ -600,7 +869,11 @@ export class CoreRuntime {
                 method === "GET") {
                 if (scope === "server")
                     fail(403, "Executor credential required");
-                this.sse(request, response, this.executors);
+                const tokenHash = scope.tokenHash;
+                let streams = this.executorStreams.get(tokenHash);
+                if (!streams)
+                    this.executorStreams.set(tokenHash, (streams = new Set()));
+                this.sse(request, response, streams, () => this.executorStreams.delete(tokenHash));
                 this.send(response, 'event: work_available\ndata: {"type":"work_available"}\n\n');
                 return;
             }
@@ -612,10 +885,7 @@ export class CoreRuntime {
                     return json({
                         actions: this.store
                             .all("actions")
-                            .filter((a) => a.status === "pending" &&
-                            a.agentId === scope.agentId &&
-                            a.manifestHash === scope.manifestHash &&
-                            a.implementationVersion === scope.implementationVersion),
+                            .filter((a) => a.status === "pending" && a.agentId === scope.agentId),
                     });
                 const actionId = path[2];
                 if (!actionId)
@@ -627,10 +897,7 @@ export class CoreRuntime {
                         fail(404, "Action not found");
                     this.scoped(scope, action);
                     if (method === "POST" && path[3] === "claim") {
-                        const claim = ActionClaimRequestSchema.parse(body);
-                        if (claim.manifestHash !== action.manifestHash ||
-                            claim.implementationVersion !== action.implementationVersion)
-                            fail(409, "Definition mismatch");
+                        ActionClaimRequestSchema.parse(body);
                         if (action.status !== "pending" ||
                             this.session(action.sessionId).status === "cancelled" ||
                             this.session(action.sessionId).activeTurnId !== action.turnId)
@@ -671,13 +938,104 @@ export class CoreRuntime {
                 path[3] === "commands" &&
                 method === "POST")
                 return json(this.command(path[2], SessionCommandSchema.parse(await this.body(request)), scope));
+            if (path[1] === "vaults")
+                return json(await this.dispatchVault(scope, method, path, url, request));
+            if (path[1] === "host")
+                return json(await this.dispatchHost(scope, method, path, request));
             if (scope !== "server")
                 fail(403, "Application credential required");
+            if (path[1] === "executors" && path.length === 2 && method === "GET")
+                return json({
+                    executors: this.registry.list().map((e) => ({
+                        agentId: e.agentId,
+                        implementationVersion: e.implementationVersion,
+                        ...(e.manifestHash === undefined
+                            ? {}
+                            : { manifestHash: e.manifestHash }),
+                        connected: (this.executorStreams.get(e.tokenHash)?.size ?? 0) > 0,
+                        updatedAt: e.updatedAt,
+                    })),
+                });
+            // The length guard matters: the connect branch above only matches GET, so without it a
+            // PUT to /v1/executors/connect would register an agent literally named "connect".
+            if (path[1] === "executors" && path.length === 2 && method === "PUT") {
+                const body = RegisterExecutorsRequestSchema.parse(await this.body(request));
+                // Credential rules are shared with startup validation, which throws plainly; on the
+                // wire a rejected registration is a bad request, not a server fault.
+                try {
+                    for (const executor of body.executors)
+                        assertExecutorCredential(executor, this.options.serverToken);
+                }
+                catch (error) {
+                    fail(400, error instanceof Error ? error.message : String(error));
+                }
+                if (new Set(body.executors.map((e) => e.agentId)).size !==
+                    body.executors.length ||
+                    new Set(body.executors.map((e) => e.token)).size !==
+                        body.executors.length)
+                    fail(400, "Executor registrations must be unique per agent and token");
+                const updatedAt = new Date().toISOString();
+                const records = body.executors.map((executor) => ({
+                    agentId: executor.agentId,
+                    implementationVersion: executor.implementationVersion,
+                    ...(executor.manifestHash === undefined
+                        ? {}
+                        : { manifestHash: executor.manifestHash }),
+                    tokenHash: hashToken(executor.token),
+                    persisted: true,
+                    updatedAt,
+                }));
+                for (const record of records) {
+                    const collision = this.registry.find(record.tokenHash);
+                    if (collision && collision.agentId !== record.agentId)
+                        fail(409, "Executor tokens must be unique");
+                }
+                // Persist the whole batch first; the in-memory registry must never run ahead of SQLite.
+                this.store.tx(() => {
+                    for (const record of records)
+                        this.store.putExecutor({
+                            agentId: record.agentId,
+                            tokenHash: record.tokenHash,
+                            implementationVersion: record.implementationVersion,
+                            ...(record.manifestHash === undefined
+                                ? {}
+                                : { manifestHash: record.manifestHash }),
+                            updatedAt,
+                        });
+                });
+                const results = records.map((record) => {
+                    const { rotated, previousHash } = this.registry.upsert(record);
+                    if (rotated && previousHash) {
+                        for (const r of this.executorStreams.get(previousHash) ?? [])
+                            r.end();
+                        this.executorStreams.delete(previousHash);
+                    }
+                    return {
+                        agentId: record.agentId,
+                        implementationVersion: record.implementationVersion,
+                        rotated,
+                    };
+                });
+                return json({ executors: results });
+            }
+            if (path[1] === "executors" &&
+                path.length === 3 &&
+                path[2] &&
+                method === "DELETE") {
+                const agentId = path[2];
+                const existing = this.registry.get(agentId) ?? fail(404, "Executor not found");
+                if (!existing.persisted)
+                    fail(409, "Executor is provided by NYLORUN_EXECUTORS_JSON and cannot be deleted");
+                this.store.tx(() => this.store.deleteExecutor(agentId));
+                this.registry.remove(agentId);
+                for (const r of this.executorStreams.get(existing.tokenHash) ?? [])
+                    r.end();
+                this.executorStreams.delete(existing.tokenHash);
+                return json({ agentId, deleted: true });
+            }
             if (path[1] === "agents" && path.length === 2 && method === "GET")
                 return json({
-                    agents: this.store
-                        .all("definitions")
-                        .map((d) => ({
+                    agents: this.store.all("definitions").map((d) => ({
                         agentId: d.manifest.id,
                         manifest: d.manifest,
                         manifestHash: d.manifestHash,
@@ -723,11 +1081,19 @@ export class CoreRuntime {
                 const id = path[2];
                 if (method === "PUT" && path.length === 3) {
                     const body = PutSessionRequestSchema.parse(await this.body(request));
+                    const vaultIds = body.vaultIds ?? [];
+                    const credentialSelections = body.credentialSelections ?? [];
                     const result = this.store.tx(() => {
+                        this.vault.assertAttachment(body.ownerUserId, vaultIds, credentialSelections);
                         const prior = this.store.get("sessions", id);
                         if (prior) {
-                            if (semantic(prior.creation) !== semantic(body))
+                            if (sessionIdentity(prior.creation) !== sessionIdentity(body))
                                 fail(409, "Session already exists with different creation parameters");
+                            prior.vaultIds = vaultIds;
+                            prior.credentialSelections = credentialSelections;
+                            prior.creation = body;
+                            this.store.put("sessions", id, prior);
+                            this.vault.recordAttachment(id, vaultIds);
                             return prior;
                         }
                         const definition = this.store.get("definitions", body.agentId) ??
@@ -743,8 +1109,12 @@ export class CoreRuntime {
                             status: "idle",
                             activeTurnId: null,
                             creation: body,
+                            vaultIds,
+                            credentialSelections,
+                            pluginRoots: definition.pluginRoots ?? {},
                         };
                         this.store.put("sessions", id, s);
+                        this.vault.recordAttachment(id, vaultIds);
                         return s;
                     });
                     return json(this.view(result));
@@ -775,7 +1145,7 @@ export class CoreRuntime {
                 response.end();
                 return;
             }
-            const status = error instanceof HttpError
+            const status = error instanceof HttpError || error instanceof VaultError
                 ? error.status
                 : error?.name === "ZodError" ||
                     error?.message === "Invalid cursor"
@@ -799,6 +1169,10 @@ export class CoreRuntime {
             implementationVersion: s.implementationVersion,
             status: s.status,
             activeTurnId: s.activeTurnId,
+            vaultIds: s.vaultIds ?? [],
+            credentialSelections: s.credentialSelections ?? [],
+            mcpSnapshot: s.mcpSnapshot ?? null,
+            mcpDiagnostics: s.mcpDiagnostics ?? [],
             waits: Array.isArray(s.waits)
                 ? s.waits.map((call) => ({
                     invocationId: call.invocationId,
@@ -823,6 +1197,165 @@ export class CoreRuntime {
             })),
         };
     }
+    async prepareMcp(id, signal) {
+        const s = this.session(id);
+        const declared = s.manifest.capabilities.some((capability) => capability.mcpServers !== undefined &&
+            Object.keys(capability.mcpServers).length > 0);
+        if (!declared)
+            return;
+        if (!s.mcpSnapshot) {
+            const found = await this.mcp.discover({
+                sessionId: id,
+                manifest: s.manifest,
+                manifestHash: s.manifestHash,
+                pluginRoots: s.pluginRoots ?? {},
+                signal,
+            });
+            this.store.tx(() => {
+                const current = this.session(id);
+                if (current.mcpSnapshot)
+                    return;
+                current.mcpSnapshot = found.snapshot;
+                current.mcpDiagnostics = found.diagnostics;
+                this.store.put("sessions", id, current);
+            });
+            return;
+        }
+        const diagnostics = await this.mcp.reconnect({
+            sessionId: id,
+            manifest: s.manifest,
+            pluginRoots: s.pluginRoots ?? {},
+            tools: s.mcpSnapshot.mcpTools,
+            signal,
+        });
+        if (diagnostics.length === 0)
+            return;
+        this.store.tx(() => {
+            const current = this.session(id);
+            const prior = [...(current.mcpDiagnostics ?? [])];
+            for (const item of diagnostics) {
+                const index = prior.findIndex((existing) => existing.capabilityId === item.capabilityId &&
+                    existing.serverName === item.serverName);
+                if (index >= 0)
+                    prior[index] = item;
+                else
+                    prior.push(item);
+            }
+            current.mcpDiagnostics = prior;
+            this.store.put("sessions", id, current);
+        });
+    }
+    async callMcpTool(request) {
+        const s = this.session(request.sessionId);
+        const tool = mcpToolOf(s, request.capabilityId, request.toolName);
+        if (!tool)
+            throw new Error(`MCP tool '${request.toolName ?? ""}' is not in the session snapshot`);
+        return this.mcp.call({
+            sessionId: s.id,
+            capabilityId: tool.capabilityId,
+            serverName: tool.serverName,
+            serverToolName: tool.serverToolName,
+            args: request.input,
+            manifest: s.manifest,
+            pluginRoots: s.pluginRoots ?? {},
+        });
+    }
+    async callSandboxTool(request, signal) {
+        const s = this.session(request.sessionId);
+        const capability = sandboxCapabilityOf(s.manifest, request.capabilityId, request.toolName);
+        if (!capability)
+            throw new Error(`'${request.toolName ?? ""}' is not a sandbox tool`);
+        return this.sandbox.run({ id: s.id, activeTurnId: s.activeTurnId, manifest: s.manifest }, capability, request.toolName, request.input, signal);
+    }
+    async authorize(sessionId, request) {
+        const s = this.session(sessionId);
+        const result = await this.vault.authorize({
+            sessionId,
+            vaultIds: s.vaultIds ?? [],
+            credentialSelections: s.credentialSelections ?? [],
+            url: request.url,
+            serverName: request.serverName,
+        });
+        if (result.status === "authorized") {
+            const token = result.headers.authorization.slice("Bearer ".length);
+            scrub({ authorization: result.headers.authorization, url: result.url }, [
+                token,
+            ]);
+        }
+        return result;
+    }
+    ensureKek() {
+        if (this.kek)
+            return this.kek;
+        if (this.options.vaultKek === null)
+            throw new Error("Vault key-encryption key is required");
+        this.kek = createKekFile(this.kekPath);
+        return this.kek;
+    }
+    async dispatchHost(scope, method, path, request) {
+        if (scope !== "server") {
+            this.vault.reject(path.join("/"));
+            fail(403, "Application credential required");
+        }
+        if (path[2] === "models" && path.length === 3 && method === "GET")
+            return hostModelCatalog();
+        if (path[2] === "sandbox" && path.length === 3 && method === "GET")
+            return this.sandbox.report();
+        if (path[2] === "providers" && path.length === 3 && method === "GET")
+            return this.vault.listHostProviders();
+        if (path[2] === "model" && path.length === 3 && method === "GET")
+            return this.vault.getHostModel();
+        if (path[2] === "model" && path.length === 3 && method === "PUT")
+            return this.vault.putHostModel(PutHostModelRequestSchema.parse(await this.body(request)));
+        if (path[2] === "model" &&
+            path[3] === "selection" &&
+            path.length === 4 &&
+            method === "PUT")
+            return this.vault.selectHostModel(SelectHostModelRequestSchema.parse(await this.body(request)));
+        fail(404, "Route not found");
+    }
+    async dispatchVault(scope, method, path, url, request) {
+        if (scope !== "server") {
+            this.vault.reject(path.join("/"));
+            fail(403, "Application credential required");
+        }
+        if (path.length === 2 && method === "POST") {
+            const body = CreateVaultRequestSchema.parse(await this.body(request));
+            return this.vault.createVault(body);
+        }
+        if (path.length === 2 && method === "GET") {
+            const ownerUserId = url.searchParams.get("ownerUserId") ??
+                fail(400, "ownerUserId is required");
+            return { vaults: this.vault.listVaults(ownerUserId) };
+        }
+        const vaultId = path[2];
+        if (!vaultId)
+            fail(404, "Vault not found");
+        if (path.length === 3 && method === "GET")
+            return this.vault.getVault(vaultId);
+        if (path.length === 3 && method === "DELETE")
+            return this.vault.deleteVault(vaultId);
+        if (path[3] !== "credentials")
+            fail(404, "Route not found");
+        if (path.length === 4 && method === "POST") {
+            const body = CreateCredentialRequestSchema.parse(await this.body(request));
+            return this.vault.createCredential(vaultId, body);
+        }
+        if (path.length === 4 && method === "GET")
+            return { credentials: this.vault.listCredentials(vaultId) };
+        const credentialId = path[4];
+        if (!credentialId)
+            fail(404, "Credential not found");
+        if (path.length === 5 && method === "GET")
+            return this.vault.getCredential(vaultId, credentialId);
+        if (path.length === 5 && method === "POST") {
+            const body = RotateCredentialRequestSchema.parse(await this.body(request));
+            return this.vault.rotateCredential(vaultId, credentialId, body);
+        }
+        if (path.length === 5 && method === "DELETE")
+            return this.vault.deleteCredential(vaultId, credentialId);
+        fail(404, "Route not found");
+    }
     async listen(port = 8787, hostname = "127.0.0.1") {
         if (this.server)
             throw new Error("Already listening");
@@ -843,8 +1376,10 @@ export class CoreRuntime {
         clearInterval(this.timer);
         for (const c of this.running.values())
             c.abort();
-        for (const r of this.executors)
-            r.end();
+        await this.mcp.close();
+        for (const streams of this.executorStreams.values())
+            for (const r of streams)
+                r.end();
         for (const set of this.observers.values())
             for (const r of set)
                 r.end();
@@ -856,6 +1391,8 @@ export class CoreRuntime {
         // Providers must honor AbortSignal. Keep storage open until any in-flight journal writes have drained.
         while (this.running.size)
             await new Promise((resolve) => setTimeout(resolve, 10));
+        await this.sandbox.close();
+        this.closed = true;
         this.store.db.close();
         if (this.lockPath)
             unlinkSync(this.lockPath);
@@ -875,3 +1412,7 @@ export async function startRuntime(options) {
         throw error;
     }
 }
+/** What an action runs, for events: a tool name, or a hook point and its capabilities. */
+function actionTarget(action) {
+    return action.kind === "hook" ? { hook: action.hook } : { toolName: action.toolName };
+}