@anchrd/intel-api 0.3.0 → 0.3.2

package/dist/knowledge/knowledge.types.d.ts

@@ -1,9 +1,9 @@
-import type { ArchiveKnowledgeNodeInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, KnowledgeAttachment, KnowledgeCitation, KnowledgeDocument, KnowledgeGraph, KnowledgeGraphInput, KnowledgeLink, KnowledgeNode, KnowledgeVersion, ListKnowledgeNodesInput, ResourceGrant, RevokeKnowledgeGrantInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, UpdateKnowledgeNodeInput } from "@anchrd/intel-contract";
+import type { AppendKnowledgeTableRowsInput, AppendKnowledgeTableRowsResult, ArchiveKnowledgeNodeInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, KnowledgeAttachment, KnowledgeCitation, KnowledgeDocument, KnowledgeGraph, KnowledgeGraphInput, KnowledgeLink, KnowledgeNode, KnowledgeTable, KnowledgeVersion, ListKnowledgeNodesInput, ResolveKnowledgeLinksInput, ResolveKnowledgeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeKnowledgeGrantInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, ShareKnowledgeResult, UpdateKnowledgeNodeInput } from "@anchrd/intel-contract";
 import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
 export interface Actor {
     id: string;
     email: string;
-    canReindex?: boolean;
+    isAdmin?: boolean;
 }
 export interface NewKnowledgeNode {
     node: KnowledgeNode;
@@ -18,16 +18,28 @@ export interface NewKnowledgeVersion {
     idempotencyKey: string;
     auditId: string;
 }
+export interface NewKnowledgeTableVersion {
+    version: Omit<KnowledgeVersion, "sequence">;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+}
 export interface KnowledgeRepository {
     listVisible(actor: Actor, input: ListKnowledgeNodesInput): Promise<KnowledgeNode[]>;
+    listVisibleBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
     getVisible(actor: Actor, nodeId: string): Promise<KnowledgeNode | null>;
-    canEdit(actor: Actor, nodeId: string): Promise<boolean>;
-    canManage(actor: Actor, nodeId: string): Promise<boolean>;
-    findIdempotentNode(actorId: string, operation: "knowledge.create" | "knowledge.save" | "knowledge.update" | "knowledge.archive" | "knowledge.link" | "knowledge.unlink" | "knowledge.share" | "knowledge.revoke", idempotencyKey: string): Promise<string | null>;
+    can(actor: Actor, nodeId: string, verb: ResourceVerb): Promise<boolean>;
+    findIdempotentNode(actorId: string, operation: "knowledge.create" | "knowledge.save" | "knowledge.append" | "knowledge.update" | "knowledge.archive" | "knowledge.share" | "knowledge.revoke", idempotencyKey: string): Promise<string | null>;
     findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
     insertNode(input: NewKnowledgeNode): Promise<KnowledgeNode>;
     getVersion(versionId: string): Promise<KnowledgeVersion | null>;
     appendVersion(input: NewKnowledgeVersion): Promise<"saved" | "conflict">;
+    appendTableVersion(input: NewKnowledgeTableVersion): Promise<KnowledgeVersion>;
+    listVersionContentKeys(nodeId: string): Promise<string[]>;
+    firstVersionContentKey(nodeId: string): Promise<string | null>;
     listVersions(nodeId: string): Promise<KnowledgeVersion[]>;
     updateNode(input: {
         node: KnowledgeNode;
@@ -46,23 +58,22 @@ export interface KnowledgeRepository {
         auditId: string;
     }): Promise<"conflict" | KnowledgeNode>;
     listGrants(resourceId: string): Promise<ResourceGrant[]>;
+    organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
     listLinksVisible(actor: Actor, nodeId: string): Promise<KnowledgeLink[]>;
-    getLinkVisible(actor: Actor, linkId: string): Promise<KnowledgeLink | null>;
-    findLinkVisible(actor: Actor, input: Pick<CreateKnowledgeLinkInput, "sourceNodeId" | "targetNodeId" | "relation">): Promise<KnowledgeLink | null>;
-    insertLink(input: {
-        link: KnowledgeLink;
-        actorId: string;
-        idempotencyKey: string;
-        auditId: string;
-    }): Promise<KnowledgeLink>;
-    deleteLink(input: {
+    resolveVisibleTitles(actor: Actor, nodeIds: string[]): Promise<Array<{
+        nodeId: string;
+        title: string;
+    }>>;
+    replaceTextLinks(input: {
         sourceNodeId: string;
-        linkId: string;
+        links: Array<{
+            id: string;
+            targetNodeId: string;
+        }>;
         actorId: string;
-        idempotencyKey: string;
         auditId: string;
         occurredAt: string;
-    }): Promise<boolean>;
+    }): Promise<void>;
     graphVisible(actor: Actor, input: KnowledgeGraphInput): Promise<KnowledgeGraph>;
     setGrant(input: {
         grant: ResourceGrant;
@@ -102,20 +113,46 @@ export interface KnowledgeDeps {
     content: ContentStore;
     id(): string;
     now(): Date;
+    externalFlowCallers(actor: Actor, folderId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowKnowledgeReferences(actor: Actor, folderId: string): Promise<string[]>;
     hash(content: string | Uint8Array): Promise<string>;
     indexing: {
         enqueue(versionId: string): Promise<void>;
     };
     semantic?: SemanticIndex | undefined;
 }
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
+export interface BoundedChildren {
+    items: KnowledgeNode[];
+    total: number;
+}
 export interface KnowledgeService {
     list(actor: Actor, input: ListKnowledgeNodesInput): Promise<{
         items: KnowledgeNode[];
     }>;
+    /**
+     * One level of the tree as this actor may see it, bounded: at most `limit` current children, and
+     * `total` for how many there are. Its caller is the relation graph, which draws a bounded picture
+     * and must not read a folder of a thousand documents to do it (#30).
+     *
+     * ⚠️ `total` counts what passed the visibility predicate and nothing else, or the size a picture
+     * reports would become a way of learning that something is filed here.
+     */
+    childrenBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
     get(actor: Actor, nodeId: string): Promise<KnowledgeDocument>;
+    folderAccess(actor: Actor, folderId: string): Promise<FolderAccess>;
     create(actor: Actor, input: CreateKnowledgeNodeInput): Promise<KnowledgeNode>;
     save(actor: Actor, input: SaveKnowledgeVersionInput): Promise<KnowledgeDocument>;
     saveAttachment(actor: Actor, input: SaveKnowledgeAttachmentInput): Promise<KnowledgeDocument>;
+    getTable(actor: Actor, nodeId: string): Promise<KnowledgeTable>;
+    defineTable(actor: Actor, input: DefineKnowledgeTableInput): Promise<KnowledgeTable>;
+    appendTableRows(actor: Actor, input: AppendKnowledgeTableRowsInput): Promise<AppendKnowledgeTableRowsResult>;
     getAttachment(actor: Actor, nodeId: string): Promise<KnowledgeAttachment>;
     readAttachment(actor: Actor, nodeId: string): Promise<KnowledgeAttachmentBody>;
     listVersions(actor: Actor, nodeId: string): Promise<{
@@ -123,18 +160,14 @@ export interface KnowledgeService {
     }>;
     update(actor: Actor, input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode>;
     archive(actor: Actor, input: ArchiveKnowledgeNodeInput): Promise<KnowledgeNode>;
-    listGrants(actor: Actor, resourceId: string): Promise<{
-        items: ResourceGrant[];
-    }>;
+    listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
     listLinks(actor: Actor, nodeId: string): Promise<{
         items: KnowledgeLink[];
     }>;
-    createLink(actor: Actor, input: CreateKnowledgeLinkInput): Promise<KnowledgeLink>;
-    deleteLink(actor: Actor, input: DeleteKnowledgeLinkInput): Promise<{
-        deleted: boolean;
-    }>;
+    resolveLinks(actor: Actor, input: ResolveKnowledgeLinksInput): Promise<ResolveKnowledgeLinksResult>;
     graph(actor: Actor, input: KnowledgeGraphInput): Promise<KnowledgeGraph>;
-    share(actor: Actor, input: ShareKnowledgeInput): Promise<ResourceGrant>;
+    visibleNode(actor: Actor, nodeId: string): Promise<KnowledgeNode | null>;
+    share(actor: Actor, input: ShareKnowledgeInput): Promise<ShareKnowledgeResult>;
     revokeGrant(actor: Actor, input: RevokeKnowledgeGrantInput): Promise<{
         revoked: boolean;
     }>;
@@ -149,9 +182,9 @@ export interface KnowledgeIndexTarget {
     nodeId: string;
     versionId: string;
     title: string;
-    contentKey: string;
+    contentKeys: string[];
     mediaType: string;
-    kind: "document" | "attachment";
+    kind: "document" | "attachment" | "table";
     updatedAt: string;
 }
 export interface KnowledgeIndexRepository {

package/dist/mcp/mcp.js

@@ -1,7 +1,8 @@
-import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, KnowledgeGraphInput, ListFlowGrantsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendKnowledgeTableRowsInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, GetKnowledgeTableInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
+import { permits } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 function text(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
@@ -27,25 +28,26 @@ export async function handleMcp(request, deps) {
     const actor = {
         id: deps.authorization.identity.id,
         email: deps.authorization.identity.email,
-        canReindex: deps.authorization.can("intel", "admin"),
+        isAdmin: deps.authorization.can("intel", "admin"),
     };
     const toolActor = {
         id: deps.authorization.identity.id,
         email: deps.authorization.identity.email,
-        canExecute: deps.authorization.can("tools", "execute"),
+        canExecute: permits(deps.authorization, "tools", "execute"),
     };
     const flowActor = {
         id: deps.authorization.identity.id,
         email: deps.authorization.identity.email,
-        canRun: deps.authorization.can("flows", "run"),
-        canApprove: deps.authorization.can("flows", "approve"),
+        canRun: permits(deps.authorization, "flows", "run"),
+        canApprove: permits(deps.authorization, "flows", "approve"),
+        isAdmin: deps.authorization.can("intel", "admin"),
     };
     const server = new McpServer({ name: "intel", version: "0.1.0" });
     const EmptyInput = z.strictObject({});
-    if (deps.authorization.can("knowledge", "read")) {
+    if (permits(deps.authorization, "knowledge", "read")) {
         server.registerTool("knowledge_list", {
             title: "List knowledge",
-            description: "List authorized folders, documents, and attachments under one parent.",
+            description: "List authorized folders, documents, attachments, and tables under one parent.",
             inputSchema: ListKnowledgeNodesInput,
             annotations: {
                 title: "List knowledge",
@@ -127,6 +129,18 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.knowledge.search(actor, input)));
+        server.registerTool("knowledge_table_get", {
+            title: "Get knowledge table",
+            description: "Read one authorized table as column names and rows.",
+            inputSchema: GetKnowledgeTableInput,
+            annotations: {
+                title: "Get knowledge table",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.knowledge.getTable(actor, input.nodeId)));
         server.registerTool("knowledge_links_list", {
             title: "List knowledge links",
             description: "List authorized outgoing links and backlinks for one Knowledge node.",
@@ -139,6 +153,25 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.knowledge.listLinks(actor, input.nodeId)));
+        // The reader's half of a document link (#41): the titles of the linked documents this caller
+        // may see. There is no tool to create or delete a link — a relationship is written in the text
+        // and `knowledge_save` is what records it, so there is only one way to make one.
+        //
+        // ⚠️ A target this caller may not reach, or one that is gone, is simply absent from the answer.
+        // The two are indistinguishable on purpose: telling them apart would confirm that a document
+        // exists somewhere they cannot look.
+        server.registerTool("knowledge_links_resolve", {
+            title: "Resolve knowledge links",
+            description: "Resolve document link targets to the titles this caller is authorized to see. Targets that are unreachable or deleted are absent from the result.",
+            inputSchema: ResolveKnowledgeLinksInput,
+            annotations: {
+                title: "Resolve knowledge links",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.knowledge.resolveLinks(actor, input)));
         server.registerTool("knowledge_graph", {
             title: "Get knowledge graph",
             description: "Get the authorized Knowledge nodes and explicit relationships for discovery.",
@@ -166,10 +199,10 @@ export async function handleMcp(request, deps) {
             },
         }, async () => text(await deps.knowledge.reindex(actor)));
     }
-    if (deps.authorization.can("knowledge", "create")) {
+    if (permits(deps.authorization, "knowledge", "create")) {
         server.registerTool("knowledge_create", {
             title: "Create knowledge",
-            description: "Create a governed folder, document, or attachment metadata node.",
+            description: "Create a governed folder, document, attachment, or table node.",
             inputSchema: CreateKnowledgeNodeInput,
             annotations: {
                 title: "Create knowledge",
@@ -180,7 +213,7 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.knowledge.create(actor, input)));
     }
-    if (deps.authorization.can("knowledge", "write")) {
+    if (permits(deps.authorization, "knowledge", "write")) {
         server.registerTool("knowledge_save", {
             title: "Save knowledge version",
             description: "Append an immutable content version using an optimistic base version.",
@@ -205,6 +238,34 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.knowledge.saveAttachment(actor, input)));
+        server.registerTool("knowledge_table_define", {
+            title: "Define knowledge table columns",
+            description: "Write the column names of an empty table. The header is the contract every append is checked against and cannot be rewritten.",
+            inputSchema: DefineKnowledgeTableInput,
+            annotations: {
+                title: "Define knowledge table columns",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.knowledge.defineTable(actor, input)));
+        // The tool #40 exists for: an agent collecting findings on a schedule appends them without
+        // reading or resending what is already there, and two agents appending at once lose nothing.
+        server.registerTool("knowledge_table_append", {
+            title: "Append knowledge table rows",
+            description: "Append rows to a table without reading or resending its existing content. Each row must have exactly as many cells as the table has columns; a row that does not is rejected and nothing is written.",
+            inputSchema: AppendKnowledgeTableRowsInput,
+            annotations: {
+                title: "Append knowledge table rows",
+                readOnlyHint: false,
+                destructiveHint: false,
+                // The idempotency key makes a repeat of the same call a no-op; without one, appending
+                // twice appends twice, which is what appending means.
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.knowledge.appendTableRows(actor, input)));
         server.registerTool("knowledge_update", {
             title: "Update knowledge",
             description: "Rename, move, describe, or change the context policy of Knowledge.",
@@ -229,32 +290,8 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.knowledge.archive(actor, input)));
-        server.registerTool("knowledge_link_create", {
-            title: "Link knowledge",
-            description: "Create a governed relationship between two authorized Knowledge nodes.",
-            inputSchema: CreateKnowledgeLinkInput,
-            annotations: {
-                title: "Link knowledge",
-                readOnlyHint: false,
-                destructiveHint: false,
-                idempotentHint: true,
-                openWorldHint: false,
-            },
-        }, async (input) => text(await deps.knowledge.createLink(actor, input)));
-        server.registerTool("knowledge_link_delete", {
-            title: "Delete knowledge link",
-            description: "Delete one governed Knowledge relationship by ID.",
-            inputSchema: DeleteKnowledgeLinkInput,
-            annotations: {
-                title: "Delete knowledge link",
-                readOnlyHint: false,
-                destructiveHint: true,
-                idempotentHint: true,
-                openWorldHint: false,
-            },
-        }, async (input) => text(await deps.knowledge.deleteLink(actor, input)));
     }
-    if (deps.authorization.can("knowledge", "share")) {
+    if (permits(deps.authorization, "knowledge", "share")) {
         server.registerTool("knowledge_shares_list", {
             title: "List knowledge shares",
             description: "List direct grants for Knowledge the caller is allowed to manage.",
@@ -292,11 +329,11 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.knowledge.revokeGrant(actor, input)));
     }
-    if (deps.authorization.can("flows", "read")) {
+    if (permits(deps.authorization, "flows", "read")) {
         server.registerTool("flows_list", {
             title: "List flows",
-            description: "List authorized company flows by title and description.",
-            inputSchema: EmptyInput,
+            description: "List authorized flows, either all of them or the ones filed in one folder of the shared Knowledge tree.",
+            inputSchema: ListFlowsInput,
             annotations: {
                 title: "List flows",
                 readOnlyHint: true,
@@ -304,7 +341,7 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async () => text(await deps.flows.list(flowActor)));
+        }, async (input) => text(await deps.flows.list(flowActor, input)));
         server.registerTool("flow_get", {
             title: "Get flow",
             description: "Load one authorized flow and its current immutable graph on demand.",
@@ -317,6 +354,45 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.get(flowActor, input.flowId)));
+        server.registerTool("flow_calls_list", {
+            title: "List called flows",
+            description: "List the flows one flow calls, read out of its graph rather than out of where it is filed.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List called flows",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listCalls(flowActor, input.flowId)));
+        // ⚠️ Only nodes the requesting user may see are in the answer, placeholders included: an edge to
+        // a grey box would already say that something is there. The same rule the screen follows,
+        // because it is the same service (#19).
+        server.registerTool("flow_relation_graph", {
+            title: "Read the relation graph",
+            description: "Read what accesses what for one folder or one flow: which flow reads which document and which flow calls which flow.",
+            inputSchema: RelationGraphInput,
+            annotations: {
+                title: "Read the relation graph",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.relationGraph(flowActor, input)));
+        server.registerTool("flow_requirements_list", {
+            title: "List what a flow needs",
+            description: "List the Knowledge documents and MCP tools one flow's graph names. Documents the calling user cannot see are counted rather than named, and no claim is made about whether anyone may reach them: for tools that cannot be known in advance, because the catalog is a live query with each user's own portal token.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List what a flow needs",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listRequirements(flowActor, input.flowId)));
         server.registerTool("flow_run_get", {
             title: "Get flow run",
             description: "Get durable run state and the next node an AI or person must handle.",
@@ -329,46 +405,37 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.getRun(flowActor, input.runId)));
-    }
-    if (deps.authorization.can("flows", "share")) {
-        server.registerTool("flow_shares_list", {
-            title: "List flow shares",
-            description: "List direct grants for a Flow the caller is allowed to manage.",
-            inputSchema: ListFlowGrantsInput,
-            annotations: {
-                title: "List flow shares",
+        // ⚠️ Model context like every other tool result: what a run did, never what it produced. The run
+        // input and output are absent because a run reaches Knowledge and tools with the rights of
+        // whoever started it, and only their own runs are the calling user's to read out that way.
+        server.registerTool("flow_runs_list", {
+            title: "List flow runs",
+            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.",
+            inputSchema: ListFlowRunsInput,
+            annotations: {
+                title: "List flow runs",
                 readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.flows.listGrants(flowActor, input.resourceId)));
-        server.registerTool("flow_share", {
-            title: "Share flow",
-            description: "Grant Flow access to a Gate user, verified email, or the organization.",
-            inputSchema: ShareFlowInput,
+        }, async (input) => text(await deps.flows.listRuns(flowActor, input)));
+        server.registerTool("flow_run_steps_list", {
+            title: "List flow run steps",
+            description: "List every completed step of one run, oldest first, with its outcome, branch, and the reason a failed step gives, plus the call chain the run belongs to.",
+            inputSchema: GetFlowRunInput,
             annotations: {
-                title: "Share flow",
-                readOnlyHint: false,
+                title: "List flow run steps",
+                readOnlyHint: true,
                 destructiveHint: false,
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.flows.share(flowActor, input)));
-        server.registerTool("flow_revoke_share", {
-            title: "Revoke flow share",
-            description: "Revoke one direct Flow grant by ID.",
-            inputSchema: RevokeFlowGrantInput,
-            annotations: {
-                title: "Revoke flow share",
-                readOnlyHint: false,
-                destructiveHint: true,
-                idempotentHint: true,
-                openWorldHint: false,
-            },
-        }, async (input) => text(await deps.flows.revokeGrant(flowActor, input)));
+        }, async (input) => text(await deps.flows.listRunSteps(flowActor, input.runId)));
     }
-    if (deps.authorization.can("flows", "create")) {
+    // A flow has no share tool of its own. Sharing happens on the folder a flow is filed in, through
+    // knowledge_share, so a narrower grant cannot sit beside the folder grant (ADR-0004 §2).
+    if (permits(deps.authorization, "flows", "create")) {
         server.registerTool("flow_create", {
             title: "Create flow",
             description: "Create governed flow metadata before adding an immutable graph version.",
@@ -382,7 +449,19 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.create(flowActor, input)));
     }
-    if (deps.authorization.can("flows", "write")) {
+    if (permits(deps.authorization, "flows", "write")) {
+        server.registerTool("flow_update", {
+            title: "Rename or move flow",
+            description: "Rename a flow, change its description, or move it to another folder of the shared Knowledge tree. Never changes what the flow does.",
+            inputSchema: UpdateFlowInput,
+            annotations: {
+                title: "Rename or move flow",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.update(flowActor, input)));
         server.registerTool("flow_save", {
             title: "Save flow",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",
@@ -396,7 +475,22 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.save(flowActor, input)));
     }
-    if (deps.authorization.can("flows", "publish")) {
+    if (permits(deps.authorization, "flows", "publish")) {
+        // The same answer the screen shows the author before publishing. Every user-visible capability
+        // has its MCP equivalent, and a freeze nobody could inspect from here would be one behavior
+        // through two doors.
+        server.registerTool("flow_publish_preview", {
+            title: "Preview flow publication",
+            description: "Show which version each sub-flow call will take and which of them publishing freezes.",
+            inputSchema: PreviewFlowPublishInput,
+            annotations: {
+                title: "Preview flow publication",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.previewPublish(flowActor, input)));
         server.registerTool("flow_publish", {
             title: "Publish flow",
             description: "Publish a version after resolving its authorized Knowledge and tool references.",
@@ -410,7 +504,7 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.publish(flowActor, input)));
     }
-    if (deps.authorization.can("flows", "run")) {
+    if (permits(deps.authorization, "flows", "run")) {
         server.registerTool("flow_run_start", {
             title: "Start flow run",
             description: "Start a durable run of the published graph and return its first actionable node.",
@@ -436,7 +530,7 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.flows.completeStep(flowActor, input)));
     }
-    if (deps.authorization.can("tools", "read")) {
+    if (permits(deps.authorization, "tools", "read")) {
         server.registerTool("tools_catalog_list", {
             title: "List tools",
             description: "List the MCP tools the calling user can reach through the portal, live rather than cached.",
@@ -450,7 +544,7 @@ export async function handleMcp(request, deps) {
             },
         }, async () => text(await deps.tools.catalog(toolActor)));
     }
-    if (deps.authorization.can("tools", "test")) {
+    if (permits(deps.authorization, "tools", "test")) {
         server.registerTool("tools_test", {
             title: "Test tool",
             description: "Validate input and execute one explicitly read-only cached MCP tool with the caller's Gate connection.",
@@ -464,7 +558,7 @@ export async function handleMcp(request, deps) {
             },
         }, async (input) => text(await deps.tools.test(toolActor, input)));
     }
-    if (deps.authorization.can("tools", "execute")) {
+    if (permits(deps.authorization, "tools", "execute")) {
         server.registerTool("tools_execute", {
             title: "Execute tool",
             description: "Validate and execute a discovered MCP tool with the caller's just-in-time Gate connection.",

package/dist/shared/csv/csv.d.ts

@@ -0,0 +1,13 @@
+export declare function encodeCsvRow(cells: readonly string[]): string;
+export declare function encodeCsv(rows: readonly (readonly string[])[]): string;
+/**
+ * Every row of a CSV body, quoted fields included.
+ *
+ * ⚠️ A quoted field may contain a line break, so this cannot split on `\n` first. A row is closed
+ * by a line break that falls outside quotes and by nothing else — the reason a naive `split` reads
+ * a table with one multi-line cell as two broken rows.
+ *
+ * A trailing newline does not produce an empty final row; an empty line in the middle does produce
+ * a row with one empty cell, because that is what the file says.
+ */
+export declare function parseCsv(text: string): string[][];

package/dist/shared/csv/csv.js

@@ -0,0 +1,85 @@
+// The one CSV reader and writer in Intel. A table's canonical body is CSV (#40), and every surface
+// that has to look inside one — the grid, the column check, the search index — goes through here so
+// none of them can grow a private opinion about quoting.
+//
+// RFC 4180 with two deliberate narrowings: rows are separated by `\n` when written (a reader
+// accepts `\r\n` too), and a field is quoted only when it has to be. Nothing else is escaped,
+// because CSV has no escapes — a quote inside a quoted field is written twice.
+function needsQuoting(cell) {
+    return (cell.includes(",") ||
+        cell.includes('"') ||
+        cell.includes("\n") ||
+        cell.includes("\r") ||
+        cell !== cell.trim());
+}
+export function encodeCsvRow(cells) {
+    return cells
+        .map((cell) => (needsQuoting(cell) ? `"${cell.replaceAll('"', '""')}"` : cell))
+        .join(",");
+}
+export function encodeCsv(rows) {
+    return rows.length === 0 ? "" : `${rows.map(encodeCsvRow).join("\n")}\n`;
+}
+/**
+ * Every row of a CSV body, quoted fields included.
+ *
+ * ⚠️ A quoted field may contain a line break, so this cannot split on `\n` first. A row is closed
+ * by a line break that falls outside quotes and by nothing else — the reason a naive `split` reads
+ * a table with one multi-line cell as two broken rows.
+ *
+ * A trailing newline does not produce an empty final row; an empty line in the middle does produce
+ * a row with one empty cell, because that is what the file says.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let cell = "";
+    let quoted = false;
+    let started = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (quoted) {
+            if (character === '"') {
+                if (text[index + 1] === '"') {
+                    cell += '"';
+                    index += 1;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else {
+                cell += character;
+            }
+            continue;
+        }
+        if (character === '"' && cell === "") {
+            quoted = true;
+            started = true;
+            continue;
+        }
+        if (character === ",") {
+            row.push(cell);
+            cell = "";
+            started = true;
+            continue;
+        }
+        if (character === "\n" || character === "\r") {
+            if (character === "\r" && text[index + 1] === "\n")
+                index += 1;
+            row.push(cell);
+            rows.push(row);
+            row = [];
+            cell = "";
+            started = false;
+            continue;
+        }
+        cell += character;
+        started = true;
+    }
+    if (started || cell !== "" || row.length > 0) {
+        row.push(cell);
+        rows.push(row);
+    }
+    return rows;
+}