@anchrd/intel-api 0.37.1 → 0.39.0

package/dist/adapters/db/db.js

@@ -1,4 +1,4 @@
-import { descendantsCte, grantColumns as grantColumnsFor, grantInForce, mapGrant, nodeVerbBindings, nodeVerbQuery, principalColumns, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { descendantsCte, flowInSubtree, flowInSubtreeBindings, grantColumns as grantColumnsFor, grantInForce, mapGrant, nodeVerbBindings, nodeVerbQuery, principalColumns, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const versionColumns = `id, node_id, sequence, content_key, media_type, content_hash,
   size, segment, created_by, created_at`;
 const grantColumns = grantColumnsFor("node_id");
@@ -70,6 +70,18 @@ export function createNodeRepository(deps) {
     // same question of the same table.
     const visibleCte = subtreeCte;
     const readBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
+    /**
+     * What a LEVEL query binds: the walk over `nodes`, then the flow half of `has_children`, in the
+     * order the two appear in the statement.
+     *
+     * ⚠️ One clock reading for both halves. Two calls to `deps.now()` inside one statement would
+     * measure the same `expires_at` against two different moments, and a grant that expires between
+     * them would be honoured on one side of the OR and refused on the other.
+     */
+    const levelBindings = (actor) => {
+        const now = deps.now().toISOString();
+        return [...subtreeBindings(actor, "read", now), ...flowInSubtreeBindings(actor, "read", now)];
+    };
     /**
      * The optional folder cut a search carries (#126), in the three places one statement needs it:
      * the extra CTE, the extra join, and the one binding between the actor's and the query's. All
@@ -126,8 +138,14 @@ export function createNodeRepository(deps) {
      * everywhere would make a link to a task a dead end.
      */
     const notInTree = (alias) => `${alias}.kind <> 'task'`;
-    const visibleChildren = (bounded) => `${visibleCte}
-    SELECT ${nodeColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""},
+    /**
+     * The chevron column, and it is drawn ONLY for the tree (#777). The bounded read the relation
+     * graph makes discards it, and since #777 it is no longer free: computing it costs a second
+     * correlated `EXISTS` per row and six bindings that statement has no other use for. Leaving it
+     * out there is not a divergence in the visibility predicate, which is what the two forms share;
+     * it is one column the caller never reads.
+     */
+    const chevronColumn = `
       -- Whether this row has children THIS actor may see (#59), asked of the same allowed set one
       -- level down. A second rule written here would drift from the one above it, and the drift
       -- would show as a chevron that opens onto nothing.
@@ -137,11 +155,29 @@ export function createNodeRepository(deps) {
       -- actor can see, and the chevron falls away by itself (D66, #376). Leaving it out here would
       -- draw a chevron that opens onto an empty level — exactly the drift the comment above warns
       -- about, arriving through the door it was written for.
-      EXISTS (
+      --
+      -- ⚠️ And the SECOND half of the level, because the tree is shared: a folder holds nodes and
+      -- flows side by side (ADR-0004 §1), and a flow is not a node. Asking only the nodes table
+      -- left a folder whose only children are flows answering "empty": no chevron, no way down,
+      -- while clicking the folder listed both kinds perfectly well (#777). It is the same root as
+      -- #457, where a count over nodes alone held such a folder for empty on the delete path; that
+      -- one was fixed, this one was not.
+      --
+      -- ⚠️ flowInSubtree rather than a hand-written condition, for the reason stated above it: it
+      -- is the very predicate db-flows.ts draws the level with, so the chevron and the level it
+      -- opens onto cannot answer differently. Its folder clause is already satisfied here (the
+      -- flow's parent is n, and n is joined to allowed), so today it can only widen the answer,
+      -- never narrow it, which is the only direction a chevron may drift in at all.
+      (EXISTS (
         SELECT 1 FROM nodes child
         JOIN allowed AS allowed_child ON allowed_child.id = child.id
         WHERE child.parent_id = n.id AND child.archived_at IS NULL AND ${notInTree("child")}
-      ) AS has_children
+      ) OR EXISTS (
+        SELECT 1 FROM flows flow
+        WHERE flow.parent_id = n.id AND flow.archived_at IS NULL AND ${flowInSubtree}
+      )) AS has_children`;
+    const visibleChildren = (bounded) => `${visibleCte}
+    SELECT ${nodeColumns}${bounded ? ", COUNT(*) OVER () AS total" : `,${chevronColumn}`}
     FROM nodes n
     JOIN allowed ON allowed.id = n.id
     WHERE ${levelPredicate} AND (? = 1 OR n.archived_at IS NULL) AND ${notInTree("n")}
@@ -166,9 +202,17 @@ export function createNodeRepository(deps) {
         async listVisible(actor, input) {
             const result = await deps.db
                 .prepare(input.archivedOnly ? archivedEverywhere : visibleChildren(false))
-                .bind(...readBindings(actor), ...(input.archivedOnly
-                ? []
-                : [input.parentId, input.parentId, input.includeArchived ? 1 : 0]))
+                .bind(
+            // ⚠️ The archive statement answers `has_children` as a literal 0, so it carries no flow
+            // bindings; the level statement carries both halves. Same branch, two bind lists.
+            ...(input.archivedOnly
+                ? readBindings(actor)
+                : [
+                    ...levelBindings(actor),
+                    input.parentId,
+                    input.parentId,
+                    input.includeArchived ? 1 : 0,
+                ]))
                 .all();
             const rows = result.results ?? [];
             return {
@@ -179,6 +223,9 @@ export function createNodeRepository(deps) {
         async listVisibleBounded(actor, input) {
             const result = await deps.db
                 .prepare(visibleChildren(true))
+                // ⚠️ `readBindings`, not `levelBindings`: this form carries no chevron column, so the
+                // flow half's six bindings have no placeholder to land in. D1 answers a miscount with
+                // `Wrong number of parameter bindings`, so the two cannot silently go out of step.
                 .bind(...readBindings(actor), input.parentId, input.parentId, 0, input.limit)
                 .all();
             const rows = result.results ?? [];
@@ -1340,6 +1387,31 @@ export function createNodeRepository(deps) {
                 .all();
             return { nodes, links: (linkResult.results ?? []).map(mapLink) };
         },
+        /**
+         * The same `allowed` set every other read joins against, narrowed to attachments (#773).
+         *
+         * ⚠️ Ordered and paged by `n.id` rather than by title: the id is the cursor, and a cursor has to
+         * be unique or a page boundary falling between two identical titles silently drops one of them.
+         * `graphVisible` above orders by title because it draws a picture and takes the whole set.
+         */
+        async listVisibleAttachments(actor, input) {
+            const result = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${nodeColumns}
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          WHERE n.archived_at IS NULL
+            AND n.kind = 'attachment'
+            AND (? IS NULL OR n.id > ?)
+          ORDER BY n.id
+          LIMIT ?`)
+                // ⚠️ Positional throughout, and the cursor is bound TWICE. Numbered parameters (?1, ?2)
+                // would count from the first placeholder of the whole statement — and `visibleCte` above
+                // has already spent several of them.
+                .bind(...readBindings(actor), input.after, input.after, input.limit)
+                .all();
+            return (result.results ?? []).map(mapNode);
+        },
         async setGrant(input) {
             const grant = input.grant;
             const { type: principalType, id: principalId } = principalColumns(grant.principal);

package/dist/mcp/mcp.js

@@ -4,7 +4,7 @@ import { BoardAssigneeResolveInput, BoardAssigneeSearchInput, BoardGetInput, Boa
 import { FeedListRequest } from "@anchrd/intel-contract/feed";
 import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
-import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetAttachmentInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
 import { ListEffectiveAccessInput, ListFlowEffectiveAccessInput, ListFlowGrantsInput, ListGrantsInput, RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, ShareInput, } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
@@ -218,7 +218,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.boards.resolveAssignees(actor, input)));
         server.registerTool("board_task_create", {
             title: "Add a card to a board",
-            description: "File a new card on a board. Omit the status to put it in the first column. Name a parent task to make it a subtask — it lands on the same board, and moving an existing card under another one is `node_update` with a new parent. The card is a node like any other: its own address, its own permissions, its own history.",
+            description: "File a new card on a board. Omit the status to put it in the first column. Name a parent task to make it a subtask — it lands on the same board, and moving an existing card under another one is `node_update` with a new parent. The card is a node like any other: its own address, its own permissions, its own history — and its own body. This call answers with the BOARD rather than the new card, so to write that body, make the card with `node_create` under the board instead: it answers with the node itself, files it on the board just the same, and hands you the id `node_version_create` asks for.",
             inputSchema: BoardTaskCreateInput,
             annotations: {
                 title: "Add a card to a board",
@@ -329,8 +329,11 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.nodes.getVersion(actor, input.nodeId, input.versionId)));
         server.registerTool("node_attachment_get", {
             title: "Get node attachment",
-            description: "Get authorized immutable attachment metadata and its explicit MCP resource URI.",
-            inputSchema: GetNodeInput,
+            description: "Get authorized immutable attachment metadata, and with includeContent the file itself. " +
+                "The resourceUri in the answer is this server's own address; a portal that aggregates " +
+                "several servers prefixes it, so read the file through includeContent unless the URI " +
+                "came from resources/list.",
+            inputSchema: GetAttachmentInput,
             annotations: {
                 title: "Get node attachment",
                 readOnlyHint: true,
@@ -338,8 +341,76 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, 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) => {
+        }, 
+        /**
+         * ⚠️ The size is checked BEFORE the stream is opened, which the resource handler below cannot
+         * do — it is handed the body by the SDK and has to cancel it. Here the metadata read is its
+         * own call, so an oversized attachment costs no R2 read at all.
+         *
+         * ⚠️ The bytes go out as an embedded RESOURCE block, never as text. A base64 string in a text
+         * block is something a model will try to read; a resource block is a file to a client that
+         * understands one, and the metadata stays in the first block either way (#773).
+         */
+        async (input) => {
+            const metadata = await deps.nodes.getAttachment(actor, input.nodeId);
+            if (!input.includeContent)
+                return text(metadata);
+            if (metadata.version.size > AttachmentInlineLimit) {
+                throw new IntelError(413, "attachment_too_large", "Attachment is too large to inline; read it over HTTP instead");
+            }
+            const { attachment, body } = await deps.nodes.readAttachment(actor, input.nodeId);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(attachment) },
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: `intel://nodes/${attachment.node.id}/attachment`,
+                            mimeType: attachment.version.mediaType,
+                            blob: await base64(body),
+                        },
+                    },
+                ],
+                isError: false,
+            };
+        });
+        server.registerResource("node-attachment", 
+        /**
+         * ⚠️ `list` is what makes the attachments findable at all, and it was `undefined` until #773.
+         * A client that cannot enumerate them has to GUESS the URI — and the one place it could copy
+         * one from, `node_attachment_get`, answers this server's own address, which a portal that
+         * aggregates several servers prefixes. Measured on 2026-08-24: the URI out of that tool was
+         * refused as `Resource not found` while the prefixed spelling delivered the file.
+         *
+         * ⚠️ The listing is COMPLETE, and the loop below is why it has to be. `ListResourcesCallback`
+         * takes `RequestHandlerExtra` and nothing else — the SDK hands a template's list callback no
+         * cursor (checked against the 1.30.0 type: `(extra) => ListResourcesResult`), so a
+         * `nextCursor` in the answer is one nothing would ever send back. That leaves two honest
+         * options and one dishonest one: answer everything, refuse, or cut the list at some limit and
+         * let it read as complete. The cut is the one that is out — a reader would never learn which
+         * of their files are missing.
+         *
+         * The paging is therefore INTERNAL: D1 is asked in pages so one statement never has to carry
+         * the whole set, and the loop ends when the service stops handing back a cursor.
+         */
+        new ResourceTemplate("intel://nodes/{nodeId}/attachment", {
+            list: async () => {
+                const resources = [];
+                let after = null;
+                do {
+                    const page = await deps.nodes.listAttachments(actor, { limit: 100, after });
+                    resources.push(...page.items.map((node) => ({
+                        uri: `intel://nodes/${node.id}/attachment`,
+                        name: node.title,
+                        // ⚠️ No `mimeType`: it lives on the VERSION, so answering one would cost a version
+                        // read per row. The read itself carries the real one.
+                        description: node.description ?? undefined,
+                    })));
+                    after = page.nextCursor;
+                } while (after !== null);
+                return { resources };
+            },
+        }), { 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();
@@ -468,7 +539,7 @@ export async function handleMcp(request, deps) {
     if (permits(deps.authorization, "nodes", "create")) {
         server.registerTool("node_create", {
             title: "Create node",
-            description: "Create a governed folder, document, attachment, or table node.",
+            description: "Create a governed node: a folder, a board, a document, a card, an attachment or a table. A card made under a board lands on that board, and the answer carries the new node's id — which is what `node_version_create` needs to give it a body.",
             inputSchema: CreateNodeInput,
             annotations: {
                 title: "Create node",
@@ -482,7 +553,7 @@ export async function handleMcp(request, deps) {
     if (permits(deps.authorization, "nodes", "write")) {
         server.registerTool("node_version_create", {
             title: "Create node version",
-            description: "Append an immutable content version using an optimistic base version.",
+            description: "Append an immutable content version using an optimistic base version. Documents and board cards both take one — writing a card here is how a ticket gets a body instead of only a title.",
             inputSchema: SaveNodeVersionInput,
             annotations: {
                 title: "Create node version",

package/dist/nodes/nodes.js

@@ -27,6 +27,22 @@ const nothingWithheld = { titles: [], hidden: 0 };
 function applicableVerbs(kind) {
     return kind === "folder" ? ["read", "write", "execute", "share"] : ["read", "write", "share"];
 }
+/**
+ * Which kinds hold an editor body — the text somebody types and `node_get` reads back.
+ *
+ * ⚠️ **A card is one of them, and that is the whole of D66 on the write side** (#785). A task is a
+ * node like every other: its text is a node version, in the same table, through the same route. The
+ * panel reaches this call through `POST /nodes/:id/versions` exactly as MCP does, so a list that
+ * omitted `task` closed BOTH surfaces at once — an agent could name a card and not describe it, and
+ * a reader typing into the card got "could not be saved" over a body the model says it should hold.
+ *
+ * ⚠️ **A set, not one more `||`.** The other four kinds each carry their content some other way —
+ * a folder and a board hold children, an attachment holds bytes, a table holds CSV segments — and
+ * naming the ones that DO take an editor version is what keeps the next kind from being waved
+ * through by a condition that only ever grew. The annotation ties it to the enum: a kind renamed in
+ * the contract stops this file from compiling instead of silently dropping out of the set.
+ */
+const EditorContentKinds = ["document", "task"];
 // ⚠️ The refusal has to be actionable without becoming a directory of the tree. Whoever holds
 // `share` on one folder must not learn the titles of flows they may not see, so the ones they may
 // see are named and the rest are only counted (ADR-0004 §3, and #17's review) — which is the whole
@@ -666,8 +682,8 @@ export function createNodes(deps) {
                 return document;
             }
             const node = await requireVisible(actor, input.nodeId);
-            if (node.kind !== "document") {
-                throw new IntelError(409, "document_content_required", "Only documents accept editor content versions");
+            if (!EditorContentKinds.includes(node.kind)) {
+                throw new IntelError(409, "document_content_required", "Only documents and cards accept editor content versions");
             }
             if (!(await deps.repository.can(actor, node.id, "write"))) {
                 throw new IntelError(403, "node_forbidden", "This node cannot be edited");
@@ -782,6 +798,23 @@ export function createNodes(deps) {
                 throw new IntelError(500, "content_missing", "Attachment is missing");
             return { attachment: metadata, body };
         },
+        /**
+         * One page of readable attachments for the MCP resource listing (#773).
+         *
+         * ⚠️ It asks the repository for one row MORE than it hands back. Without that, a page that
+         * happens to be exactly full is indistinguishable from a page with more behind it, and the
+         * choice is between always sending a cursor (one wasted round trip per listing) or never
+         * sending one (a silently truncated list, which reads as complete).
+         */
+        async listAttachments(actor, input) {
+            const rows = await deps.repository.listVisibleAttachments(actor, {
+                limit: input.limit + 1,
+                after: input.after,
+            });
+            const items = rows.slice(0, input.limit);
+            const last = items.at(-1);
+            return { items, nextCursor: rows.length > input.limit && last ? last.id : null };
+        },
         async getTable(actor, nodeId) {
             const node = await requireVisible(actor, nodeId);
             if (node.kind !== "table") {

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

@@ -56,6 +56,10 @@ export interface NodeRepository {
     }): Promise<BoundedChildren>;
     getVisible(actor: Actor, nodeId: string): Promise<Node | null>;
     listVisibleSubtree(actor: Actor, rootId: string | null): Promise<SubtreeNode[]>;
+    listVisibleAttachments(actor: Actor, input: {
+        limit: number;
+        after: string | null;
+    }): Promise<Node[]>;
     can(actor: Actor, nodeId: string, verb: ResourceVerb): Promise<boolean>;
     findIdempotentNode(actorId: string, operation: "node.create" | "node.save" | "node.append" | "node.update" | "node.archive" | "node.share" | "node.revoke" | SnapshotOperation, idempotencyKey: string): Promise<string | null>;
     findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
@@ -325,6 +329,13 @@ export interface NodeService {
     redefineTable(actor: Actor, input: RedefineTableInput): Promise<NodeTable>;
     getAttachment(actor: Actor, nodeId: string): Promise<NodeAttachment>;
     readAttachment(actor: Actor, nodeId: string): Promise<NodeAttachmentBody>;
+    listAttachments(actor: Actor, input: {
+        limit: number;
+        after: string | null;
+    }): Promise<{
+        items: Node[];
+        nextCursor: string | null;
+    }>;
     listVersions(actor: Actor, nodeId: string): Promise<{
         items: NodeVersion[];
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.37.1",
+  "version": "0.39.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,8 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.25.0",
-    "@anchrd/intel-contract": "^0.29.0",
+    "@anchrd/gate-sdk": "^0.26.0",
+    "@anchrd/intel-contract": "^0.31.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",