@anchrd/intel-api 0.7.0 → 0.9.0

package/dist/http/http.js

@@ -1,4 +1,4 @@
-import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListNodesInput, NodeGraphInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
+import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListNodesInput, NodeGraphInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
@@ -231,19 +231,34 @@ export function createHttp(deps) {
         return context.json(await deps.nodes.listAgents(asActor(auth), input));
     });
     /**
-     * ⚠️ The one response in Intel's HTTP surface that carries a credential (#182, D27).
+     * ⚠️ NO response in Intel's HTTP surface carries a credential any more (D29, #207).
      *
-     * `applicationKey` is the Gate Application key of the new agent, in plain text, exactly once —
-     * Gate issues it once and keeps only a hash, and Intel writes it nowhere. It belongs in the agent
-     * runtime's `AGENT_APPLICATION_KEYS` secret; the answer says so rather than assuming the caller
-     * knows. The caller's own bearer is what creates the principal, so this needs `applications:write`
-     * in Gate on top of `knowledge:create` in Intel.
+     * Creating an agent still mints its Gate Application with the caller's own bearer — so this needs
+     * `applications:write` in Gate on top of `knowledge:create` in Intel — but the key Gate issues
+     * once goes straight into the agent runtime over the service binding, inside this request. The
+     * answer is the same shape every agent read has. Until #207 it carried the key in plain text and
+     * a person had to put it into a Worker secret by hand, which is why an agent created here could
+     * never run (#200).
      */
     app.post("/nodes/agents", async (context) => {
         const auth = requireCapability(context, "knowledge", "create");
         const input = CreateAgentInput.parse(await context.req.json().catch(() => null));
         return context.json(await deps.nodes.createAgent(asActor(auth), input, { token: context.get("token") }), 201);
     });
+    /**
+     * The repair path, and the only one an agent that lost its key has (D29, #207).
+     *
+     * ⚠️ `knowledge/write`, not `agents/run`. Which principal an agent acts as is a property of the
+     * agent, changed by whoever may change the agent; being allowed to press "Run now" is a different
+     * question and answers a different one. The resource ACL on the node is checked by the service.
+     *
+     * ⚠️ Before `/nodes/:nodeId`, like every other literal segment under `/nodes`.
+     */
+    app.post("/nodes/agents/:nodeId/rotate-key", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = RotateAgentKeyInput.parse({ nodeId: context.req.param("nodeId") });
+        return context.json(await deps.nodes.rotateAgentKey(asActor(auth), input, { token: context.get("token") }));
+    });
     // ⚠️ Before `/nodes/:nodeId`, or the router would read "export" as a node ID. The root has no
     // node to address, so the whole installation — as this caller may read it — exports here (#136).
     app.get("/nodes/export", async (context) => {
@@ -295,7 +310,9 @@ export function createHttp(deps) {
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.nodes.saveAgentDefinition(asActor(auth), input), 201);
+        // ⚠️ The caller's own bearer travels on, like it does when an agent is created: writing a
+        // definition also arms what it schedules, and that call is made as the person saving (#214).
+        return context.json(await deps.nodes.saveAgentDefinition(asActor(auth), input, { token: context.get("token") }), 201);
     });
     app.get("/nodes/:nodeId/versions", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
@@ -673,6 +690,13 @@ export function createHttp(deps) {
         const auth = requireCapability(context, "tools", "read");
         return context.json(await deps.tools.catalog(asToolActor(auth)));
     });
