@anchrd/intel-api 0.12.5 → 0.14.0

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AddBoardTaskInput, AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, ConfigureBoardInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetBoardInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, MoveBoardTaskInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateBoardTaskInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
+import { AddBoardTaskInput, AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, ConfigureBoardInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetBoardInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, MoveBoardTaskInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, RepairBoardTaskIdsInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateBoardTaskInput, 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";
@@ -8,18 +8,18 @@ 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.
+ * ⚠️ One name per tool, and the second one is gone for good (#149).
  *
- * ⚠️ 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.
+ * Every tool here carried a `knowledge_*` alias beside its name from #125 until today. The alias
+ * was never politeness: a tool name lives in somebody else's configuration — a portal endpoint, an
+ * agent definition, a saved prompt — so renaming it here alone breaks them at the moment we deploy
+ * rather than at a moment they chose. ADR-0005 §8 therefore kept both, **for a transition**.
+ *
+ * A transition without an end date is not a transition, it is a second permanent name — and two
+ * names for one tool is exactly the friction #125 removed. It ends here. What follows for anybody
+ * writing a tool: there is one name, and a rename is a breaking change that needs its own ticket
+ * and its own notice, not a quiet second entry.
  */
-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.
@@ -112,7 +112,7 @@ export async function handleMcp(request, deps) {
         name: deps.authorization.identity.name ?? null,
     }));
     if (permits(deps.authorization, "knowledge", "read")) {
-        registerWithAlias(server, { name: "node_list", deprecated: "knowledge_list" }, {
+        server.registerTool("node_list", {
             title: "List nodes",
             description: "List authorized folders, documents, attachments, and tables under one parent.",
             inputSchema: ListNodesInput,
@@ -124,7 +124,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.list(actor, input)));
-        registerWithAlias(server, { name: "node_get", deprecated: "knowledge_get" }, {
+        server.registerTool("node_get", {
             title: "Get node",
             description: "Get one authorized node and its current immutable content version.",
             inputSchema: GetNodeInput,
@@ -136,7 +136,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.get(actor, input.nodeId)));
-        registerWithAlias(server, { name: "node_versions_list", deprecated: "knowledge_versions_list" }, {
+        server.registerTool("node_versions_list", {
             title: "List node versions",
             description: "List immutable versions of one authorized node.",
             inputSchema: GetNodeInput,
@@ -163,7 +163,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getVersion(actor, input.nodeId, input.versionId)));
-        registerWithAlias(server, { name: "node_attachment_get", deprecated: "knowledge_attachment_get" }, {
+        server.registerTool("node_attachment_get", {
             title: "Get node attachment",
             description: "Get authorized immutable attachment metadata and its explicit MCP resource URI.",
             inputSchema: GetNodeInput,
@@ -199,7 +199,7 @@ export async function handleMcp(request, deps) {
                 ],
             };
         });
-        registerWithAlias(server, { name: "search", deprecated: "knowledge_search" }, {
+        server.registerTool("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 " +
@@ -240,7 +240,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getAgent(actor, input)));
-        registerWithAlias(server, { name: "node_table_get", deprecated: "knowledge_table_get" }, {
+        server.registerTool("node_table_get", {
             title: "Get node table",
             description: "Read one authorized table as column names and rows.",
             inputSchema: GetTableInput,
@@ -267,7 +267,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getBoard(actor, input)));
-        registerWithAlias(server, { name: "node_links_list", deprecated: "knowledge_links_list" }, {
+        server.registerTool("node_links_list", {
             title: "List node links",
             description: "List authorized outgoing links and backlinks for one node.",
             inputSchema: GetNodeInput,
@@ -286,7 +286,7 @@ export async function handleMcp(request, deps) {
         // ⚠️ 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.
-        registerWithAlias(server, { name: "node_links_resolve", deprecated: "knowledge_links_resolve" }, {
+        server.registerTool("node_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: ResolveNodeLinksInput,
@@ -298,7 +298,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.resolveLinks(actor, input)));
-        registerWithAlias(server, { name: "node_graph", deprecated: "knowledge_graph" }, {
+        server.registerTool("node_graph", {
             title: "Get node graph",
             description: "Get the authorized nodes and explicit relationships for discovery.",
             inputSchema: NodeGraphInput,
@@ -330,7 +330,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.bundle.manifest(bundleActor, input.nodeId)));
     }
     if (deps.authorization.can("intel", "admin")) {
-        registerWithAlias(server, { name: "node_reindex", deprecated: "knowledge_reindex" }, {
+        server.registerTool("node_reindex", {
             title: "Reindex nodes",
             description: "Queue every current canonical node version for derived index rebuild.",
             inputSchema: EmptyInput,
@@ -344,7 +344,7 @@ export async function handleMcp(request, deps) {
         }, async () => text(await deps.nodes.reindex(actor)));
     }
     if (permits(deps.authorization, "knowledge", "create")) {
-        registerWithAlias(server, { name: "node_create", deprecated: "knowledge_create" }, {
+        server.registerTool("node_create", {
             title: "Create node",
             description: "Create a governed folder, document, attachment, or table node.",
             inputSchema: CreateNodeInput,
@@ -415,7 +415,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: true,
             },
         }, async (input) => text(await deps.nodes.rotateAgentKey(actor, input, { token: deps.bearer })));
-        registerWithAlias(server, { name: "node_save", deprecated: "knowledge_save" }, {
+        server.registerTool("node_save", {
             title: "Save node version",
             description: "Append an immutable content version using an optimistic base version.",
             inputSchema: SaveNodeVersionInput,
@@ -427,7 +427,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.save(actor, input)));
-        registerWithAlias(server, { name: "node_attachment_save", deprecated: "knowledge_attachment_save" }, {
+        server.registerTool("node_attachment_save", {
             title: "Save node attachment",
             description: "Append immutable base64 file bytes to an attachment node.",
             inputSchema: SaveAttachmentInput,
@@ -459,7 +459,7 @@ export async function handleMcp(request, deps) {
             zip: decodeZipBase64(input.zipBase64),
             idempotencyKey: input.idempotencyKey,
         })));
-        registerWithAlias(server, { name: "node_table_define", deprecated: "knowledge_table_define" }, {
+        server.registerTool("node_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: DefineTableInput,
@@ -473,7 +473,7 @@ export async function handleMcp(request, deps) {
         }, 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.
-        registerWithAlias(server, { name: "node_table_append", deprecated: "knowledge_table_append" }, {
+        server.registerTool("node_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: AppendTableRowsInput,
@@ -540,7 +540,7 @@ export async function handleMcp(request, deps) {
          */
         server.registerTool("board_configure", {
             title: "Configure board statuses",
-            description: 'Write the board\'s whole status list, in the order it should be drawn. Adding, renaming and reordering columns are all this call. The "archived" status is part of every board and cannot be removed, and a status that tasks still sit in cannot be removed either.',
+            description: 'Write the board\'s whole status list, in the order it should be drawn. Adding, renaming and reordering columns are all this call. The "archived" status is part of every board and cannot be removed, and a status that tasks still sit in cannot be removed either. Set "terminal" on a column to say that standing in it means the work is finished — that is what decides whether a task waiting on another is still blocked. Several columns may be terminal; "archived" always is and cannot be set otherwise. Omitting it leaves an ordinary column not terminal.',
             inputSchema: ConfigureBoardInput,
             annotations: {
                 title: "Configure board statuses",
@@ -553,7 +553,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.nodes.configureBoard(actor, input)));
         server.registerTool("board_task_add", {
             title: "Add board task",
-            description: "Add one task to a board. The server assigns its id and its place in the order; name afterTaskId or beforeTaskId to put it between two cards, or neither to put it last in its column. parentId makes it a subtask of another task on the same board, dependsOn names tasks of the same board it waits for, and references names Intel nodes. Needs no baseVersionId: tasks are addressed by id, so parallel writers do not collide.",
+            description: "Add one task to a board. The server assigns its id and its place in the order; name afterTaskId or beforeTaskId to put it between two cards, or neither to put it last in its column. parentId makes it a subtask of another task on the same board, dependsOn names tasks of the same board it waits for, and references names Intel nodes. dependsOn, labels and references are sets: naming the same task, word or node twice is refused rather than quietly folded together. Needs no baseVersionId: tasks are addressed by id, so parallel writers do not collide.",
             inputSchema: AddBoardTaskInput,
             annotations: {
                 title: "Add board task",
@@ -565,7 +565,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.nodes.addBoardTask(actor, input)));
         server.registerTool("board_task_update", {
             title: "Update board task",
-            description: "Change what a task says: title, assignee, labels, dates, dependencies, description or references. Where a task SITS — its status, its parent, its order — is board_task_move instead. Every named field replaces its current value whole; fields that are not named stay as they are.",
+            description: "Change what a task says: title, assignee, labels, dates, dependencies, description or references. Where a task SITS — its status, its parent, its order — is board_task_move instead. Every named field replaces its current value whole; fields that are not named stay as they are. dependsOn, labels and references are sets: appending to a list this task already holds is refused rather than quietly folded together, so read the current value before you write it back.",
             inputSchema: UpdateBoardTaskInput,
             annotations: {
                 title: "Update board task",
@@ -601,7 +601,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.deleteBoardTask(actor, input)));
-        registerWithAlias(server, { name: "node_update", deprecated: "knowledge_update" }, {
+        server.registerTool("board_repair_task_ids", {
+            title: "Repair repeated board task ids",
+            description: "Give a fresh id to every task entry on a board that repeats an id another entry already used. Only a board imported from a hand-written or foreign bundle can hold such a pair, and it cannot be repaired with the other calls: they address a task by id, so they would read, write or remove both entries at once. The first entry under an id keeps it — that is the one every parentId and dependsOn on the board already means — and each later one becomes its own task with everything else it carries, so nothing is lost and no edge is invented. The answer names each pair. A board that names every task once is refused rather than rewritten. Repeated STATUS ids are repaired with board_configure instead, by writing the status list with distinct ids.",
+            inputSchema: RepairBoardTaskIdsInput,
+            annotations: {
+                title: "Repair repeated board task ids",
+                readOnlyHint: false,
+                // Nothing is removed and nothing is overwritten: one entry gains an id of its own and
+                // every other field on every task stays exactly as it stood.
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.repairBoardTaskIds(actor, input)));
+        server.registerTool("node_update", {
             title: "Update node",
             description: "Rename, move, or describe a node.",
             inputSchema: UpdateNodeInput,
@@ -613,7 +627,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.update(actor, input)));
-        registerWithAlias(server, { name: "node_archive", deprecated: "knowledge_archive" }, {
+        server.registerTool("node_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,
@@ -632,7 +646,7 @@ export async function handleMcp(request, deps) {
         async (input) => text(await deps.nodes.archive(actor, input, { token: deps.bearer })));
     }
     if (permits(deps.authorization, "knowledge", "share")) {
-        registerWithAlias(server, { name: "node_shares_list", deprecated: "knowledge_shares_list" }, {
+        server.registerTool("node_shares_list", {
             title: "List node shares",
             description: "List direct grants for nodes the caller is allowed to manage.",
             inputSchema: ListGrantsInput,
@@ -644,7 +658,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.listGrants(actor, input.resourceId)));
-        registerWithAlias(server, { name: "node_share", deprecated: "knowledge_share" }, {
+        server.registerTool("node_share", {
             title: "Share node",
             description: "Grant inherited node access to a Gate user, verified email, or the organization.",
             inputSchema: ShareInput,
@@ -656,7 +670,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.share(actor, input)));
-        registerWithAlias(server, { name: "node_revoke_share", deprecated: "knowledge_revoke_share" }, {
+        server.registerTool("node_revoke_share", {
             title: "Revoke node share",
             description: "Revoke one direct node grant by ID.",
             inputSchema: RevokeGrantInput,

package/dist/nodes/board/board.d.ts

@@ -1,4 +1,50 @@
+import { type BoardDocument } from "@anchrd/intel-contract";
 import type { BoardDeps, BoardOperations } from "./board.types.js";
+/**
+ * A stored board brought up to the current schema, before it is validated.
+ *
+ * ⚠️ It runs before `BoardDocument.parse`, on `unknown`, because after that parse a missing field or
+ * a repeated id is already a refusal — and `parseStoredBoard` is deliberately loud
+ * (`board_unreadable`), so an un-upgraded board would not read as "old", it would read as corrupt.
+ *
+ * The upgrade is persisted by the next write of any kind, because every write serialises the whole
+ * document. Nothing has to be migrated ahead of time and nothing has to be re-migrated.
+ */
+export declare function upgradeStoredBoard(parsed: unknown): unknown;
+/**
+ * The first id a board document uses for two different things (anchrd/intel#321).
+ *
+ * ⚠️ Deliberately NOT a rule on `BoardDocument`, and that is the whole decision. A schema rule would
+ * reach every parse of a stored body — `parseStoredBoard`, `indexing.ts`, the link reader — and a
+ * board imported before this existed would stop answering with `board_unreadable`: the whole board
+ * gone over something that costs one view. It is the trap #311 walked into, and #318 walked into
+ * from the other side.
+ *
+ * ⚠️ And NOT folded in `upgradeStoredBoard` either, which is where the sibling rules of #318 went. A
+ * repeated `dependsOn`, label or reference carries no information, so dropping the second mention
+ * loses nothing. Two tasks under one id are two whole tasks — titles, dates, descriptions — and a
+ * fold on the READ is written back by the next save of any kind, because every write serialises the
+ * whole document. That is one task gone for good, for every board, without anybody having asked.
+ * The UI folds the same pair for a DRAWING (`orderedTasks`), which costs nothing: the document keeps
+ * both, and repairing the pair brings the second card back.
+ *
+ * ⚠️ What this does NOT rescue, and it is worth knowing: `replaced` matches a task by id, so the
+ * first `board_task_update` against such a pair writes the SAME task into both entries. The stored
+ * board is then two identical tasks rather than two different ones. That is a consequence of
+ * addressing a board by task id at all (#285) and predates this rule; the reason the rule is at the
+ * import is to stop the pair from existing, not to make it survivable. A board that already holds
+ * one is repaired by `repairTaskIds` below — asked for, never done on the quiet — and the refusal
+ * here names it, because "your file is wrong" without a way out is where anchrd/intel#341 started.
+ *
+ * So it is asked exactly where there is a caller to answer: the bundle import, the one door a board
+ * document written elsewhere comes in through. Everything else mints task ids itself (`deps.id()`)
+ * and takes its status list through `ConfigureBoardInput`, which has demanded distinct ids since
+ * #285.
+ */
+export declare function repeatedBoardId(document: BoardDocument): {
+    list: "statuses" | "tasks";
+    id: string;
+} | null;
 /**
  * Every board operation, applied to the document rather than to the file (#285).
  *