@anchrd/intel-api 0.12.1 → 0.12.3

package/dist/adapters/db/db-indexing.js

@@ -40,7 +40,18 @@ export function createNodeIndexRepository(db) {
                 .all();
             return mapTarget(row, (segments.results ?? []).map((segment) => segment.content_key));
         },
-        async replace(target, content) {
+        /**
+         * Every passage of this node, replacing every passage it had.
+         *
+         * ⚠️ One row per chunk, in ONE batch with the delete in front of it. Most kinds bring exactly
+         * one chunk and this is the statement pair it always was; a board brings one per task (#285),
+         * and a search can then answer with the card that matched rather than with the whole board.
+         *
+         * ⚠️ A board with no tasks writes no row at all, and that is right: there is nothing to find in
+         * it. What must not happen is the delete landing without the inserts, which is why they share a
+         * batch — D1 runs it as one transaction.
+         */
+        async replace(target, chunks) {
             await db.batch([
                 db
                     .prepare(`DELETE FROM node_fts WHERE node_id = ? AND EXISTS (
@@ -48,13 +59,13 @@ export function createNodeIndexRepository(db) {
             WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
           )`)
                     .bind(target.nodeId, target.nodeId, target.versionId),
-                db
+                ...chunks.map((chunk) => db
                     .prepare(`INSERT INTO node_fts (version_id, node_id, title, content)
-            SELECT ?, ?, ?, ? WHERE EXISTS (
-              SELECT 1 FROM nodes
-              WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
-            )`)
-                    .bind(target.versionId, target.nodeId, target.title, content, target.nodeId, target.versionId),
+              SELECT ?, ?, ?, ? WHERE EXISTS (
+                SELECT 1 FROM nodes
+                WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+              )`)
+                    .bind(target.versionId, target.nodeId, chunk.title, chunk.text, target.nodeId, target.versionId)),
             ]);
         },
         async markIndexed(versionId, occurredAt) {

package/dist/adapters/db/db.js

@@ -5,6 +5,18 @@ const grantColumns = `id, node_id, principal_type, principal_id, verb, expires_a
   created_by, created_at`;
 const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
   link.origin, link.label, link.created_by, link.created_at`;
+// The first row of each node, in the order they arrive. A chunked kind — a board, whose index holds
+// one row per task (#285) — answers a query once per matching card; a citation names a node, so the
+// best of them is the one that gets to speak for it.
+function dedupedByNode(rows) {
+    const seen = new Set();
+    return rows.filter((row) => {
+        if (seen.has(row.node_id))
+            return false;
+        seen.add(row.node_id);
+        return true;
+    });
+}
 const nodeColumns = `n.id, n.parent_id, n.kind, n.title, n.description,
   n.owner_id, n.current_version_id, n.created_at, n.updated_at, n.archived_at`;
 function mapNode(row) {
@@ -363,6 +375,32 @@ export function createNodeRepository(deps) {
                 throw error;
             }
         },
+        /**
+         * What an earlier write with this key recorded about itself (#285).
+         *
+         * ⚠️ The idempotency row points at the VERSION, and the audit event points at the node, so the
+         * two are joined through the version id the snapshot writer puts into the metadata. That
+         * metadata is where a board operation says which task it touched and how many it removed —
+         * facts a replay cannot recompute from the stored document, because the document is the state
+         * AFTER the write. Without this, repeating a delete would answer with a count nobody measured.
+         */
+        async findSnapshotMetadata(actorId, operation, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT audit.metadata_json AS metadata_json
+          FROM idempotency_keys keys
+          JOIN audit_events audit
+            ON audit.action = keys.operation
+            AND json_extract(audit.metadata_json, '$.versionId') = keys.resource_id
+          WHERE keys.actor_id = ? AND keys.operation = ? AND keys.idempotency_key = ?`)
+                .bind(actorId, operation, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            const parsed = JSON.parse(row.metadata_json);
+            return typeof parsed === "object" && parsed !== null
+                ? parsed
+                : null;
+        },
         async findImportReplay(actorId, idempotencyKey) {
             const row = await deps.db
                 .prepare(`SELECT audit.metadata_json AS metadata_json
@@ -777,7 +815,8 @@ export function createNodeRepository(deps) {
             return mapVersion(row);
         },
         /**
-         * One snapshot of a table, written only against the state it replaces (#135).
+         * One snapshot — the whole readable state after a mutation — written only against the state it
+         * replaces (#135, #285).
          *
          * ⚠️ The shape of `appendVersion`, not of the append above it: the base check sits inside the
          * INSERT's own WHERE, so a segment that landed between the service's read and this batch makes
@@ -787,17 +826,23 @@ export function createNodeRepository(deps) {
          * The idempotency row carries the mutation's own operation, so a replayed update can never be
          * confused with a delete that reused the key, and the audit trail names what was done.
          */
-        async appendTableSnapshot(input) {
+        async appendSnapshotVersion(input) {
             const version = input.version;
             await deps.db.batch([
                 deps.db
                     .prepare(`INSERT INTO node_versions (
             id, node_id, sequence, content_key, media_type, content_hash, size, segment,
             created_by, created_at
-          ) SELECT ?, ?, ?, ?, ?, ?, ?, 'snapshot', ?, ?
+          ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
           FROM nodes
           WHERE id = ? AND current_version_id IS ?`)
-                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
+                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, 
+                // ⚠️ Taken from the version rather than written in as `'snapshot'`. A table's mutation
+                // marks a snapshot, because reading a table starts at the newest one and everything
+                // before it is history (#135). A board's version carries the whole board by
+                // construction, so it marks nothing — the same `null` a document's version carries, and
+                // for the same reason (#285).
+                version.segment, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
                 deps.db
                     .prepare(`UPDATE nodes
             SET current_version_id = ?, updated_at = ?
@@ -1083,7 +1128,12 @@ export function createNodeRepository(deps) {
           LIMIT ?`)
                 .bind(...readBindings(actor), ...scopeBindings(input.scopeId), query, input.limit)
                 .all();
-            return (result.results ?? []).map((row) => ({
+            // ⚠️ One citation per node, and the FIRST is the one kept. A board holds one index row per
+            // task (#285), so a query matching three cards of the same board arrives here three times;
+            // the rows come back in rank order, so the survivor is the best-matching card and its own
+            // passage is what the reader is shown. Without this, one busy board could fill a whole page
+            // of results and push every other node off it.
+            return dedupedByNode(result.results ?? []).map((row) => ({
                 nodeId: row.node_id,
                 versionId: row.version_id,
                 title: row.title,
@@ -1117,8 +1167,12 @@ export function createNodeRepository(deps) {
                 rows.push(...(result.results ?? []));
             }
             const order = new Map(uniqueIds.map((id, index) => [id, index]));
-            rows.sort((left, right) => (order.get(left.node_id) ?? 0) - (order.get(right.node_id) ?? 0));
-            return rows.map((row) => ({
+            // The same one-per-node rule as the lexical half above, for the same reason: a semantic hit
+            // is a hit on a NODE (the vector index is keyed by node id), so hydrating it must not turn one
+            // hit into one row per task.
+            const deduped = dedupedByNode(rows);
+            deduped.sort((left, right) => (order.get(left.node_id) ?? 0) - (order.get(right.node_id) ?? 0));
+            return deduped.map((row) => ({
                 nodeId: row.node_id,
                 versionId: row.version_id,
                 title: row.title,

package/dist/adapters/openid/openid.js

@@ -24,8 +24,45 @@ function metadataCandidates(resourceUrl, challenge) {
 function resourceMetadataChallenge(header) {
     return header?.match(/resource_metadata="([^"]+)"/i)?.[1] ?? null;
 }
-function isCloudflareAccess(issuer) {
-    return new URL(issuer).hostname.endsWith(".cloudflareaccess.com");
+const AuthorizationServerMetadata = z.looseObject({
+    scopes_supported: z.array(z.string()).nullish(),
+});
+/**
+ * The scopes this authorization server says it understands, or `null` when it names none.
+ *
+ * ⚠️ `null` is not "no scopes" — RFC 8414 makes `scopes_supported` OPTIONAL, and Cloudflare Access
+ * omits it. It means "this server never said", and the only safe reading of that is to ask for
+ * nothing: a scope the server does not know is at best ignored and at worst turns the whole
+ * authorization down, and neither failure names the scope as its cause.
+ *
+ * This replaces a hostname check (`issuer.endsWith(".cloudflareaccess.com")`) that decided the same
+ * question by guessing who the server was. A Cloudflare Access portal on its own domain — the
+ * normal case for anyone who cares what their portal is called — was read as some other vendor, and
+ * Intel then asked it for `offline_access`, a scope it never published (#97).
+ */
+async function publishedScopes(fetcher, issuer) {
+    const url = new URL(issuer);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+    const response = await fetcher(`${url.origin}/.well-known/oauth-authorization-server${path}`, {
+        signal: AbortSignal.timeout(RequestTimeoutMs),
+        headers: { accept: "application/json" },
+    }).catch(() => null);
+    if (!response?.ok)
+        return null;
+    const metadata = AuthorizationServerMetadata.safeParse(await response.json().catch(() => null));
+    return metadata.success ? (metadata.data.scopes_supported ?? null) : null;
+}
+/**
+ * Of the scopes Intel would like, the ones this server published — joined, or absent.
+ *
+ * `offline_access` is the one that matters: it is where a refresh token comes from on a server that
+ * gates it behind a scope. Asking for it unconditionally is what a hostname check amounted to.
+ */
+function requestableScope(published) {
+    if (!published)
+        return undefined;
+    const wanted = ["openid", "profile", "email", "offline_access"].filter((scope) => published.includes(scope));
+    return wanted.length > 0 ? wanted.join(" ") : undefined;
 }
 function tokenResponse(tokens) {
     return {
@@ -122,10 +159,11 @@ export function createOpenId(deps) {
                     continue;
                 const issuer = metadata.data.authorization_servers[0];
                 if (issuer) {
+                    const scope = requestableScope(await publishedScopes(deps.fetch, issuer));
                     return {
                         resource: metadata.data.resource,
                         issuer,
-                        ...(isCloudflareAccess(issuer) ? {} : { scope: "openid profile email offline_access" }),
+                        ...(scope ? { scope } : {}),
                     };
                 }
             }
@@ -142,11 +180,17 @@ export function createOpenId(deps) {
                 // not survive its first access token (#97): `offline_access` was being requested and
                 // the right to act on it never was.
                 grant_types: ["authorization_code", "refresh_token"],
-                ...(isCloudflareAccess(input.issuer)
-                    ? {}
-                    : { scope: "openid profile email offline_access" }),
+                ...(input.scope ? { scope: input.scope } : {}),
                 token_endpoint_auth_method: "none",
-                ...(isCloudflareAccess(input.issuer) ? { resource: input.resource } : {}),
+                // ⚠️ Unconditional, and that is the protocol rather than a vendor accommodation. The
+                // MCP authorization spec: "MCP clients MUST send this parameter regardless of whether
+                // authorization servers support it" (RFC 8707 Resource Indicators). Sending it only to
+                // hosts whose name ended in `.cloudflareaccess.com` meant every portal on its own
+                // domain registered as a client that never named the resource it wanted a token for —
+                // and Cloudflare's Managed OAuth requires exactly that conformance before it will hand
+                // out a refresh token. The connection then died at the first token expiry, and the log
+                // said "no refresh token was ever issued" (#97).
+                resource: input.resource,
             }, client.None(), { ...options(input.issuer), ...(algorithm ? { algorithm } : {}) }));
             return configuration.clientMetadata().client_id;
         },

package/dist/auth/auth.js

@@ -60,8 +60,15 @@ export function createBrowserAuth(deps) {
     const gateIssuer = deps.gateUrl.replace(/\/+$/, "");
     const redirectUri = `${baseUrl}/auth/callback`;
     const secure = new URL(baseUrl).protocol === "https:";
-    async function clientId(issuer, resource) {
-        const registrationKey = `${issuer}#${resource}`;
+    async function clientId(issuer, resource, scope) {
+        // ⚠️ The suffix is a registration generation, and it is what makes a fix to the registration
+        // reach an installation that already has one. A stored client is reused forever, so #97 —
+        // clients registered without the `resource` parameter and therefore never given a refresh
+        // token — would have been repaired in code and nowhere else: every existing deployment would
+        // keep handing back the broken registration it made months ago. Raise this whenever the
+        // REGISTRATION changes shape, never for anything else; each raise costs one silent
+        // re-registration per issuer and resource.
+        const registrationKey = `${issuer}#${resource}#r2`;
         const stored = await deps.clients.get(registrationKey, redirectUri);
         if (stored)
             return stored;
@@ -74,6 +81,7 @@ export function createBrowserAuth(deps) {
             redirectUri,
             clientName: "Intel",
             resource,
+            ...(scope ? { scope } : {}),
         })
             .catch((error) => {
             reportUnexpectedError(error);
@@ -148,7 +156,7 @@ export function createBrowserAuth(deps) {
             const discovered = await deps.oauth.discoverResource(deps.portalUrl).catch(() => {
                 throw new IntelError(409, "portal_oauth_unavailable", "The MCP portal does not publish usable OAuth metadata");
             });
-            const connectionClientId = await clientId(discovered.issuer, discovered.resource);
+            const connectionClientId = await clientId(discovered.issuer, discovered.resource, discovered.scope);
             const { verifier: codeVerifier, challenge: codeChallenge } = await pkce();
             const state = randomState();
             const pending = {

package/dist/auth/auth.types.d.ts

@@ -15,6 +15,7 @@ export interface OAuthPort {
         redirectUri: string;
         clientName: string;
         resource: string;
+        scope?: string;
     }): Promise<string>;
     authorizationUrl(input: {
         issuer: string;

package/dist/bundle/bundle.js

@@ -1,4 +1,4 @@
-import { AgentDefinition, AgentMediaType, BlockNoteMediaType, BundleImportResult, BundleManifest, BundleManifestFilename, DocumentLinkInlineType, FlowGraph, TableMediaType, } from "@anchrd/intel-contract";
+import { AgentDefinition, AgentMediaType, BlockNoteMediaType, BoardDocument, BoardMediaType, BundleImportResult, BundleManifest, BundleManifestFilename, DocumentLinkInlineType, FlowGraph, TableMediaType, } from "@anchrd/intel-contract";
 import { Unzip, UnzipInflate, Zip, ZipDeflate, ZipPassThrough } from "fflate";
 import { documentLinkTargets } from "../nodes/document-links/document-links.js";
 import { parseCsv } from "../shared/csv/csv.js";
@@ -216,6 +216,13 @@ function nakedKindOf(name) {
     if (lower.endsWith(".csv")) {
         return { kind: "table", mediaType: TableMediaType, title: name.slice(0, -4) };
     }
+    // ⚠️ Before any plain `.json` rule and with a compound suffix on purpose (#285). A board is not
+    // recognisable from `.json` alone — an agent definition wears the same extension — so the export
+    // writes `.board.json` and a naked upload has to spell it out too. A file that only says `.json`
+    // is an attachment, which is what it was before boards existed.
+    if (lower.endsWith(".board.json")) {
+        return { kind: "board", mediaType: BoardMediaType, title: name.slice(0, -11) };
+    }
     return { kind: "attachment", mediaType: guessedMediaType(lower), title: name };
 }
 const KnownMediaTypes = {
@@ -394,6 +401,25 @@ export function createBundle(deps) {
                 },
             };
         }
+        // A board is one JSON file, exactly like an agent's definition: the document IS the board, so
+        // there is nothing to serialize differently for an export (#285). A board with no version yet
+        // exports as an empty file, the same way an agent without a definition does.
+        if (node.kind === "board") {
+            const path = `${directory}${uniqueName(used, base, ".board.json")}`;
+            return {
+                manifest: {
+                    id: node.id,
+                    kind: "board",
+                    title: node.title,
+                    description: node.description,
+                    mediaType: version?.mediaType ?? BoardMediaType,
+                    path,
+                },
+                content: version === null
+                    ? { type: "text", load: async () => "" }
+                    : { type: "text", load: textLoader(version.contentKey) },
+            };
+        }
         if (node.kind === "agent") {
             const path = `${directory}${uniqueName(used, base, ".json")}`;
             return {
@@ -904,6 +930,35 @@ export function createBundle(deps) {
                         version = versionRowFor(entry, text, TableMediaType, await deps.hash(text), "snapshot");
                     }
                 }
+                else if (entry.kind === "board") {
+                    const text = entry.body === null ? "" : decodeText(entry.body, entry.path);
+                    if (text.trim().length > 0) {
+                        let document;
+                        try {
+                            document = BoardDocument.parse(JSON.parse(text));
+                        }
+                        catch {
+                            throw new IntelError(400, "import_invalid_board", `Bundle entry is not a board: ${entry.path}`);
+                        }
+                        // ⚠️ `references` are remapped the way a document's inline links are, and `dependsOn`
+                        // and `parentId` are NOT (#285). A task's references point at NODES, which the import
+                        // renumbers; its dependencies and its parent point at tasks inside this very file,
+                        // whose ids the import does not touch. Renumbering those would break every edge in the
+                        // board for no reason.
+                        const remapped = {
+                            statuses: document.statuses,
+                            tasks: document.tasks.map((task) => ({
+                                ...task,
+                                references: task.references.map((reference) => idMap.get(reference) ?? reference),
+                            })),
+                        };
+                        const body = JSON.stringify(remapped);
+                        version = versionRowFor(entry, body, BoardMediaType, await deps.hash(body), null);
+                        // Into the same link pass as an imported document: a board's references are `text`
+                        // links, so they have to survive the import the same way.
+                        documentBodies.set(entry.newId, { mediaType: BoardMediaType, content: body });
+                    }
+                }
                 else if (entry.kind === "agent") {
                     const text = entry.body === null ? "" : decodeText(entry.body, entry.path);
                     if (text.trim().length > 0) {
@@ -952,7 +1007,7 @@ export function createBundle(deps) {
                 nodes.push({
                     id: entry.newId,
                     parentId,
-                    // Flows took the `continue` above; what reaches here is one of the five node kinds.
+                    // Flows took the `continue` above; what reaches here is one of the six node kinds.
                     kind: entry.kind,
                     // A manifest title and a file name are both somebody else's text, and an export written
                     // by an escaping chain carries the entity in both (#202).

package/dist/http/http.js

@@ -1,4 +1,4 @@
-import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListNodesInput, NodeGraphInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
+import { AddBoardTaskInput, AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, ConfigureBoardInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteTableRowsInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListNodesInput, MoveBoardTaskInput, NodeGraphInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateBoardTaskInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
@@ -438,6 +438,54 @@ export function createHttp(deps) {
         }
         return context.json(await deps.nodes.redefineTable(asActor(auth), input), 201);
     });
+    // The board (#285). One read and five task operations, all action-style POSTs for the same reason
+    // the table mutations are: what they address is a task ID in the body, and none of them has an
+    // address of its own to PUT to. Every one writes a version, so they all answer 201 like the
+    // table's do.
+    app.get("/nodes/:nodeId/board", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.nodes.getBoard(asActor(auth), { nodeId: context.req.param("nodeId") }));
+    });
+    app.post("/nodes/:nodeId/board/configure", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = ConfigureBoardInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.configureBoard(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/board/tasks", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = AddBoardTaskInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.addBoardTask(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/board/tasks/update", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = UpdateBoardTaskInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.updateBoardTask(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/board/tasks/move", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = MoveBoardTaskInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.moveBoardTask(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/board/tasks/delete", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = DeleteBoardTaskInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.deleteBoardTask(asActor(auth), input), 201);
+    });
     app.get("/nodes/:nodeId/links", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         return context.json(await deps.nodes.listLinks(asActor(auth), context.req.param("nodeId")));

package/dist/indexing/indexing.js

@@ -1,4 +1,4 @@
-import { BlockNoteDocument, BlockNoteMediaType } from "@anchrd/intel-contract";
+import { BlockNoteDocument, BlockNoteMediaType, BoardDocument } from "@anchrd/intel-contract";
 export class PermanentIndexingError extends Error {
 }
 function indexText(mediaType, content) {
@@ -13,6 +13,35 @@ function indexText(mediaType, content) {
         throw new PermanentIndexingError(`Node version content is not a valid BlockNote document: ${error instanceof Error ? error.message : "unknown parse failure"}`);
     }
 }
+/**
+ * One passage per task, never one per board (#285).
+ *
+ * ⚠️ This is the whole reason a board is chunked at all. "Where do I stand with X" has to land on a
+ * CARD: indexed as one blob, a board of three hundred tasks matches on any of them and answers with
+ * whichever thousand characters the snippet function happened to cut — text from a task that may
+ * have nothing to do with the question. Each chunk carries the task's own title, which is the
+ * column the FTS table weights highest.
+ *
+ * ⚠️ The status list is not indexed. "Backlog" and "Done" appear on every board in the
+ * installation, so they are the words most likely to match and the least likely to mean anything.
+ */
+function boardChunks(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new PermanentIndexingError(`Node version content is not valid JSON: ${error instanceof Error ? error.message : "unknown parse failure"}`);
+    }
+    const board = BoardDocument.safeParse(parsed);
+    if (!board.success) {
+        throw new PermanentIndexingError("Node version content is not a valid board document");
+    }
+    return board.data.tasks.map((task) => ({
+        title: task.title,
+        text: [task.title, ...task.labels, task.description].filter(Boolean).join("\n\n"),
+    }));
+}
 async function readCanonical(deps, target) {
     if (target.kind === "attachment") {
         const key = target.contentKeys[0];
@@ -36,7 +65,9 @@ export function createIndexing(deps) {
             // the tree being asked. What makes an agent findable is what a person wrote about it, so the
             // text is its description, and the FTS table indexes the title on its own (#139).
             if (target.kind === "agent") {
-                await deps.repository.replace(target, target.description ?? "");
+                await deps.repository.replace(target, [
+                    { title: target.title, text: target.description ?? "" },
+                ]);
                 await deps.semantic?.replace(target, target.description ?? "");
                 await deps.repository.markIndexed(versionId, deps.now().toISOString());
                 return;
@@ -58,7 +89,11 @@ export function createIndexing(deps) {
                 if (text === undefined) {
                     throw new PermanentIndexingError(`No document converter is configured for ${target.mediaType}`);
                 }
-                await deps.repository.replace(target, text);
+                // ⚠️ The semantic index stays per NODE while the lexical one gains a row per task. Vectorize
+                // is keyed by node id (`semantic-index.ts`), so a board would need its own key space there
+                // before it could carry one vector per card — a bigger change than #285, and one nothing
+                // asks for yet: the lexical half is what "find the card" needs today.
+                await deps.repository.replace(target, target.kind === "board" ? boardChunks(text) : [{ title: target.title, text }]);
                 await deps.semantic?.replace(target, text);
                 await deps.repository.markIndexed(versionId, deps.now().toISOString());
             }

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, 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, 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";
@@ -252,6 +252,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getTable(actor, input.nodeId)));
+        // A board answers whole: the statuses and every task, in one read. There is no per-task read
+        // beside it, because a card is small and the interesting question is almost always about
+        // several of them at once — what is in review, what waits for what (#285).
+        server.registerTool("board_get", {
+            title: "Get board",
+            description: "Read one authorized board: its status list and every task with its full field set. A board that has never been written answers with the default statuses and no tasks.",
+            inputSchema: GetBoardInput,
+            annotations: {
+                title: "Get board",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.getBoard(actor, input)));
         registerWithAlias(server, { name: "node_links_list", deprecated: "knowledge_links_list" }, {
             title: "List node links",
             description: "List authorized outgoing links and backlinks for one node.",
@@ -513,6 +528,79 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.redefineTable(actor, input)));
+        /**
+         * The board's write surface (#285). No `knowledge_*` alias on any of them — these are new under
+         * the post-#125 naming.
+         *
+         * ⚠️ Not one of them takes a `baseVersionId`, and the descriptions say so. That is the property
+         * an agent has to be able to rely on: two agents working the same board at the same time touch
+         * different tasks, and neither is asked to read the whole board first or to retry a conflict
+         * that says nothing about what they were doing. The server applies each call by task id to the
+         * board as it stands at that moment.
+         */
+        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.',
+            inputSchema: ConfigureBoardInput,
+            annotations: {
+                title: "Configure board statuses",
+                readOnlyHint: false,
+                // Removing a column is possible here, so this is not a purely additive write.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, 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.",
+            inputSchema: AddBoardTaskInput,
+            annotations: {
+                title: "Add board task",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, 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.",
+            inputSchema: UpdateBoardTaskInput,
+            annotations: {
+                title: "Update board task",
+                readOnlyHint: false,
+                // Every named field replaces what stood there; the version history keeps it, the task
+                // does not.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.updateBoardTask(actor, input)));
+        server.registerTool("board_task_move", {
+            title: "Move board task",
+            description: 'Move one task: into another status, under another parent, or between two neighbours. Archiving a task is this call with status "archived" — there is no separate verb, and nothing is deleted by it. Two moves on two different tasks both go through.',
+            inputSchema: MoveBoardTaskInput,
+            annotations: {
+                title: "Move board task",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.moveBoardTask(actor, input)));
+        server.registerTool("board_task_delete", {
+            title: "Delete board task",
+            description: 'Remove a task AND every subtask under it, recursively. The answer counts everything that went, and dependsOn entries in the remaining tasks that pointed at a deleted one are removed with it. To take a task off the board without losing it, move it to the "archived" status instead.',
+            inputSchema: DeleteBoardTaskInput,
+            annotations: {
+                title: "Delete board task",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.deleteBoardTask(actor, input)));
         registerWithAlias(server, { name: "node_update", deprecated: "knowledge_update" }, {
             title: "Update node",
             description: "Rename, move, or describe a node.",

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

@@ -0,0 +1,15 @@
+import type { BoardDeps, BoardOperations } from "./board.types.js";
+/**
+ * Every board operation, applied to the document rather than to the file (#285).
+ *
+ * ⚠️ This module is where a board's rules live, and it is deliberately pure: it takes a document
+ * and gives back the next one. The version, R2 and the retry against a racing write are the
+ * service's business (`nodes.ts`), and the surfaces have no rules of their own — HTTP, MCP and the
+ * UI all arrive here. A second implementation of "may this task depend on that one" is the thing
+ * this shape exists to prevent.
+ *
+ * ⚠️ What it does NOT check is anything that needs the tree: whether a `references` id names a node
+ * the writer may see, and whether an `agent` assignee is really an agent. Those are reads against
+ * D1 and the ACL, so they happen in the service before the document is touched at all.
+ */
+export declare function createBoard(deps: BoardDeps): BoardOperations;