+    // ⚠️ Registered before `/tools/test` and `/tools/execute` and behind `tools/read`, not a new
+    // capability: it answers strictly less than `/tools` does — the servers behind the same live
+    // list, with no schemas (D30).
+    app.get("/tools/servers", async (context) => {
+        const auth = requireCapability(context, "tools", "read");
+        return context.json(await deps.tools.servers(asToolActor(auth)));
+    });
     app.post("/tools/test", async (context) => {
         const auth = requireCapability(context, "tools", "test");
         const input = TestToolInput.parse(await context.req.json().catch(() => null));

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
+import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
@@ -342,19 +342,18 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.nodes.create(actor, input)));
         /**
-         * ⚠️ The ONE tool result in Intel that contains a secret, and it is a decision rather than an
-         * oversight (#182, D27). Everywhere else in this file a credential in a result would be a leak
-         * into model context; here the result IS the credential — Gate issues an Application key once
-         * and keeps only its hash, so a redacted answer would mean "an agent you can create but never
-         * run", and the same administrator would get less through MCP than through the browser. Gate
-         * made the identical exception for `application_create` (`anchrd/gate` GATE-75).
-         *
-         * The exception is this tool and nothing beside it: `agent_get`, `agent_list` and every node
-         * read answer with `applicationId` alone, which names the principal without authenticating it.
+         * ⚠️ There is no longer ANY tool result in Intel that contains a secret, and that is the whole
+         * of D29 seen from here. Until #207 this one tool answered with the Application key in plain
+         * text — a deliberate exception, because the result WAS the credential and a redacted answer
+         * would have meant "an agent you can create but never run". The exception is gone rather than
+         * weakened: the key now travels from Gate into the agent runtime over Intel's service binding
+         * inside this call, so there is nothing left to hand to a model. `agent_create`, `agent_get`,
+         * `agent_list` and every node read answer with `applicationId` alone, which names the principal
+         * without authenticating it.
          */
         server.registerTool("agent_create", {
             title: "Create agent",
-            description: "Create an agent node with its first definition, and the Gate application it runs as. The definition names nodes and their role, schedules and a model — never accounts, secrets or channels. The response carries the application key ONCE, in plain text: put it into the agent runtime's AGENT_APPLICATION_KEYS secret and store it nowhere else. A repeated idempotency key returns the existing agent with no key.",
+            description: "Create an agent node with its first definition, and the Gate application it runs as. The definition names nodes and their role, schedules and a model — never accounts, secrets or channels. The agent's application key is handed to the agent runtime internally and never appears in this result; the agent can run straight away. A repeated idempotency key returns the existing agent and mints nothing.",
             inputSchema: CreateAgentInput,
             annotations: {
                 title: "Create agent",
@@ -378,7 +377,29 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.nodes.saveAgentDefinition(actor, input)));
+        }, async (input) => text(await deps.nodes.saveAgentDefinition(actor, input, { token: deps.bearer })));
+        /**
+         * The MCP half of the "Replace key" action in the agent profile (D29, #207).
+         *
+         * ⚠️ `knowledge/write` like `agent_update`, not `agents/run`: which principal an agent acts as
+         * is a property of the agent, changed by whoever may change the agent. And the result names the
+         * principal and the moment — never the key, which went to the runtime and nowhere else.
+         */
+        server.registerTool("agent_rotate_key", {
+            title: "Replace an agent's application key",
+            description: "Issue a new Gate application key for an agent and give it to the agent runtime. The previous key stops working immediately. Use it when a run fails with agent_key_missing, or when a key may have been exposed. The key itself is never returned.",
+            inputSchema: RotateAgentKeyInput,
+            annotations: {
+                title: "Replace an agent's application key",
+                readOnlyHint: false,
+                // The old key stops working the moment this runs, and anything still using it breaks.
+                destructiveHint: true,
+                // Asking twice issues twice, and the second answer invalidates the first key.
+                idempotentHint: false,
+                // The principal lives in Gate, which is a system outside Intel.
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.nodes.rotateAgentKey(actor, input, { token: deps.bearer })));
         registerWithAlias(server, { name: "node_save", deprecated: "knowledge_save" }, {
             title: "Save node version",
             description: "Append an immutable content version using an optimistic base version.",
@@ -927,6 +948,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async () => text(await deps.tools.catalog(toolActor)));
+        // The MCP twin of the picker in the agent profile (D30): whole servers, so an agent can be
+        // given tools from a client instead of from the screen. Assigning and removing is
+        // `agent_update` — a delegation is a field of the definition, not a surface of its own.
+        server.registerTool("tools_servers_list", {
+            title: "List tool servers",
+            description: "List the MCP servers the calling user reaches through the portal, as the portal itself names them. These are the handles an agent definition may delegate.",
+            inputSchema: EmptyInput,
+            annotations: {
+                title: "List tool servers",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async () => text(await deps.tools.servers(toolActor)));
     }
     if (permits(deps.authorization, "tools", "test")) {
         server.registerTool("tools_test", {

package/dist/nodes/nodes.js

@@ -327,6 +327,34 @@ export function createNodes(deps) {
             throw new IntelError(500, "content_missing", "Version content is missing");
         return { node, version, definition: parseStoredDefinition(body), applicationId };
     }
+    /**
+     * The one place a caller's asked-for definition becomes the definition Intel stores (D30).
+     *
+     * ⚠️ `delegatedBy` is ADDED here, from the session, and could not have arrived any other way:
+     * `AgentDefinitionInput` has no field for it, so a body naming somebody else is a parse error at
+     * the boundary rather than a value this function has to remember to ignore. Adding it here is
+     * safe in exactly one direction — the writer must prove below that they reach every named server
+     * themselves, so the delegation can only ever move to somebody who already had it.
+     *
+     * ⚠️ The check is a live `tools/list` through the portal, before anything is written. A server the
+     * saver cannot reach is refused BY NAME — a silent drop would leave a person looking at a saved
+     * agent that quietly has one tool fewer than they picked.
+     */
+    async function delegationOf(actor, definition) {
+        const tools = definition.tools;
+        if (!tools)
+            return { ...definition, tools: null };
+        const servers = [...new Set(tools.servers)];
+        if (servers.length === 0) {
+            return { ...definition, tools: { delegatedBy: actor.id, servers: [] } };
+        }
+        const reachable = new Set(await deps.toolServers(actor));
+        const missing = servers.filter((server) => !reachable.has(server));
+        if (missing.length > 0) {
+            throw new IntelError(403, "tool_server_not_delegatable", `You do not reach these MCP servers, so you cannot delegate them: ${missing.join(", ")}`);
+        }
+        return { ...definition, tools: { delegatedBy: actor.id, servers } };
+    }
     /**
      * One immutable definition version, written exactly the way a document's content is (ADR-0005 §1).
      *
@@ -694,10 +722,12 @@ export function createNodes(deps) {
          * would make the second write look like a replay of the first. A caller who repeats the
          * request gets the agent that already exists rather than a second one beside it.
          *
-         * ⚠️ A REPLAY MAKES NO SECOND APPLICATION and answers `applicationKey: null`. It still returns
-         * the agent that exists — that promise is not weakened — but a repeat that minted a fresh
-         * principal to fill the field would leave the installation with two machine accounts for one
-         * agent, one of which nobody would ever switch off. Gate is not asked at all on that path.
+         * ⚠️ A REPLAY MAKES NO SECOND APPLICATION. It still returns the agent that exists — that promise
+         * is not weakened — but a repeat that minted a fresh principal would leave the installation with
+         * two machine accounts for one agent, one of which nobody would ever switch off, and would
+         * replace a working agent's key with one it never asked for. Gate is not asked at all on that
+         * path, and no key travels either. What a replay DOES do is arm the agent's schedules again
+         * (#214) — that is idempotent, and it is the repair for a create whose arming failed.
          *
          * ⚠️ Gate is asked BEFORE anything is written, and that ordering IS the answer to "what if Gate
          * is down". Nothing exists yet at that moment, so a Gate that does not answer leaves no node, no
@@ -722,14 +752,21 @@ export function createNodes(deps) {
             const definitionKey = `${input.idempotencyKey}:definition`;
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
             if (existingId) {
-                return {
-                    ...(await agentOf(await requireVisible(actor, existingId))),
-                    applicationKey: null,
-                };
+                const existing = await agentOf(await requireVisible(actor, existingId));
+                // ⚠️ A replay arms as well, and that is what makes a create whose sync failed repairable
+                // (#214): repeating it with the same key mints nothing, returns this agent, and puts its
+                // alarm right. Without it the only repair left would be a fresh key — a second agent.
+                if ((existing.definition?.schedules.length ?? 0) > 0) {
+                    await deps.agentSchedules.sync({ token: caller.token, agentId: existing.node.id });
+                }
+                return existing;
             }
             if (input.parentId !== null && !(await deps.repository.can(actor, input.parentId, "write"))) {
                 throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
             }
+            // Before Gate, for the same reason the runtime check is before Gate: a delegation the saver
+            // cannot back must not leave a machine principal behind for an agent that was never created.
+            const definition = await delegationOf(actor, input.definition);
             const nodeId = deps.id();
             // The Application's name is what a person reads in Gate's list, so it has to be enough to
             // recognise the agent by. Title alone would leave two agents called "Research" indis-
@@ -738,6 +775,22 @@ export function createNodes(deps) {
                 token: caller.token,
                 name: `Intel agent ${input.title} (${nodeId})`,
             });
+            // ⚠️ The handover happens BEFORE the node is written, for the same reason Gate is asked before
+            // it: at this moment nothing exists on Intel's side, so a runtime that does not take the key
+            // leaves no node, no version, no R2 object and no audit event — the agent simply does not come
+            // into being and the caller repeats the request. The other order would produce exactly the
+            // agent #200 is about: a node that looks finished and dies at its first run. What it can leave
+            // behind is a Durable Object holding a key for a node id that will never exist, which is
+            // ciphertext nobody can address — ULIDs are not reused.
+            try {
+                await deps.agentKeys.store({ token: caller.token, agentId: nodeId, key: application.key });
+            }
+            catch (error) {
+                await deps.applications
+                    .setEnabled({ token: caller.token, applicationId: application.id, enabled: false })
+                    .catch(() => undefined);
+                throw error;
+            }
             const timestamp = deps.now().toISOString();
             let node;
             try {
@@ -766,21 +819,95 @@ export function createNodes(deps) {
                     .catch(() => undefined);
                 throw error;
             }
-            const agent = await writeAgentVersion(actor, node, input.definition, null, definitionKey);
-            return {
-                ...agent,
-                // ⚠️ The one place a credential is put into an answer, and it is assembled here rather than
-                // carried around: `application.key` has been in one local variable since Gate returned it
-                // and reaches no store, no audit row and no log on the way (D27).
-                applicationKey: {
-                    agentId: node.id,
-                    applicationId: application.id,
-                    key: application.key,
-                    notice: "This key is shown once. Add it to the agent runtime's AGENT_APPLICATION_KEYS secret as { agentId, key } — the whole list, not just this entry — and store it nowhere else. Intel keeps only the application ID; Gate keeps only a hash.",
-                },
-            };
+            // ⚠️ No key in the answer, and no field one could travel in (D29). `application.key` has been
+            // in one local variable since Gate returned it, went into the runtime, and is out of reach of
+            // every surface above this line.
+            const created = (await writeAgentVersion(actor, node, definition, null, definitionKey));
+            /**
+             * ⚠️ Only when this definition actually schedules something — unlike the save below, which
+             * arms unconditionally. A brand-new agent has no earlier definition, so there is no alarm that
+             * could be left standing: no schedules means there is nothing to arm and nothing to clear, and
+             * the screen creates every agent that way (the profile is where schedules are added).
+             *
+             * ⚠️ It fails loudly, and the agent stays. Everything is written by now and nothing here can
+             * roll an agent back, so the caller is told the one thing they can act on: the schedules are
+             * not armed. The repair is repeating the create with the SAME idempotency key — which returns
+             * this agent, mints no second Application, and arms it. A fresh key would create a second
+             * agent beside this one, which is why the message says "again" and not "retry".
+             */
+            if (definition.schedules.length > 0) {
+                await deps.agentSchedules.sync({ token: caller.token, agentId: node.id });
+            }
+            return created;
         },
-        async saveAgentDefinition(actor, input) {
+        /**
+         * A new key for the Application this agent runs as, handed straight to the runtime (D29, #207).
+         *
+         * ⚠️ A write on the agent node, not a run: `knowledge/write` at the door and the resource ACL
+         * here. Whoever may change what an agent does may change which key it does it with; being
+         * allowed to press "Run now" says nothing about being allowed to decide its principal.
+         *
+         * ⚠️ Gate first, runtime second, and nothing in between. Gate issues the replacement before it
+         * revokes the old one, so a rotation that fails at Gate changes nothing at all; one that fails
+         * at the handover leaves the agent with a key it no longer has — named, repairable, and fixed by
+         * rotating again. The alternative order cannot exist: the runtime has nothing to store until
+         * Gate has answered.
+         *
+         * ⚠️ The key is in one local variable and in no answer. This is the operation that exists BECAUSE
+         * Gate hands a key out exactly once — reading one back is not something any repair can do.
+         */
+        async rotateAgentKey(actor, input, caller) {
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "agent") {
+                throw new IntelError(409, "not_an_agent", "Only agents have an application key");
+            }
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This agent cannot be edited");
+            }
+            if (!deps.agentRuntimeAvailable()) {
+                throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime, so there is nothing to give a key to");
+            }
+            const applicationId = await deps.repository.agentApplicationId(node.id);
+            if (applicationId === null) {
+                // An agent written before #182, restored from a bundle, or imported. Giving it a principal
+                // is an act in Gate, and inventing one here would make Intel the author of a machine
+                // account nobody asked for.
+                throw new IntelError(409, "agent_application_missing", "This agent has no Gate application, so there is no key to replace");
+            }
+            const rotated = await deps.applications.rotateKey({ token: caller.token, applicationId });
+            await deps.agentKeys.store({ token: caller.token, agentId: node.id, key: rotated.key });
+            const rotatedAt = deps.now().toISOString();
+            // ⚠️ Written LAST, and only once both sides took the change. An event ahead of the runtime
+            // would record a rotation that may not have arrived, and this row is the only trace the act
+            // leaves in Intel — nothing about the node itself changes, so a reader who diffed versions
+            // would see an agent that silently began acting with a different credential.
+            await deps.repository.recordAgentKeyRotation({
+                auditId: deps.id(),
+                actorId: actor.id,
+                nodeId: node.id,
+                applicationId,
+                occurredAt: rotatedAt,
+            });
+            return { nodeId: node.id, applicationId, rotatedAt };
+        },
+        /**
+         * A new definition version, and the alarm that has to match it (#214).
+         *
+         * ⚠️ The runtime is told to re-arm after EVERY definition write, not only after one that names a
+         * schedule. The alternative — comparing against the definition that was there before — needs the
+         * previous document read back out of R2, and it is wrong in exactly the direction that matters:
+         * a save that removes the LAST schedule has nothing to compare against in the new definition and
+         * is precisely the write that has to clear the alarm. One binding call per save buys the rule
+         * "what is written is what is armed" without a comparison anybody could get backwards.
+         *
+         * ⚠️ Written first, armed second, and the definition STAYS when the arming fails. It has to: the
+         * runtime reads the definition back out of Intel to arm it, so there is no order in which it
+         * could be armed before it exists. What the caller gets instead of silence is
+         * `agent_schedules_not_armed` — the version is in the history, the profile shows it, and saving
+         * again arms it. Rolling the version back would be worse than the unarmed alarm: it would throw
+         * away an edit somebody made because a Worker was briefly unreachable.
+         */
+        async saveAgentDefinition(actor, input, caller) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
             if (existingId)
                 return await agentOf(await requireVisible(actor, input.nodeId));
@@ -794,7 +921,9 @@ export function createNodes(deps) {
             if (node.currentVersionId !== input.baseVersionId) {
                 throw new IntelError(409, "version_conflict", "A newer version already exists");
             }
-            return await writeAgentVersion(actor, node, input.definition, input.baseVersionId, input.idempotencyKey);
+            const saved = await writeAgentVersion(actor, node, await delegationOf(actor, input.definition), input.baseVersionId, input.idempotencyKey);
+            await deps.agentSchedules.sync({ token: caller.token, agentId: node.id });
+            return saved;
         },
         async saveAttachment(actor, input) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);

package/dist/nodes/nodes.types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, ListAgentsInput, ListNodesInput, Node, NodeAgent, NodeAttachment, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
+import type { AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, ListAgentsInput, ListNodesInput, Node, NodeAgent, NodeAttachment, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
 import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
 export interface Actor {
     id: string;
@@ -55,6 +55,26 @@ export interface NodeRepository {
     findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
     insertNode(input: NewNode): Promise<Node>;
     agentApplicationId(nodeId: string): Promise<string | null>;
+    /**
+     * The audit row for replacing the key of the Application an agent runs as (D29, #207).
+     *
+     * ⚠️ Its own write because it is the only mutation on an agent node that changes nothing IN the
+     * node — no version, no row, nothing a reader could diff afterwards. Swapping which credential an
+     * agent acts with is the most security-relevant thing anybody does to it, and without this it
+     * would be the one act on the tree that leaves no trace in Intel at all. Gate audits its side;
+     * Gate does not know which Intel node the principal belongs to.
+     *
+     * ⚠️ `applicationId` names the principal and is a name, not a credential. The key itself is not a
+     * parameter here and must never become one — audit is metadata, and this is exactly the row a
+     * "helpful" second field would leak it into.
+     */
+    recordAgentKeyRotation(input: {
+        auditId: string;
+        actorId: string;
+        nodeId: string;
+        applicationId: string;
+        occurredAt: string;
+    }): Promise<void>;
     getVersion(versionId: string): Promise<NodeVersion | null>;
     appendVersion(input: NewNodeVersion): Promise<"saved" | "conflict">;
     appendTableVersion(input: NewTableVersion): Promise<NodeVersion>;
@@ -184,6 +204,19 @@ export interface AgentApplications {
         id: string;
         key: string;
     }>;
+    /**
+     * A replacement key for an Application that already exists, invalidating every earlier one.
+     *
+     * ⚠️ Gate issues before it revokes, so a failed rotation leaves the old key working. That is what
+     * makes `rotate-key` a safe repair rather than a way to lock an agent out: the only state this
+     * can leave behind is "new key issued, runtime never got it", and rotating again fixes it.
+     */
+    rotateKey(input: {
+        token: string;
+        applicationId: string;
+    }): Promise<{
+        key: string;
+    }>;
     setEnabled(input: {
         token: string;
         applicationId: string;
@@ -198,6 +231,38 @@ export interface NodesDeps {
     content: ContentStore;
     applications: AgentApplications;
     agentRuntimeAvailable(): boolean;
+    /**
+     * The runtime's key store, as the tree needs it (D29, #207).
+     *
+     * ⚠️ This is where the Application key GOES, and it is the only place it goes. Gate hands it out
+     * once, this port carries it into the agent's Durable Object over the service binding, and the
+     * local variable that held it dies with the call. Nothing in this file writes it to D1, R2, an
+     * audit row, a log line or a response — the proof is the absence of the value in every argument
+     * every port was called with, not a redaction somebody could forget.
+     */
+    agentKeys: {
+        store(input: {
+            token: string;
+            agentId: string;
+            key: string;
+        }): Promise<void>;
+    };
+    /**
+     * The runtime's alarm, brought in line with the definition that was just written (#214).
+     *
+     * ⚠️ Required, not optional, and it carries no schedules. The runtime arms its alarm only when
+     * something tells it to look — a chat turn, a resume, a manual run, or this call — so a definition
+     * written without it leaves an agent whose schedules are visible in its profile and fire never.
+     * What travels is the agent's ID and the caller's bearer; the runtime re-reads the definition from
+     * Intel with the agent's own token, which is what keeps a schedule something that was written
+     * before it can be acted on.
+     */
+    agentSchedules: {
+        sync(input: {
+            token: string;
+            agentId: string;
+        }): Promise<void>;
+    };
     id(): string;
     now(): Date;
     externalFlowCallers(actor: Actor, folderId: string): Promise<{
@@ -205,6 +270,14 @@ export interface NodesDeps {
         hidden: number;
     }>;
     flowNodeReferences(actor: Actor, folderId: string): Promise<string[]>;
+    /**
+     * The handles of the MCP servers this actor reaches through the portal right now (D30).
+     *
+     * ⚠️ Injected as a live question, never as a stored list. Delegating a server is only allowed to
+     * somebody who has it themselves, and "has it" can only be answered by asking the portal at the
+     * moment of the save — a mirrored table here would be the permission mirror ADR-0003 removed.
+     */
+    toolServers(actor: Actor): Promise<string[]>;
     hash(content: string | Uint8Array): Promise<string>;
     indexing: {
         enqueue(versionId: string): Promise<void>;
@@ -254,14 +327,29 @@ export interface NodeService {
     redefineTable(actor: Actor, input: RedefineTableInput): Promise<NodeTable>;
     getAgent(actor: Actor, input: GetAgentInput): Promise<NodeAgent>;
     /**
-     * An agent node, its first definition, and the Gate Application it runs as (#182).
+     * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
      *
-     * ⚠️ The answer carries the Application key ONCE. It is the only value any Intel service returns
-     * that is a credential, it is never written down on the way out, and the caller who receives it
-     * is the only one who will ever see it.
+     * ⚠️ The answer carries NO key. The one Gate issues goes straight into the agent runtime over the
+     * service binding, inside this call, and the caller never sees it — which is what makes an agent
+     * created through the screen able to run without a terminal step (#200, #207).
      */
     createAgent(actor: Actor, input: CreateAgentInput, caller: GateCaller): Promise<CreatedAgent>;
-    saveAgentDefinition(actor: Actor, input: SaveAgentDefinitionInput): Promise<NodeAgent>;
+    /**
+     * Replace the key of the Application an agent runs as, and give the new one to the runtime.
+     *
+     * ⚠️ The repair path for an agent that answers `agent_key_missing`, and the only one: Gate keeps
+     * a key hashed, so an agent whose Durable Object lost its key cannot be handed the old one back.
+     * It is a write on the agent node — `knowledge/write` and the resource ACL — not a run.
+     */
+    rotateAgentKey(actor: Actor, input: RotateAgentKeyInput, caller: GateCaller): Promise<AgentKeyRotated>;
+    /**
+     * A new definition version for an agent, and the alarm that goes with it (#214).
+     *
+     * ⚠️ It takes the caller's bearer for the same reason `createAgent` does: the runtime is told to
+     * re-arm over the service binding, and what travels on that call is the person behind this request
+     * — never a service key (D19).
+     */
+    saveAgentDefinition(actor: Actor, input: SaveAgentDefinitionInput, caller: GateCaller): Promise<NodeAgent>;
     listAgents(actor: Actor, input: ListAgentsInput): Promise<AgentList>;
     getAttachment(actor: Actor, nodeId: string): Promise<NodeAttachment>;
     readAttachment(actor: Actor, nodeId: string): Promise<NodeAttachmentBody>;

package/dist/tools/tool-servers/tool-servers.d.ts

@@ -0,0 +1,46 @@
+import { type ToolServer } from "@anchrd/intel-contract";
+/**
+ * The portal's own directory tool. It is an ordinary entry in `tools/list`, so it is reached the
+ * same way every other tool is: `tools/call` with the asking user's portal token.
+ *
+ * ⚠️ Its presence in the live list is also the permission check. A deployment whose portal does not
+ * offer it, or a user whose Access policies hide it, gets no server list at all — and therefore
+ * cannot delegate anything. That is deliberate: the alternative would be inventing the server list
+ * out of tool names, which is exactly the guess this module exists to avoid.
+ */
+export declare const ServerDirectoryTool = "portal_list_servers";
+export interface ToolServerDirectoryAnswer {
+    isError: boolean;
+    content: unknown[];
+    structuredContent?: unknown;
+}
+/**
+ * The servers this user reaches: the portal's directory, confirmed against the portal's live tool
+ * list.
+ *
+ * Two sets come out of one answer, and keeping them apart is the whole of this function:
+ *
+ * - **`declared`** — every identifier the directory mentions at all, disabled rows included. It is
+ *   the universe `serverOf` attributes against, and it must be as WIDE as possible. ⚠️ Narrowing it
+ *   widens the delegation: drop `wiki_extra` because the portal marked it disabled, and the live
+ *   tool `wiki_extra__read` falls back onto `wiki` — a tool of a server nobody delegated, handed to
+ *   an agent that was given `wiki`. Filtering therefore happens after attribution, never before it.
+ * - **the returned list** — what may actually be delegated: enabled, and confirmed by at least one
+ *   live tool. Intel cannot prove that a directory identifier is the same string the namespace uses,
+ *   so it only ever offers handles it has just seen work.
+ *
+ * ⚠️ What remains outside Intel's reach: a directory that omits a server whose tools ARE in
+ * `tools/list`. Nothing in the answer distinguishes that from a tool of the enclosing namespace, and
+ * the portal is the authority on its own servers — so an incomplete directory widens by exactly one
+ * namespace level, and it is a portal defect rather than something this code can detect.
+ */
+export interface ToolServerDirectory {
+    /** Every identifier the directory mentioned. Attribute against this, never against `servers`. */
+    declared: string[];
+    /** What may be offered and delegated: enabled, and confirmed by a live tool. */
+    servers: ToolServer[];
+}
+export declare function toolServersFrom(input: {
+    directory: ToolServerDirectoryAnswer;
+    toolNames: string[];
+}): ToolServerDirectory | null;