@anchrd/intel-api 0.6.7 → 0.9.0

package/dist/mcp/mcp.js

@@ -1,5 +1,5 @@
-import { AppendKnowledgeTableRowsInput, ArchiveFlowInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+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";
 import { permits } from "../shared/gate-authorization/gate-authorization.js";
@@ -7,6 +7,19 @@ import { IntelError } from "../shared/intel-error/intel-error.js";
 function text(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
 }
+/**
+ * Registers one tool twice: under its name, and under the `knowledge_*` name it carried before #125.
+ *
+ * ⚠️ The alias is not politeness. A tool name lives in someone else's configuration — a Portal
+ * endpoint, an agent, a saved prompt — and renaming it here alone breaks them at the moment we
+ * deploy rather than at a moment they chose. Both entries share one handler and one schema, so
+ * there is no second behavior to keep in step; only the name and the first sentence of the
+ * description differ. The aliases are removed in anchrd/intel#149.
+ */
+function registerWithAlias(server, names, config, handler) {
+    server.registerTool(names.name, config, handler);
+    server.registerTool(names.deprecated, { ...config, description: `Deprecated: use ${names.name}. ${config.description}` }, handler);
+}
 // MCP returns resource payloads inline as base64, so an attachment cannot be streamed to the client
 // and must fit in Worker memory twice over. Refuse oversized attachments instead of losing the
 // isolate; HTTP still serves them as a stream.
@@ -41,59 +54,129 @@ export async function handleMcp(request, deps) {
         canRun: permits(deps.authorization, "flows", "run"),
         isAdmin: deps.authorization.can("intel", "admin"),
     };
+    const bundleActor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        isAdmin: deps.authorization.can("intel", "admin"),
+        canReadFlows: permits(deps.authorization, "flows", "read"),
+        canCreateFlows: permits(deps.authorization, "flows", "create"),
+    };
+    const agentActor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        isAdmin: deps.authorization.can("intel", "admin"),
+        canRun: permits(deps.authorization, "agents", "run"),
+    };
     const server = new McpServer({ name: "intel", version: "0.1.0" });
     const EmptyInput = z.strictObject({});
