@anchrd/intel-api 0.39.0 → 0.41.0

package/dist/mcp/mcp.js

@@ -10,6 +10,7 @@ import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableI
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { GetPromptRequestSchema, ListPromptsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { permits } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
@@ -158,15 +159,46 @@ export async function handleMcp(request, deps) {
         email: deps.authorization.identity.email,
         name: deps.authorization.identity.name ?? null,
     }));
+    // The change journal, read forward from a stable position (#620). It is what makes Intel the
+    // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
+    // and Intel never learns that the consumer exists. That is the D24 test passed rather than
+    // argued — remove every reader and nothing piles up here.
+    //
+    // ⚠️ **The capability follows the KIND asked for** (#774), which is why this tool stands outside
+    // both capability blocks rather than inside one. An audit row says the same thing its resource
+    // says, so the journal asks what reading that resource asks — `nodes/read` for `node`,
+    // `flows/read` for `flow` and `flow-run`. A capability of its own would be a second answer to one
+    // question and the two would drift; `nodes/read` for all three would drop the first of the three
+    // checks for exactly the two kinds #774 opened.
+    //
+    // ⚠️ **Offered on EITHER capability, decided per call.** Registration is per connection and the
+    // kind arrives per call, so the two cannot be the same gate. Holding one of the two is what makes
+    // the tool worth listing at all; which of the three journals it then answers is the handler's
+    // question. Same shape, same order, same refusal as `GET /audit` — one business layer, three thin
+    // surfaces.
+    if (permits(deps.authorization, "nodes", "read") ||
+        permits(deps.authorization, "flows", "read")) {
+        server.registerTool("audit_list", {
+            title: "List change events",
+            description: "Read the change journal forward from a stable position: what happened to the resources you may read, oldest first. `resourceType` picks which of the three journals to read — `node`, `flow` or `flow-run` — and each has its own cursor; do not carry one over to another. Pass `nextCursor` back as `after` to continue where you stopped — it says WHERE YOU GOT TO and comes back on the last page as well. Whether another page may follow is `hasMore`; a null `nextCursor` means nothing was returned, not that you have caught up. Events about permanently deleted nodes and flows are never returned, to anybody.",
+            inputSchema: AuditListRequest,
+            annotations: {
+                title: "List change events",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => {
+            // ⚠️ Before the service, so a refusal costs no journal read. A 403 that arrived after the
+            // rows were read is a 403 that already read them.
+            if (!permits(deps.authorization, input.resourceType === "node" ? "nodes" : "flows", "read")) {
+                throw new IntelError(403, "permission_required", "Permission required");
+            }
+            return text(await deps.audit.list(actor, input));
+        });
+    }
     if (permits(deps.authorization, "nodes", "read")) {
-        // The change journal, read forward from a stable position (#620). It is what makes Intel the
-        // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
-        // and Intel never learns that the consumer exists. That is the D24 test passed rather than
-        // argued — remove every reader and nothing piles up here.
-        //
-        // ⚠️ `nodes/read`, not a capability of its own. An audit row about a node says the same thing
-        // the node says; a second capability would be a second answer to one question, and the two
-        // would drift.
         // The board as one answer (#648). Four tools, not five: a move is an update of `status` and
         // `position`, and deleting a task is `node_archive` — nothing here removes a `nodes` row.
         server.registerTool("board_get", {
@@ -252,18 +284,6 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.boards.update(actor, input)));
-        server.registerTool("audit_list", {
-            title: "List change events",
-            description: "Read the change journal forward from a stable position: what happened to the nodes you may read, oldest first. Pass `nextCursor` back as `after` to continue where you stopped; a null `nextCursor` means you have caught up. Only node events can be listed — flow events need their own visibility check and are refused rather than left out. Events about permanently deleted nodes are never returned, to anybody.",
-            inputSchema: AuditListRequest,
-            annotations: {
-                title: "List change events",
-                readOnlyHint: true,
-                destructiveHint: false,
-                idempotentHint: true,
-                openWorldHint: false,
-            },
-        }, async (input) => text(await deps.audit.list(actor, input)));
         server.registerTool("feed_list", {
             title: "List recent activity",
             description: "Read the change journal backwards: what most recently happened to the nodes you may read, newest first, one entry per event. Each entry carries the node's current title and the folders above it, and only the folders you may open. Pass `nextCursor` back as `before` to keep going further into the past; a null `nextCursor` means you have reached the beginning. Pass `actor` to see one person's or one agent's work alone. This is the human-facing view — for catching up on everything in order, use audit_list, and do not mix the two cursors.",
@@ -929,7 +949,7 @@ export async function handleMcp(request, deps) {
         // whoever started it, and only their own runs are the calling user's to read out that way.
         server.registerTool("flow_run_list", {
             title: "List flow runs",
-            description: "List the runs of one flow, newest first, with status, start, duration, what triggered them, and for a failed run the step that ended it. Optionally only the failed ones. Runs the calling user may not see are absent, and a failure inside a called flow they may not see is named by the calling step alone.",
+            description: 'List flow runs, newest first, with status, start, duration, what triggered them, and for a failed run the step that ended it. Name a `flowId` for one flow, or leave it out for the runs of every flow you may read — which is the way to answer "did anything run at all" without knowing a flow first. Optionally only the failed ones. Runs the calling user may not see are absent, and a failure inside a called flow they may not see is named by the calling step alone.',
             inputSchema: ListFlowRunsInput,
             annotations: {
                 title: "List flow runs",
@@ -1217,6 +1237,55 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.tools.execute(toolActor, input)));
     }
+    /**
+     * The slash-command surface (#775). A prompt is the one thing on this server the HUMAN chooses:
+     * a tool is called when the model thinks of it, a prompt when somebody types `/name`.
+     *
+     * ⚠️ **Registered through the low-level handlers rather than `registerPrompt`, and the cost is
+     * the reason.** `registerPrompt` takes one name at a time, so a catalogue that lives in D1 would
+     * have to be read and registered while the server is being built — on EVERY request, including
+     * every `tools/call` that will never look at a prompt. These two handlers run the queries only
+     * when a client actually asks for prompts.
+     *
+     * ⚠️ **The capability is declared here because nothing else declares it.** Without
+     * `registerCapabilities` the SDK would answer `prompts/list` while telling clients during
+     * initialization that this server has no prompts, and a client that believes the handshake never
+     * asks. `listChanged: false` is the truthful value: the catalogue changes when somebody edits a
+     * document, and this server sends no notification about it.
+     *
+     * ⚠️ **Offered on EITHER capability, decided per call** — the shape `audit_list` uses one screen
+     * up, for the same reason. Holding one of the two is what makes the surface worth offering at
+     * all; which half of the catalogue it then answers is `listOffered`'s question, and it asks it
+     * per row against the resource ACL underneath.
+     */
+    if (permits(deps.authorization, "nodes", "read") ||
+        permits(deps.authorization, "flows", "read")) {
+        const promptActor = {
+            ...actor,
+            canReadNodes: permits(deps.authorization, "nodes", "read"),
+            canReadFlows: permits(deps.authorization, "flows", "read"),
+        };
+        server.server.registerCapabilities({ prompts: { listChanged: false } });
+        server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: (await deps.prompts.list(promptActor)).map((entry) => ({
+                name: entry.name,
+                title: entry.title,
+                // ⚠️ No `arguments`, and that is a decision rather than a gap (#775). A prompt without
+                // arguments is completely usable — it is an instruction somebody wrote down — and the
+                // obvious source of an argument schema, a flow's requirements, is a round of its own.
+                // Declaring an empty `arguments` array would tell a client the question was asked and
+                // answered "none", which is a different claim.
+                ...(entry.description === null ? {} : { description: entry.description }),
+            })),
+        }));
+        server.server.setRequestHandler(GetPromptRequestSchema, async (promptRequest) => {
+            const { entry, text } = await deps.prompts.get(promptActor, promptRequest.params.name);
+            return {
+                ...(entry.description === null ? {} : { description: entry.description }),
+                messages: [{ role: "user", content: { type: "text", text } }],
+            };
+        });
+    }
     const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
     await server.connect(transport);
     return await transport.handleRequest(request);

package/dist/mcp/mcp.types.d.ts

@@ -5,6 +5,7 @@ import type { BundleService } from "../bundle/bundle.types.js";
 import type { FeedService } from "../feed/feed.types.js";
 import type { FlowService } from "../flows/flows.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
+import type { Prompts } from "../prompts/prompts.types.js";
 import type { ToolService } from "../tools/tools.types.js";
 export interface McpDeps {
     authorization: Authorized;
@@ -20,4 +21,5 @@ export interface McpDeps {
     audit: AuditService;
     feed: FeedService;
     boards: BoardService;
+    prompts: Prompts;
 }

package/dist/nodes/nodes.js

@@ -637,6 +637,11 @@ export function createNodes(deps) {
             const timestamp = deps.now().toISOString();
             const created = await deps.repository.insertNode({
                 node: {
+                    // ⚠️ A node is never born offered (#775). Naming a slash command is a curation decision
+                    // about a document that already exists, and `node_create` takes no name: a creation that
+                    // could also take the last free name in the catalogue would fail for a reason that has
+                    // nothing to do with creating anything.
+                    promptName: null,
                     id: deps.id(),
                     parentId: input.parentId,
                     kind: input.kind,
@@ -997,6 +1002,22 @@ export function createNodes(deps) {
             if (!(await deps.repository.can(actor, current.id, "write"))) {
                 throw new IntelError(403, "node_forbidden", "This node cannot be edited");
             }
+            /**
+             * ⚠️ **Only a document can be offered as a slash command, and the refusal names the kind**
+             * (#775). A prompt is an instruction; a folder, a table, an attachment, a board or a task is
+             * material, and material is read through `node_get` rather than typed as a command.
+             *
+             * ⚠️ It stands BEFORE the idempotency replay on purpose: a call that is wrong about the kind
+             * is wrong on every attempt, and answering the second one out of the replay table would tell
+             * a caller their refused write had succeeded.
+             *
+             * ⚠️ Clearing it — `null` on a kind that could never have had one — is deliberately allowed.
+             * It changes nothing, and refusing a no-op would make "take the command off everything in
+             * this folder" a call that fails on the folder itself.
+             */
+            if (input.promptName != null && current.kind !== "document") {
+                throw new IntelError(409, "prompt_not_a_document", `Only a document can be offered as a slash command, and this is a ${current.kind}.`);
+            }
             const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.update", input.idempotencyKey);
             if (replayedId)
                 return await requireVisible(actor, replayedId);
@@ -1045,6 +1066,7 @@ export function createNodes(deps) {
                     parentId: input.parentId === undefined ? current.parentId : input.parentId,
                     title: input.title === undefined ? current.title : plainTitle(input.title),
                     description: input.description === undefined ? current.description : input.description,
+                    promptName: input.promptName === undefined ? current.promptName : input.promptName,
                     updatedAt,
                 },
                 baseUpdatedAt: input.baseUpdatedAt,
@@ -1055,6 +1077,22 @@ export function createNodes(deps) {
             if (updated === "cycle") {
                 throw new IntelError(409, "move_cycle", "A node cannot be moved into its descendant");
             }
+            if (updated === "prompt_name_taken") {
+                /**
+                 * ⚠️ **The sentence names the holder only when this actor may see it.** That a name is
+                 * taken has to be said — otherwise the caller retries forever against a wall they cannot
+                 * see — but WHICH document holds it is a fact about the tree, and ADR-0004 §3 does not let
+                 * a refusal become a way of reading it. `promptNameHolder` answers `null` for the title in
+                 * that case, and the second sentence below is what the caller gets instead.
+                 */
+                const holder = await deps.repository.promptNameHolder(actor, input.promptName);
+                const held = holder === null
+                    ? "It is already taken."
+                    : holder.title === null
+                        ? `A ${holder.kind} you cannot see already uses it.`
+                        : `The ${holder.kind} "${holder.title}" already uses it.`;
+                throw new IntelError(409, "prompt_name_taken", `The slash command "${input.promptName}" is not free. ${held} Pick another name — names are never changed for you, because the catalogue would then mean a different thing to every reader.`);
+            }
             if (updated === "conflict") {
                 throw new IntelError(409, "update_conflict", "This node was changed by another editor");
             }

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

@@ -3,6 +3,7 @@ import type { ArchiveNodeInput, CreateNodeInput, ListNodesInput, Node, NodeAttac
 import type { ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, ShareInput, ShareResult } from "@anchrd/intel-contract/share";
 import type { AppendTableRowsInput, AppendTableRowsResult, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, RedefineTableInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract/table";
 import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+import type { PromptNameHolder } from "../prompts/prompts.types.js";
 export interface Actor {
     id: string;
     email: string;
@@ -78,7 +79,13 @@ export interface NodeRepository {
         actorId: string;
         idempotencyKey: string;
         auditId: string;
-    }): Promise<"cycle" | "conflict" | Node>;
+    }): Promise<"cycle" | "conflict" | "prompt_name_taken" | Node>;
+    /**
+     * Who holds a slash command name, for the sentence a refused rename gets (#775). `title` is
+     * `null` when the holder exists but this actor may not see it — the name is taken either way, and
+     * which document it is stays behind the same wall every other read stands behind.
+     */
+    promptNameHolder(actor: Actor, name: string): Promise<PromptNameHolder | null>;
     archiveNode(input: {
         nodeId: string;
         baseUpdatedAt: string;

package/dist/prompts/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { Prompts, PromptsDeps } from "./prompts.types.js";
+export declare function createPrompts(deps: PromptsDeps): Prompts;

package/dist/prompts/prompts.js

@@ -0,0 +1,65 @@
+import { documentText } from "../shared/document-text/document-text.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+/**
+ * What a client is handed when it opens the command of a FLOW.
+ *
+ * ⚠️ **This text starts nothing, and that is the point** (D24: the agent acts, Intel does not).
+ * `prompts/get` is a read — a model asked for the wording of a command, not for the command to
+ * happen. Returning instructions rather than performing them keeps the one property that makes
+ * Intel safe to point a model at: nothing in this package moves because something was READ.
+ *
+ * ⚠️ It names the `flowId` rather than the prompt name, because the name is not what the next call
+ * takes. A model handed "run the flow `crm-outreach`" has to translate that back into an id, and
+ * the translation is exactly the step it gets wrong — `flow_run_start` takes an id and refuses a
+ * name with a message about the id being unknown.
+ */
+function flowInstruction(entry) {
+    const description = entry.description === null ? "" : `\n\n${entry.description}`;
+    return `Start the Intel flow "${entry.title}" by calling \`flow_run_start\` with \`flowId: "${entry.targetId}"\`. Do not describe the flow instead of starting it, and do not invent a different id: this one is the flow the command \`/${entry.name}\` stands for.${description}`;
+}
+export function createPrompts(deps) {
+    return {
+        async list(actor) {
+            return await deps.repository.listOffered(actor);
+        },
+        async get(actor, name) {
+            const entry = await deps.repository.findOffered(actor, name);
+            /**
+             * ⚠️ **One refusal for "no such command" and for "not yours to see", and it says the first.**
+             * `findOffered` searches the catalogue as this actor sees it, so a document offered under
+             * this name inside a folder they may not read is simply absent from it. Two different
+             * messages here would make the refusal a way of asking whether a command exists — the same
+             * reading of the tree ADR-0004 §3 refuses everywhere else.
+             */
+            if (entry === null) {
+                throw new IntelError(404, "prompt_not_found", "No command by that name is offered to you. `prompts/list` names the ones that are.");
+            }
+            if (entry.kind === "flow")
+                return { entry, text: flowInstruction(entry) };
+            const document = await deps.readDocument(actor, entry.targetId);
+            /**
+             * ⚠️ **A document with no version yet is an EMPTY command, not a failure.** Somebody offered a
+             * document they have not written in; the honest answer is the empty instruction they have.
+             */
+            if (document.version === null || document.content === null)
+                return { entry, text: "" };
+            /**
+             * ⚠️ **What a document node stores is not its text.** The editor writes a BlockNote payload,
+             * and handing that on gives a model a JSON blob where its instruction should be — for
+             * practically every document written in the app. `documentText` is the same extraction the
+             * search index runs, out of the same function, so the words a model is given and the words
+             * somebody can search for cannot drift apart.
+             */
+            const text = documentText(document.version.mediaType, document.content);
+            /**
+             * ⚠️ And an unreadable payload is REFUSED rather than passed on raw. Half a JSON document as
+             * an instruction is the failure this whole finding is about, one step further along: the
+             * model would act on it rather than report it.
+             */
+            if (text === null) {
+                throw new IntelError(422, "prompt_unreadable", `The document behind /${entry.name} is not stored in a form this command can be read from. Open it once and save it, or offer a document written in the editor.`);
+            }
+            return { entry, text };
+        },
+    };
+}

package/dist/prompts/prompts.types.d.ts

@@ -0,0 +1,71 @@
+import type { NodeDocument } from "@anchrd/intel-contract/node";
+import type { Actor } from "../nodes/nodes.types.js";
+/**
+ * One entry of the slash-command catalogue (#775): a document offered as an instruction, or a
+ * published flow offered as a way to start one.
+ *
+ * ⚠️ `kind` is two values and not `NodeKind`. A flow is not a node, and the five node kinds that
+ * cannot be offered have no business appearing in this union — a widened type here would be a
+ * standing invitation to hand `prompts/list` a folder.
+ */
+export interface PromptEntry {
+    name: string;
+    kind: "document" | "flow";
+    targetId: string;
+    title: string;
+    description: string | null;
+}
+/**
+ * Who holds a name, as much of it as the asking actor is entitled to learn.
+ *
+ * ⚠️ `title` is `null` when the holder exists but this actor may not see it, and that is not the
+ * same as "no holder". ADR-0004 §3 is explicit that a refusal must not become a way of reading the
+ * tree: naming the document that holds `payroll` would tell somebody without access that a document
+ * by that title exists. The caller is told the name is taken — which they must be, or they cannot
+ * proceed — and nothing else.
+ */
+export interface PromptNameHolder {
+    kind: "document" | "flow";
+    title: string | null;
+}
+/**
+ * Who is asking for the catalogue, and which halves of it they are entitled to at all.
+ *
+ * ⚠️ **The capability follows the KIND, exactly as it does for `audit_list`** (#774). A prompt
+ * entry says the same thing its resource says, so listing it asks what reading that resource asks:
+ * `nodes/read` for a document, `flows/read` for a flow. Somebody holding only one of the two gets
+ * the half they hold — not an empty list, and not the other half by accident.
+ *
+ * ⚠️ These are the GATE capabilities and they are the coarse half of the answer. The resource ACL
+ * still runs underneath, per row, in the query itself; a caller with `nodes/read` sees the offered
+ * documents THEY may read and no others.
+ */
+export interface PromptActor extends Actor {
+    canReadNodes: boolean;
+    canReadFlows: boolean;
+}
+export interface PromptRepository {
+    listOffered(actor: PromptActor): Promise<PromptEntry[]>;
+    findOffered(actor: PromptActor, name: string): Promise<PromptEntry | null>;
+}
+export interface PromptsDeps {
+    repository: PromptRepository;
+    /**
+     * One document, as the node service reads it: the same authorization walk, the same content
+     * store. `prompts/get` does not reach into R2 on its own — a second reader would be a second
+     * place for the ACL to be applied, and the one that gets it wrong is the one nobody looks at.
+     *
+     * ⚠️ **The whole document, not a string.** What is stored under a document node is the editor's
+     * payload, and turning that into readable text needs the `mediaType` beside the content. Handing
+     * a string in would put that decision in whatever wired this up — in the Cloudflare shell, which
+     * is the one place in this package that may not hold business behaviour.
+     */
+    readDocument(actor: Actor, nodeId: string): Promise<NodeDocument>;
+}
+export interface Prompts {
+    list(actor: PromptActor): Promise<PromptEntry[]>;
+    get(actor: PromptActor, name: string): Promise<{
+        entry: PromptEntry;
+        text: string;
+    }>;
+}

package/dist/prompts/prompts.types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/document-text/document-text.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The READABLE text of one stored version, for the two places that need a document as prose rather
+ * than as the editor's own payload.
+ *
+ * ⚠️ **What a document node stores is NOT its text.** The editor writes a BlockNote payload —
+ * `{ blocks, markdown, … }` — and `markdown` beside the blocks is the whole of what anybody outside
+ * the editor can read. `packages/ui/CLAUDE.md` states it for the search: `indexing.ts` pulls that
+ * field and nothing else into full text and vectors, so it is what anyone searching Intel matches
+ * against. A caller who hands the raw content on instead is handing on a JSON blob.
+ *
+ * ⚠️ **Every other media type travels unchanged**, and that is not an oversight: a `text/markdown`
+ * version IS its text, and a table renders its own. Only the editor's payload has a wrapper around
+ * the words.
+ *
+ * ⚠️ **`null` means "this content is not readable as text", not "empty".** Immutable content never
+ * becomes parsable on a retry, so the two callers answer it differently and each is right for its
+ * own surface: the indexer refuses the version permanently rather than requeueing it forever, and
+ * `prompts/get` refuses the call rather than handing a model half a JSON document. Returning `""`
+ * here would collapse both into "there is nothing to say".
+ */
+export declare function documentText(mediaType: string, content: string): string | null;

package/dist/shared/document-text/document-text.js

@@ -0,0 +1,31 @@
+import { BlockNoteDocument, BlockNoteMediaType } from "@anchrd/intel-contract/node";
+/**
+ * The READABLE text of one stored version, for the two places that need a document as prose rather
+ * than as the editor's own payload.
+ *
+ * ⚠️ **What a document node stores is NOT its text.** The editor writes a BlockNote payload —
+ * `{ blocks, markdown, … }` — and `markdown` beside the blocks is the whole of what anybody outside
+ * the editor can read. `packages/ui/CLAUDE.md` states it for the search: `indexing.ts` pulls that
+ * field and nothing else into full text and vectors, so it is what anyone searching Intel matches
+ * against. A caller who hands the raw content on instead is handing on a JSON blob.
+ *
+ * ⚠️ **Every other media type travels unchanged**, and that is not an oversight: a `text/markdown`
+ * version IS its text, and a table renders its own. Only the editor's payload has a wrapper around
+ * the words.
+ *
+ * ⚠️ **`null` means "this content is not readable as text", not "empty".** Immutable content never
+ * becomes parsable on a retry, so the two callers answer it differently and each is right for its
+ * own surface: the indexer refuses the version permanently rather than requeueing it forever, and
+ * `prompts/get` refuses the call rather than handing a model half a JSON document. Returning `""`
+ * here would collapse both into "there is nothing to say".
+ */
+export function documentText(mediaType, content) {
+    if (mediaType !== BlockNoteMediaType)
+        return content;
+    try {
+        return BlockNoteDocument.parse(JSON.parse(content)).markdown;
+    }
+    catch {
+        return null;
+    }
+}

package/migrations/0027_the_runs_of_every_flow.sql

@@ -0,0 +1,27 @@
+-- `flow_run_list` may now be asked without a flow (#774): "did anything run at all", over every
+-- flow the caller may read. `flow_runs_flow_idx (flow_id, created_at DESC)` cannot serve that — it
+-- leads with `flow_id`, and without an equality on that column the ordering falls off the index and
+-- SQLite sorts the whole table instead.
+--
+-- ⚠️ Measured against the real `flowRunsPageQuery({ scoped: false })` before this file existed, on
+-- the same engine and the same schema:
+--
+--     SCAN run
+--     … | USE TEMP B-TREE FOR ORDER BY
+--
+-- That last line is a sorting pass over every run in the installation. It costs nothing while a
+-- customer has fifty runs and everything once an agent has been running for a month.
+--
+-- ⚠️ Both columns, in the order the cursor compares them, for the reason `0022` and `0026` give:
+-- two runs created in the same millisecond are not exotic, and without the tie-break on `id` a
+-- reader continuing on `created_at` alone skips the second one with no error and no log.
+--
+-- ⚠️ `DESC` on both, because this page is newest-first. An ASC index can be walked backwards by
+-- SQLite, but only as long as EVERY term agrees on the direction — matching the `ORDER BY` exactly
+-- is the one shape that keeps that true when a third term is added later.
+--
+-- ⚠️ This does NOT replace `flow_runs_flow_idx`. That one still serves the scoped page — the runs
+-- of ONE flow — which is the older and by far the more frequent question; dropping it would put a
+-- full scan into the call that has none today. Two questions, two shapes, two indexes.
+CREATE INDEX flow_runs_time_idx
+  ON flow_runs(created_at DESC, id DESC);

package/migrations/0028_a_prompt_name_over_two_kinds.sql

@@ -0,0 +1,70 @@
+-- A document and a published flow can both be offered as a slash command (#775). What they need is
+-- one short name, and the name has to be unique across BOTH of them: they land in the same
+-- `prompts/list` catalogue, so a document and a flow can take each other's name.
+--
+-- ⚠️ **One field, not two.** `prompt_name` set means offered, `NULL` means not. A boolean beside it
+-- would allow the state "on, without a name", and that is not a thing `prompts/list` could answer.
+--
+-- ⚠️ **No third table, and the choice is deliberate.** A `prompt_names(name PRIMARY KEY, …)`
+-- catalogue would carry the cross-kind uniqueness as a real constraint, and it would cost two
+-- things this schema is not willing to pay: a second truth about the name of one node — every
+-- `SELECT` over `nodes` would have to remember a join, and the one that forgets it answers `NULL`
+-- in silence — and a fourth child table for the `nodes` rebuild recipe to carry (see the package
+-- CLAUDE.md; `node_links` is the one that already has to be carried out and back). The uniqueness
+-- WITHIN one kind is an index here; the uniqueness ACROSS the two is a condition on the write, on
+-- every statement that sets a name, in the same batch that writes it.
+--
+-- ⚠️ The condition on the write is not a nicety. A `SELECT` before an `UPDATE` in a separate call
+-- decides on a state that may be gone by the time the write lands; the check has to be part of the
+-- statement so that the two cannot come apart. What the caller is told — WHICH node or flow holds
+-- the name — is a second, cheap read that only runs once the write has already refused.
+
+-- ⚠️ **This form is MEASURED against real D1, not only against miniflare.** No other file in this
+-- folder adds a `CHECK` through `ALTER TABLE … ADD COLUMN` that reads a DIFFERENT column, and the
+-- package CLAUDE.md is explicit that a green run under the emulator proves nothing about the
+-- deployment — `foreign_keys = OFF` is honoured there and ignored by D1 over its HTTP API. A
+-- migration file is immutable after release, so the failure would surface at the deploy.
+--
+-- Run against a throwaway D1 (`intel-check-0028`, `--remote`) on 2026-08-25 and then deleted. Both
+-- statements applied, `sqlite_master` shows the CHECK on the column, and all six refusals fire with
+-- `SQLITE_CONSTRAINT_CHECK` / `SQLITE_CONSTRAINT_UNIQUE`: a folder and a table with a name, an
+-- uppercase name, a name with a space, a 41-character name, and a second row taking a name that is
+-- already held. A document with a valid name and two rows with none go through.
+--
+-- ⚠️ `kind = 'document'` is in the CHECK, not only in the service. A prompt is an instruction, not
+-- material: a folder, a table, an attachment, a board or a task never carries one (#775). The
+-- service refuses it with a sentence, and this line is what makes that refusal true even for a
+-- write that never passes the service.
+--
+-- ⚠️ `NOT GLOB '*[^a-z0-9-]*'` is the grammar `^[a-z0-9-]{1,40}$` says on the contract, spelled the
+-- one way SQLite can spell it: "no character outside the class anywhere". The obvious
+-- `GLOB '[a-z0-9-]*'` is NOT that check — it constrains the first character and lets every other
+-- one through, so `a_B C` passes it. The hyphen sits last inside the class, where it is a literal
+-- rather than a range.
+ALTER TABLE nodes ADD COLUMN prompt_name TEXT
+  CHECK (
+    prompt_name IS NULL
+    OR (
+      kind = 'document'
+      AND length(prompt_name) BETWEEN 1 AND 40
+      AND prompt_name NOT GLOB '*[^a-z0-9-]*'
+    )
+  );
+
+ALTER TABLE flows ADD COLUMN prompt_name TEXT
+  CHECK (
+    prompt_name IS NULL
+    OR (length(prompt_name) BETWEEN 1 AND 40 AND prompt_name NOT GLOB '*[^a-z0-9-]*')
+  );
+
+-- ⚠️ Partial, and that is the whole reason they work. A plain `UNIQUE` index would let several
+-- rows carry `NULL` too — SQLite treats NULLs as distinct — so the `WHERE` clause buys no
+-- correctness here; it buys the SIZE. Almost every node has no prompt name, and an index over
+-- them all would be one entry per node in the tree to serve a handful of rows.
+--
+-- ⚠️ These two carry the uniqueness WITHIN a kind and nothing more. Two documents cannot share a
+-- name and two flows cannot; a document and a flow can, as far as these indexes are concerned, and
+-- the condition on the write is the only thing that stops them. Reading one of these index names in
+-- a query plan is therefore not evidence that the cross-kind rule held.
+CREATE UNIQUE INDEX nodes_prompt_name_idx ON nodes(prompt_name) WHERE prompt_name IS NOT NULL;
+CREATE UNIQUE INDEX flows_prompt_name_idx ON flows(prompt_name) WHERE prompt_name IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.26.0",
-    "@anchrd/intel-contract": "^0.31.0",
+    "@anchrd/intel-contract": "^0.33.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",