+    // `null` is the root: the whole tree as this caller may read it. The field is required rather
+    // than defaulted so "everything" is always said, never fallen into.
+    const ExportManifestInput = z.strictObject({ nodeId: IntelId.nullable() });
+    // The zip travels inline as base64, which is MCP's one way of carrying bytes. ~14M characters is
+    // ~10 MB of zip — the same order as the attachment inline limit, and for the same isolate-memory
+    // reason. Bigger bundles take the HTTP door, which streams.
+    const ImportBundleInput = z.strictObject({
+        nodeId: IntelId.nullable(),
+        zipBase64: z.string().min(1).max(14_000_000),
+        idempotencyKey: z.string().min(8).max(200),
+    });
+    function decodeZipBase64(value) {
+        if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+            throw new IntelError(400, "import_invalid_bundle", "zipBase64 is not valid base64");
+        }
+        try {
+            return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+        }
+        catch {
+            throw new IntelError(400, "import_invalid_bundle", "zipBase64 is not valid base64");
+        }
+    }
+    // The caller's own identity (#148): the MCP twin of `GET /session`, and like it behind no
+    // capability at all — the answer is the token's own subject, and an agent that may connect may
+    // ask who it is connected as. Deliberately id, email, and name and nothing else: no
+    // capabilities, no token, nothing a caller could mistake for a permission.
+    server.registerTool("session_get", {
+        title: "Get session identity",
+        description: "Get the identity this connection acts as: user id, email, and display name. The MCP counterpart of GET /session; it answers from the token's own subject and never lists permissions.",
+        inputSchema: EmptyInput,
+        annotations: {
+            title: "Get session identity",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => text({
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        name: deps.authorization.identity.name ?? null,
+    }));
     if (permits(deps.authorization, "knowledge", "read")) {
-        server.registerTool("knowledge_list", {
-            title: "List knowledge",
+        registerWithAlias(server, { name: "node_list", deprecated: "knowledge_list" }, {
+            title: "List nodes",
             description: "List authorized folders, documents, attachments, and tables under one parent.",
-            inputSchema: ListKnowledgeNodesInput,
+            inputSchema: ListNodesInput,
             annotations: {
-                title: "List knowledge",
+                title: "List nodes",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.list(actor, input)));
-        server.registerTool("knowledge_get", {
-            title: "Get knowledge",
-            description: "Get one authorized Knowledge node and its current immutable content version.",
-            inputSchema: GetKnowledgeNodeInput,
+        }, async (input) => text(await deps.nodes.list(actor, input)));
+        registerWithAlias(server, { name: "node_get", deprecated: "knowledge_get" }, {
+            title: "Get node",
+            description: "Get one authorized node and its current immutable content version.",
+            inputSchema: GetNodeInput,
             annotations: {
-                title: "Get knowledge",
+                title: "Get node",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.get(actor, input.nodeId)));
-        server.registerTool("knowledge_versions_list", {
-            title: "List knowledge versions",
-            description: "List immutable versions of one authorized Knowledge node.",
-            inputSchema: GetKnowledgeNodeInput,
+        }, async (input) => text(await deps.nodes.get(actor, input.nodeId)));
+        registerWithAlias(server, { name: "node_versions_list", deprecated: "knowledge_versions_list" }, {
+            title: "List node versions",
+            description: "List immutable versions of one authorized node.",
+            inputSchema: GetNodeInput,
             annotations: {
-                title: "List knowledge versions",
+                title: "List node versions",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.listVersions(actor, input.nodeId)));
-        server.registerTool("knowledge_attachment_get", {
-            title: "Get knowledge attachment",
+        }, async (input) => text(await deps.nodes.listVersions(actor, input.nodeId)));
+        // The content behind one row of the version list (#147): what a version-pinned search citation
+        // points at. No `knowledge_*` alias — the tool is new under the post-#125 naming and never
+        // carried the old prefix.
+        server.registerTool("node_version_get", {
+            title: "Get node version content",
+            description: "Read one pinned immutable version of an authorized node, content included — the version a search citation names, whether or not it is current. For an attachment the answer is its metadata without the bytes. A version that does not belong to the node is not found.",
+            inputSchema: GetNodeVersionInput,
+            annotations: {
+                title: "Get node version content",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.getVersion(actor, input.nodeId, input.versionId)));
+        registerWithAlias(server, { name: "node_attachment_get", deprecated: "knowledge_attachment_get" }, {
+            title: "Get node attachment",
             description: "Get authorized immutable attachment metadata and its explicit MCP resource URI.",
-            inputSchema: GetKnowledgeNodeInput,
+            inputSchema: GetNodeInput,
             annotations: {
-                title: "Get knowledge attachment",
+                title: "Get node attachment",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.getAttachment(actor, input.nodeId)));
-        server.registerResource("knowledge-attachment", new ResourceTemplate("intel://knowledge/{nodeId}/attachment", { list: undefined }), { title: "Intel knowledge attachment" }, async (uri, variables) => {
-            const { attachment, body } = await deps.knowledge.readAttachment(actor, String(variables.nodeId));
+        }, async (input) => text(await deps.nodes.getAttachment(actor, input.nodeId)));
+        server.registerResource("node-attachment", new ResourceTemplate("intel://nodes/{nodeId}/attachment", { list: undefined }), { title: "Intel node attachment" }, async (uri, variables) => {
+            const { attachment, body } = await deps.nodes.readAttachment(actor, String(variables.nodeId));
             if (attachment.version.size > AttachmentInlineLimit) {
                 await body.cancel();
                 throw new IntelError(413, "attachment_too_large", "Attachment is too large to inline; read it over HTTP instead");
@@ -108,155 +191,279 @@ export async function handleMcp(request, deps) {
                 ],
             };
         });
-        server.registerResource("knowledge-document", new ResourceTemplate("intel://knowledge/{nodeId}", { list: undefined }), { title: "Intel knowledge document", mimeType: "application/json" }, async (uri, variables) => {
-            const document = await deps.knowledge.get(actor, String(variables.nodeId));
+        server.registerResource("node-document", new ResourceTemplate("intel://nodes/{nodeId}", { list: undefined }), { title: "Intel node document", mimeType: "application/json" }, async (uri, variables) => {
+            const document = await deps.nodes.get(actor, String(variables.nodeId));
             return {
                 contents: [
                     { uri: uri.href, mimeType: "application/json", text: JSON.stringify(document) },
                 ],
             };
         });
-        server.registerTool("knowledge_search", {
-            title: "Search knowledge",
-            description: "Search only authorized indexed Knowledge and return version-pinned citations.",
-            inputSchema: SearchKnowledgeInput,
+        registerWithAlias(server, { name: "search", deprecated: "knowledge_search" }, {
+            title: "Search nodes",
+            description: "Search only authorized indexed nodes and return version-pinned citations. Pass scopeId " +
+                "with a folder node id to search that folder and everything beneath it instead of " +
+                "everything readable.",
+            inputSchema: SearchInput,
+            annotations: {
+                title: "Search nodes",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.search(actor, input)));
+        // ⚠️ Plain `registerTool` and no alias: these tools are new with #139 and never had a
+        // `knowledge_` name, so inventing one would create a deprecated name that was never used —
+        // and #149, which removes the aliases, would then have one more thing to remove.
+        server.registerTool("agent_list", {
+            title: "List agents",
+            description: "List the authorized agents, over the whole tree or under one folder. Omit parentId for every agent, pass null for the root level.",
+            inputSchema: ListAgentsInput,
+            annotations: {
+                title: "List agents",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listAgents(actor, input)));
+        server.registerTool("agent_get", {
+            title: "Get agent",
+            description: "Read one authorized agent with its current definition: the nodes it references and their role, its schedules, and its model.",
+            inputSchema: GetAgentInput,
             annotations: {
-                title: "Search knowledge",
+                title: "Get agent",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.search(actor, input)));
-        server.registerTool("knowledge_table_get", {
-            title: "Get knowledge table",
+        }, async (input) => text(await deps.nodes.getAgent(actor, input)));
+        registerWithAlias(server, { name: "node_table_get", deprecated: "knowledge_table_get" }, {
+            title: "Get node table",
             description: "Read one authorized table as column names and rows.",
-            inputSchema: GetKnowledgeTableInput,
+            inputSchema: GetTableInput,
             annotations: {
-                title: "Get knowledge table",
+                title: "Get node table",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.getTable(actor, input.nodeId)));
-        server.registerTool("knowledge_links_list", {
-            title: "List knowledge links",
-            description: "List authorized outgoing links and backlinks for one Knowledge node.",
-            inputSchema: GetKnowledgeNodeInput,
+        }, async (input) => text(await deps.nodes.getTable(actor, input.nodeId)));
+        registerWithAlias(server, { name: "node_links_list", deprecated: "knowledge_links_list" }, {
+            title: "List node links",
+            description: "List authorized outgoing links and backlinks for one node.",
+            inputSchema: GetNodeInput,
             annotations: {
-                title: "List knowledge links",
+                title: "List node links",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.listLinks(actor, input.nodeId)));
+        }, async (input) => text(await deps.nodes.listLinks(actor, input.nodeId)));
         // The reader's half of a document link (#41): the titles of the linked documents this caller
         // may see. There is no tool to create or delete a link — a relationship is written in the text
-        // and `knowledge_save` is what records it, so there is only one way to make one.
+        // and `node_save` is what records it, so there is only one way to make one.
         //
         // ⚠️ A target this caller may not reach, or one that is gone, is simply absent from the answer.
         // The two are indistinguishable on purpose: telling them apart would confirm that a document
         // exists somewhere they cannot look.
-        server.registerTool("knowledge_links_resolve", {
-            title: "Resolve knowledge links",
+        registerWithAlias(server, { name: "node_links_resolve", deprecated: "knowledge_links_resolve" }, {
+            title: "Resolve node links",
             description: "Resolve document link targets to the titles this caller is authorized to see. Targets that are unreachable or deleted are absent from the result.",
-            inputSchema: ResolveKnowledgeLinksInput,
+            inputSchema: ResolveNodeLinksInput,
+            annotations: {
+                title: "Resolve node links",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.resolveLinks(actor, input)));
+        registerWithAlias(server, { name: "node_graph", deprecated: "knowledge_graph" }, {
+            title: "Get node graph",
+            description: "Get the authorized nodes and explicit relationships for discovery.",
+            inputSchema: NodeGraphInput,
             annotations: {
-                title: "Resolve knowledge links",
+                title: "Get node graph",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.resolveLinks(actor, input)));
-        server.registerTool("knowledge_graph", {
-            title: "Get knowledge graph",
-            description: "Get the authorized Knowledge nodes and explicit relationships for discovery.",
-            inputSchema: KnowledgeGraphInput,
+        }, async (input) => text(await deps.nodes.graph(actor, input)));
+        // The export as MCP offers it (#136): the manifest — every readable entry with its bundle path
+        // and media type. The contents behind the paths are read one by one through `node_get`,
+        // `node_table_get`, and `node_attachment_get`. ⚠️ Deliberately no binary zip over MCP: a
+        // resource payload travels inline as base64 and would have to fit in Worker memory twice, the
+        // same limit that caps `node_attachment_get` at 10 MB — a whole subtree is the case that limit
+        // exists for. HTTP `GET /nodes/:nodeId/export` streams the real archive.
+        server.registerTool("node_export_manifest", {
+            title: "Get export manifest",
+            description: "Plan a bundle export: the manifest of one authorized subtree (or the whole tree when nodeId is null) with each entry's bundle path, kind, and media type. Content bytes are fetched per node; the binary zip is served over HTTP.",
+            inputSchema: ExportManifestInput,
             annotations: {
-                title: "Get knowledge graph",
+                title: "Get export manifest",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.graph(actor, input)));
+        }, async (input) => text(await deps.bundle.manifest(bundleActor, input.nodeId)));
     }
     if (deps.authorization.can("intel", "admin")) {
-        server.registerTool("knowledge_reindex", {
-            title: "Reindex knowledge",
-            description: "Queue every current canonical Knowledge version for derived index rebuild.",
+        registerWithAlias(server, { name: "node_reindex", deprecated: "knowledge_reindex" }, {
+            title: "Reindex nodes",
+            description: "Queue every current canonical node version for derived index rebuild.",
             inputSchema: EmptyInput,
             annotations: {
-                title: "Reindex knowledge",
+                title: "Reindex nodes",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async () => text(await deps.knowledge.reindex(actor)));
+        }, async () => text(await deps.nodes.reindex(actor)));
     }
     if (permits(deps.authorization, "knowledge", "create")) {
-        server.registerTool("knowledge_create", {
-            title: "Create knowledge",
+        registerWithAlias(server, { name: "node_create", deprecated: "knowledge_create" }, {
+            title: "Create node",
             description: "Create a governed folder, document, attachment, or table node.",
-            inputSchema: CreateKnowledgeNodeInput,
+            inputSchema: CreateNodeInput,
             annotations: {
-                title: "Create knowledge",
+                title: "Create node",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.create(actor, input)));
+        }, async (input) => text(await deps.nodes.create(actor, input)));
+        /**
+         * ⚠️ 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 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",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                // Creating an agent creates a principal in Gate, which is a system outside Intel.
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.nodes.createAgent(actor, input, { token: deps.bearer })));
     }
     if (permits(deps.authorization, "knowledge", "write")) {
-        server.registerTool("knowledge_save", {
-            title: "Save knowledge version",
+        server.registerTool("agent_update", {
+            title: "Update agent definition",
+            description: "Append an immutable definition version to an agent using an optimistic base version.",
+            inputSchema: SaveAgentDefinitionInput,
+            annotations: {
+                title: "Update agent definition",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, 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.",
-            inputSchema: SaveKnowledgeVersionInput,
+            inputSchema: SaveNodeVersionInput,
             annotations: {
-                title: "Save knowledge version",
+                title: "Save node version",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.save(actor, input)));
-        server.registerTool("knowledge_attachment_save", {
-            title: "Save knowledge attachment",
+        }, async (input) => text(await deps.nodes.save(actor, input)));
+        registerWithAlias(server, { name: "node_attachment_save", deprecated: "knowledge_attachment_save" }, {
+            title: "Save node attachment",
             description: "Append immutable base64 file bytes to an attachment node.",
-            inputSchema: SaveKnowledgeAttachmentInput,
+            inputSchema: SaveAttachmentInput,
+            annotations: {
+                title: "Save node attachment",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.saveAttachment(actor, input)));
+        // The import half of the bundle round trip (#137). At minimum the manifest way: a zip made by
+        // the export — or a naked zipped folder — lands as a new subtree under the target. Same
+        // service as HTTP, so authorization, limits, remapping, and the all-or-nothing write cannot
+        // differ by surface; only the transport differs (inline base64 here, a streamed body there).
+        server.registerTool("node_import_bundle", {
+            title: "Import bundle",
+            description: "Import a zip bundle (base64) as a new subtree under an authorized target folder — null files at the root. Kinds come from manifest.json when present, from file extensions otherwise. Always creates new nodes; links and flow references between bundled entries are rewritten to the new IDs. Bundles beyond ~10 MB take the streaming HTTP route POST /nodes/:nodeId/import.",
+            inputSchema: ImportBundleInput,
             annotations: {
-                title: "Save knowledge attachment",
+                title: "Import bundle",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.saveAttachment(actor, input)));
-        server.registerTool("knowledge_table_define", {
-            title: "Define knowledge table columns",
+        }, async (input) => text(await deps.bundle.importBundle(bundleActor, {
+            targetNodeId: input.nodeId,
+            zip: decodeZipBase64(input.zipBase64),
+            idempotencyKey: input.idempotencyKey,
+        })));
+        registerWithAlias(server, { name: "node_table_define", deprecated: "knowledge_table_define" }, {
+            title: "Define node table columns",
             description: "Write the column names of an empty table. The header is the contract every append is checked against and cannot be rewritten.",
-            inputSchema: DefineKnowledgeTableInput,
+            inputSchema: DefineTableInput,
             annotations: {
-                title: "Define knowledge table columns",
+                title: "Define node table columns",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.defineTable(actor, input)));
+        }, async (input) => text(await deps.nodes.defineTable(actor, input)));
         // The tool #40 exists for: an agent collecting findings on a schedule appends them without
         // reading or resending what is already there, and two agents appending at once lose nothing.
-        server.registerTool("knowledge_table_append", {
-            title: "Append knowledge table rows",
+        registerWithAlias(server, { name: "node_table_append", deprecated: "knowledge_table_append" }, {
+            title: "Append node table rows",
             description: "Append rows to a table without reading or resending its existing content. Each row must have exactly as many cells as the table has columns; a row that does not is rejected and nothing is written.",
-            inputSchema: AppendKnowledgeTableRowsInput,
+            inputSchema: AppendTableRowsInput,
             annotations: {
-                title: "Append knowledge table rows",
+                title: "Append node table rows",
                 readOnlyHint: false,
                 destructiveHint: false,
                 // The idempotency key makes a repeat of the same call a no-op; without one, appending
@@ -264,74 +471,120 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.appendTableRows(actor, input)));
-        server.registerTool("knowledge_update", {
-            title: "Update knowledge",
-            description: "Rename, move, describe, or change the context policy of Knowledge.",
-            inputSchema: UpdateKnowledgeNodeInput,
+        }, async (input) => text(await deps.nodes.appendTableRows(actor, input)));
+        // The other half of #135: an agent that wrote a wrong finding can correct it. Positions address
+        // rows — they carry no IDs on purpose — so every mutation names the version the positions were
+        // read from and is refused with `version_conflict` when the table moved on. No `knowledge_*`
+        // alias: these tools are new under the post-#125 naming and never carried the old prefix.
+        server.registerTool("node_table_update_rows", {
+            title: "Update node table rows",
+            description: "Replace rows at the given zero-based positions. Requires the baseVersionId the positions were read from (see node_table_get); answers version_conflict and writes nothing when the table has changed since. Each replacement row must match the column count.",
+            inputSchema: UpdateTableRowsInput,
             annotations: {
-                title: "Update knowledge",
+                title: "Update node table rows",
                 readOnlyHint: false,
-                destructiveHint: false,
+                // Replacing a cell discards what stood there; the history keeps it, the table does not.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.updateTableRows(actor, input)));
+        server.registerTool("node_table_delete_rows", {
+            title: "Delete node table rows",
+            description: "Remove rows at the given zero-based positions. Requires the baseVersionId the positions were read from; answers version_conflict and writes nothing when the table has changed since.",
+            inputSchema: DeleteTableRowsInput,
+            annotations: {
+                title: "Delete node table rows",
+                readOnlyHint: false,
+                destructiveHint: true,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.update(actor, input)));
-        server.registerTool("knowledge_archive", {
-            title: "Archive knowledge",
-            description: "Archive or restore one Knowledge node using optimistic concurrency.",
-            inputSchema: ArchiveKnowledgeNodeInput,
+        }, async (input) => text(await deps.nodes.deleteTableRows(actor, input)));
+        server.registerTool("node_table_redefine", {
+            title: "Redefine node table columns",
+            description: "Change the header of a defined table through an explicit column mapping: each new column names the current column that fills it (rename or keep), names none to start empty (add), and a current column no entry names is removed with its cells. Requires the baseVersionId the mapping was read from. Defining over an existing header without a mapping stays refused.",
+            inputSchema: RedefineTableInput,
             annotations: {
-                title: "Archive knowledge",
+                title: "Redefine node table columns",
                 readOnlyHint: false,
                 destructiveHint: true,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.archive(actor, input)));
+        }, async (input) => text(await deps.nodes.redefineTable(actor, input)));
+        registerWithAlias(server, { name: "node_update", deprecated: "knowledge_update" }, {
+            title: "Update node",
+            description: "Rename, move, or describe a node.",
+            inputSchema: UpdateNodeInput,
+            annotations: {
+                title: "Update node",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.update(actor, input)));
+        registerWithAlias(server, { name: "node_archive", deprecated: "knowledge_archive" }, {
+            title: "Archive node",
+            description: "Archive or restore one node using optimistic concurrency. Archiving an agent also switches off its Gate application; restoring switches it back on.",
+            inputSchema: ArchiveNodeInput,
+            annotations: {
+                title: "Archive node",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                // The one node mutation that can reach a system outside Intel: archiving an agent
+                // switches its Gate Application (#182). Nothing else here leaves the installation.
+                openWorldHint: true,
+            },
+        }, 
+        // The caller's own bearer, exactly as the runtime proxy uses it and for the same reason:
+        // switching a machine principal is an act in Gate, performed by the person asking.
+        async (input) => text(await deps.nodes.archive(actor, input, { token: deps.bearer })));
     }
     if (permits(deps.authorization, "knowledge", "share")) {
-        server.registerTool("knowledge_shares_list", {
-            title: "List knowledge shares",
-            description: "List direct grants for Knowledge the caller is allowed to manage.",
-            inputSchema: ListKnowledgeGrantsInput,
+        registerWithAlias(server, { name: "node_shares_list", deprecated: "knowledge_shares_list" }, {
+            title: "List node shares",
+            description: "List direct grants for nodes the caller is allowed to manage.",
+            inputSchema: ListGrantsInput,
             annotations: {
-                title: "List knowledge shares",
+                title: "List node shares",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.listGrants(actor, input.resourceId)));
-        server.registerTool("knowledge_share", {
-            title: "Share knowledge",
-            description: "Grant inherited Knowledge access to a Gate user, verified email, or the organization.",
-            inputSchema: ShareKnowledgeInput,
+        }, async (input) => text(await deps.nodes.listGrants(actor, input.resourceId)));
+        registerWithAlias(server, { name: "node_share", deprecated: "knowledge_share" }, {
+            title: "Share node",
+            description: "Grant inherited node access to a Gate user, verified email, or the organization.",
+            inputSchema: ShareInput,
             annotations: {
-                title: "Share knowledge",
+                title: "Share node",
                 readOnlyHint: false,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.share(actor, input)));
-        server.registerTool("knowledge_revoke_share", {
-            title: "Revoke knowledge share",
-            description: "Revoke one direct Knowledge grant by ID.",
-            inputSchema: RevokeKnowledgeGrantInput,
+        }, async (input) => text(await deps.nodes.share(actor, input)));
+        registerWithAlias(server, { name: "node_revoke_share", deprecated: "knowledge_revoke_share" }, {
+            title: "Revoke node share",
+            description: "Revoke one direct node grant by ID.",
+            inputSchema: RevokeGrantInput,
             annotations: {
-                title: "Revoke knowledge share",
+                title: "Revoke node share",
                 readOnlyHint: false,
                 destructiveHint: true,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.knowledge.revokeGrant(actor, input)));
+        }, async (input) => text(await deps.nodes.revokeGrant(actor, input)));
     }
     if (permits(deps.authorization, "flows", "read")) {
         server.registerTool("flows_list", {
             title: "List flows",
-            description: "List authorized flows, either all of them or the ones filed in one folder of the shared Knowledge tree.",
+            description: "List authorized flows, either all of them or the ones filed in one folder of the shared tree.",
             inputSchema: ListFlowsInput,
             annotations: {
                 title: "List flows",
@@ -353,6 +606,33 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.get(flowActor, input.flowId)));
+        // Named like `knowledge_versions_list`, because it is the same question about the other kind of
+        // thing in the tree. This pair is what turns the `versionId` that `flow_publish` and
+        // `flow_publish_preview` demand into something an MCP client can actually obtain (#144).
+        server.registerTool("flow_versions_list", {
+            title: "List flow versions",
+            description: "List the immutable versions of one authorized flow, oldest first, marking which of them is published. Metadata only; flow_version_get loads a version's graph.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List flow versions",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listVersions(flowActor, input.flowId)));
+        server.registerTool("flow_version_get", {
+            title: "Get flow version",
+            description: "Get one immutable version of an authorized flow, including its graph.",
+            inputSchema: GetFlowVersionInput,
+            annotations: {
+                title: "Get flow version",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.getVersion(flowActor, input)));
         server.registerTool("flow_calls_list", {
             title: "List called flows",
             description: "List the flows one flow calls, read out of its graph rather than out of where it is filed.",
@@ -394,7 +674,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.flows.validate(flowActor, input.flowId)));
         server.registerTool("flow_requirements_list", {
             title: "List what a flow needs",
-            description: "List the Knowledge documents and MCP tools one flow's graph names. Documents the calling user cannot see are counted rather than named, and no claim is made about whether anyone may reach them: for tools that cannot be known in advance, because the catalog is a live query with each user's own portal token.",
+            description: "List the documents and MCP tools one flow's graph names. Documents the calling user cannot see are counted rather than named, and no claim is made about whether anyone may reach them: for tools that cannot be known in advance, because the catalog is a live query with each user's own portal token.",
             inputSchema: GetFlowInput,
             annotations: {
                 title: "List what a flow needs",
@@ -417,7 +697,7 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.getRun(flowActor, input.runId)));
         // ⚠️ Model context like every other tool result: what a run did, never what it produced. The run
-        // input and output are absent because a run reaches Knowledge and tools with the rights of
+        // input and output are absent because a run reaches nodes and tools with the rights of
         // whoever started it, and only their own runs are the calling user's to read out that way.
         server.registerTool("flow_runs_list", {
             title: "List flow runs",
@@ -445,7 +725,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.flows.listRunSteps(flowActor, input.runId)));
     }
     // A flow has no share tool of its own. Sharing happens on the folder a flow is filed in, through
-    // knowledge_share, so a narrower grant cannot sit beside the folder grant (ADR-0004 §2).
+    // node_share, so a narrower grant cannot sit beside the folder grant (ADR-0004 §2).
     if (permits(deps.authorization, "flows", "create")) {
         server.registerTool("flow_create", {
             title: "Create flow",
@@ -463,7 +743,7 @@ export async function handleMcp(request, deps) {
     if (permits(deps.authorization, "flows", "write")) {
         server.registerTool("flow_update", {
             title: "Rename or move flow",
-            description: "Rename a flow, change its description, or move it to another folder of the shared Knowledge tree. Never changes what the flow does.",
+            description: "Rename a flow, change its description, or move it to another folder of the shared tree. Never changes what the flow does.",
             inputSchema: UpdateFlowInput,
             annotations: {
                 title: "Rename or move flow",
@@ -518,7 +798,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.flows.previewPublish(flowActor, input)));
         server.registerTool("flow_publish", {
             title: "Publish flow",
-            description: "Publish a version after resolving its authorized Knowledge and tool references.",
+            description: "Publish a version after resolving its authorized node and tool references.",
             inputSchema: PublishFlowInput,
             annotations: {
                 title: "Publish flow",
@@ -528,6 +808,20 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.publish(flowActor, input)));
+        server.registerTool("flow_unpublish", {
+            title: "Unpublish flow",
+            description: "Withdraw a flow's published version. Versions are kept and can be republished; new runs and calls from other flows stop resolving, runs in flight finish on the version they took.",
+            inputSchema: UnpublishFlowInput,
+            annotations: {
+                title: "Unpublish flow",
+                readOnlyHint: false,
+                // Nothing is deleted and republishing is one publish away — destructive all the same,
+                // because a flow another flow calls stops resolving, like flow_archive.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.unpublish(flowActor, input)));
     }
     if (permits(deps.authorization, "flows", "run")) {
         server.registerTool("flow_run_start", {
@@ -554,6 +848,92 @@ export async function handleMcp(request, deps) {
                 openWorldHint: true,
             },
         }, async (input) => text(await deps.flows.completeStep(flowActor, input)));
+        server.registerTool("flow_run_cancel", {
+            title: "Cancel flow run",
+            description: "Cancel a running flow run without recording a step failure. Running child runs it called are cancelled with it; a run that is already terminal is refused unchanged.",
+            inputSchema: CancelFlowRunInput,
+            annotations: {
+                title: "Cancel flow run",
+                readOnlyHint: false,
+                // Nothing is deleted, but work in flight is ended for the run and its children — a
+                // client deciding whether to ask first has to be told that.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.cancelRun(flowActor, input)));
+    }
+    /**
+     * Driving an agent, over the same door the screen uses.
+     *
+     * ⚠️ The three below are the MCP half of the two head actions on the agent page — the repository's
+     * "one business layer, three thin surfaces" rule, kept in the same delivery. They call the runtime
+     * through `deps.agents`, which resolves the resource ACL and forwards the CALLER's bearer; a tool
+     * that reached the runtime with anything else would be Intel acting as somebody it is not.
+     */
+    if (permits(deps.authorization, "agents", "run")) {
+        server.registerTool("agent_pause", {
+            title: "Pause agent",
+            description: "Stop an agent from acting on its own: no schedule fires, no task and no mail is taken. Its chat keeps answering, and nothing is queued up for later.",
+            inputSchema: PauseAgentInput,
+            annotations: {
+                title: "Pause agent",
+                readOnlyHint: false,
+                // Nothing is deleted, and yet work that would have happened does not — a client deciding
+                // whether to ask first has to be told that.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.agents.request({
+            actor: agentActor,
+            token: deps.bearer,
+            agentId: input.nodeId,
+            method: "POST",
+            path: "/pause",
+            body: "{}",
+        })));
+        server.registerTool("agent_resume", {
+            title: "Resume agent",
+            description: "Let a paused agent act again. Its schedules are armed from the definition as it stands now; nothing that was due while it stood still is caught up.",
+            inputSchema: PauseAgentInput,
+            annotations: {
+                title: "Resume agent",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.agents.request({
+            actor: agentActor,
+            token: deps.bearer,
+            agentId: input.nodeId,
+            method: "POST",
+            path: "/resume",
+            body: "{}",
+        })));
+        server.registerTool("agent_run_now", {
+            title: "Run agent now",
+            description: "Fire one of the agent's own schedules straight away, against the document or flow it names. The run appears in the agent's run list; a target the agent does not schedule is refused.",
+            inputSchema: RunAgentNowInput,
+            annotations: {
+                title: "Run agent now",
+                readOnlyHint: false,
+                destructiveHint: false,
+                // Every run is a new run, so asking twice runs it twice.
+                idempotentHint: false,
+                // The agent may reach whatever its own definition grants it, so what a run touches is not
+                // knowable from this schema.
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.agents.request({
+            actor: agentActor,
+            token: deps.bearer,
+            agentId: input.nodeId,
+            method: "POST",
+            path: "/run",
+            body: JSON.stringify({ target: input.target }),
+        })));
     }
     if (permits(deps.authorization, "tools", "read")) {
         server.registerTool("tools_catalog_list", {
@@ -568,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", {