@anchrd/intel-api 0.21.0 → 0.22.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -1,4 +1,5 @@
 import { createGateClient } from "@anchrd/gate-sdk";
+import { serverOf } from "@anchrd/intel-contract/tool";
 import { ulid } from "ulid";
 import { createBrowserAuth } from "../../auth/auth.js";
 import { createBundle } from "../../bundle/bundle.js";
@@ -156,13 +157,60 @@ export default {
             // requirements list and every tree link of every run read this one answer, so none of
             // them can be kinder than the others.
             visibleNodes: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
-            toolFingerprint: async (actor, toolName) => {
+            /**
+             * ⚠️ The fingerprint of a whole SURFACE, not of one tool (#489). A step names a server and
+             * optionally the functions of it it may use, so what publishing freezes is that set — every
+             * covered function's own fingerprint, sorted so the order the portal happens to answer in
+             * cannot change the result, and hashed into one value.
+             *
+             * `null` in three cases, and all three have to refuse a publish: the catalog is unreachable,
+             * the server offers this user nothing, or a function the step explicitly allows is gone. The
+             * last one matters most — a narrowed step whose function disappeared is not a step that may
+             * quietly fall back to the rest of the server.
+             */
+            toolSurfaceFingerprint: async (actor, server, allow) => {
                 const catalog = await tools
                     .catalog({ id: actor.id, email: actor.email, canExecute: true })
                     .catch(() => null);
-                return catalog?.items.find((item) => item.name === toolName)?.fingerprint ?? null;
+                if (!catalog)
+                    return null;
+                const reachable = new Map(catalog.items.map((item) => [item.name, item.fingerprint]));
+                const covered = allow === null
+                    ? [...reachable.keys()].filter((name) => serverOf(name, [server]) !== null)
+                    : allow;
+                if (covered.length === 0)
+                    return null;
+                const parts = [];
+                for (const name of [...new Set(covered)].sort()) {
+                    const fingerprint = reachable.get(name);
+                    if (!fingerprint)
+                        return null;
+                    parts.push(`${name}:${fingerprint}`);
+                }
+                // ⚠️ The handle and the narrowing mode are part of what is hashed, not just the covered
+                // functions. Without them two different surfaces could collide: a server whose only
+                // function is allowed explicitly would hash the same as the same server left open, and the
+                // difference between "this one function" and "whatever this server offers" is exactly what
+                // publishing is meant to freeze.
+                const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode([server, allow === null ? "*" : "allow", ...parts].join("\n")));
+                return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+            },
+            // Which of the named servers this user does NOT reach. A server is reached when the live
+            // catalog carries at least one function of it — the same live answer the tool surface uses,
+            // never a mirrored table.
+            // ⚠️ The catalog error is NOT caught here, and that is the whole point. Answering an
+            // unreadable portal with "all of them are missing" turns an outage into a sentence about
+            // PERMISSIONS — the reader goes asking for access they already have, while the portal is
+            // simply down. `tools.catalog` already tells the two apart (`tool_catalog_unreadable`,
+            // `portal_not_connected`), and letting that answer through is the same rule the tool surface
+            // keeps one screen up: a sentence more specific than the evidence sends the reader looking in
+            // the wrong place.
+            unavailableServers: async (actor, servers) => {
+                if (servers.length === 0)
+                    return [];
+                const catalog = await tools.catalog({ id: actor.id, email: actor.email, canExecute: true });
+                return servers.filter((server) => !catalog.items.some((item) => serverOf(item.name, [server]) !== null));
             },
-            unavailableTools: async (actor, toolNames) => await tools.unavailable({ id: actor.id, email: actor.email, canExecute: true }, toolNames),
         });
         return await createIntel({
             baseUrl: env.INTEL_URL,

package/dist/flows/flows.d.ts

@@ -23,14 +23,18 @@ export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
 export declare function resourceIdOf(node: TreeLinkNode): string;
 export declare function calleeIds(graph: FlowGraph): string[];
 /**
- * The documents a graph names and the tools it calls, flattened and without repetition.
+ * The documents a graph names and the tool SERVERS it reaches for, flattened and without repetition.
  * The requirements list, the publish-time check and the run's first tool check read this one answer,
  * so they cannot disagree about what a flow touches. A caller that needs to know *which step* names
  * a document reads the node lists above instead — the relation graph draws exactly that edge.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
  */
 export declare function graphReferences(graph: FlowGraph): {
     nodes: string[];
-    tools: string[];
+    servers: string[];
 };
 export declare function compileFlow(graph: FlowGraph): CompiledFlow;
 export declare function createFlows(deps: FlowDeps): FlowService;

package/dist/flows/flows.js

@@ -46,24 +46,28 @@ export function calleeIds(graph) {
     return ids;
 }
 /**
- * The documents a graph names and the tools it calls, flattened and without repetition.
+ * The documents a graph names and the tool SERVERS it reaches for, flattened and without repetition.
  * The requirements list, the publish-time check and the run's first tool check read this one answer,
  * so they cannot disagree about what a flow touches. A caller that needs to know *which step* names
  * a document reads the node lists above instead — the relation graph draws exactly that edge.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
  */
 export function graphReferences(graph) {
     const nodes = [];
-    const tools = [];
+    const servers = [];
     for (const node of treeLinkNodes(graph)) {
         if (!nodes.includes(node.configuration.resourceId)) {
             nodes.push(node.configuration.resourceId);
         }
     }
     for (const node of toolNodes(graph)) {
-        if (!tools.includes(node.configuration.toolName))
-            tools.push(node.configuration.toolName);
+        if (!servers.includes(node.configuration.server))
+            servers.push(node.configuration.server);
     }
-    return { nodes, tools };
+    return { nodes, servers };
 }
 // ⚠️ The reason, in the words the person can act on, and not one word more. How many documents a
 // step cannot reach is something they may know; which ones they are is the very thing the ACL is
@@ -76,10 +80,14 @@ function treeLinkStepDetail(label, missing) {
 // ⚠️ For tools this is the only honest moment there is. The catalog is a live tools/list with the
 // requesting user's own token (ADR-0003), so nobody can be told in advance what someone else would
 // see — but the person in front of the failure can be told exactly where to go.
+// ⚠️ Servers, not tools, since #489 — and the sentence says so. A step names a server, so a person
+// told "you do not have access to this tool: notion" would go looking for a function by that name
+// and find none. What they can act on is the server: it is what the portal grants and what they can
+// ask to be granted.
 function toolStepDetail(missing) {
     return missing.length === 1
-        ? `You do not have access to this tool in the portal: ${missing.join(", ")}`
-        : `You do not have access to these tools in the portal: ${missing.join(", ")}`;
+        ? `You do not reach this tool server in the portal: ${missing.join(", ")}`
+        : `You do not reach these tool servers in the portal: ${missing.join(", ")}`;
 }
 export function compileFlow(graph) {
     const nodes = new Map();
@@ -439,11 +447,11 @@ export function createFlows(deps) {
         // The one consequence to know about: `start` throws the FIRST entry, so it now names the first
         // missing tool rather than all of them — the same as it has always done for several
         // unpublished sub-flows below. `validate` is what lists every reason at once, and it does.
-        for (const tool of await deps.unavailableTools(actor, graphReferences(version.graph).tools)) {
+        for (const server of await deps.unavailableServers(actor, graphReferences(version.graph).servers)) {
             problems.push({
                 status: 403,
                 code: "flow_tools_unavailable",
-                detail: toolStepDetail([tool]),
+                detail: toolStepDetail([server]),
             });
         }
         try {
@@ -597,12 +605,12 @@ export function createFlows(deps) {
     async function requireToolsAuthorized(actor, node, graph) {
         if (!node)
             return;
-        const toolNames = attachedNodes(node, graph)
+        const servers = attachedNodes(node, graph)
             .filter((candidate) => candidate.kind === "tool")
-            .map((candidate) => candidate.configuration.toolName);
-        if (!toolNames.length)
+            .map((candidate) => candidate.configuration.server);
+        if (!servers.length)
             return;
-        const missing = await deps.unavailableTools(actor, [...new Set(toolNames)]);
+        const missing = await deps.unavailableServers(actor, [...new Set(servers)]);
         if (missing.length) {
             throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
         }
@@ -773,6 +781,19 @@ export function createFlows(deps) {
         let changed = false;
         const nodes = [];
         for (const node of graph.nodes) {
+            // A tool step is frozen the same way a sub-flow call is: what it may reach is pinned at the
+            // moment of publishing (#489). The check above has already refused an unreachable server and
+            // a surface that moved since a previous publish, so this only writes down what it confirmed.
+            if (node.kind === "tool") {
+                const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
+                if (fingerprint !== null && fingerprint !== node.configuration.fingerprint) {
+                    nodes.push({ ...node, configuration: { ...node.configuration, fingerprint } });
+                    changed = true;
+                    continue;
+                }
+                nodes.push(node);
+                continue;
+            }
             if (node.kind !== "subflow") {
                 nodes.push(node);
                 continue;
@@ -1085,7 +1106,7 @@ export function createFlows(deps) {
                     versionId: null,
                     nodes: [],
                     hiddenNodes: 0,
-                    tools: [],
+                    servers: [],
                 };
             }
             const version = await requireVersion(versionId, flow.id);
@@ -1101,7 +1122,7 @@ export function createFlows(deps) {
                 versionId: version.id,
                 nodes: reachable,
                 hiddenNodes: referenced.nodes.length - reachable.length,
-                tools: referenced.tools,
+                servers: referenced.servers,
             };
         },
         async create(actor, input) {
@@ -1311,11 +1332,24 @@ export function createFlows(deps) {
             }
             for (const node of version.graph.nodes) {
                 if (node.kind === "tool") {
-                    const fingerprint = await deps.toolFingerprint(actor, node.configuration.toolName);
+                    // ⚠️ The fingerprint covers the whole surface this step may use — the server and, when
+                    // the step narrows it, exactly those functions with their schemas (#489). Freezing one
+                    // function was enough while a step named one; a step that may use any function of a
+                    // server would otherwise silently inherit functions the provider added AFTER publishing.
+                    const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
                     if (!fingerprint) {
-                        throw new IntelError(409, "flow_tool_unavailable", `Tool is unavailable: ${node.label}`);
+                        throw new IntelError(409, "flow_tool_unavailable", `Tool server is unavailable: ${node.label}`);
                     }
-                    if (node.configuration.fingerprint !== fingerprint) {
+                    // ⚠️ A step that has never been published carries no fingerprint, and that is not a
+                    // mismatch — it is the state every draft starts in. Publishing is what FREEZES the
+                    // surface, exactly as it turns a `latest` sub-flow call into a pinned one, and `freeze`
+                    // below writes the value in.
+                    //
+                    // Demanding it up front would mean the editor had to produce it, and nothing hands it
+                    // one: the value is derived from the asking user's own live catalog. Requiring it would
+                    // make every tool step unpublishable rather than safe.
+                    if (node.configuration.fingerprint !== null &&
+                        node.configuration.fingerprint !== fingerprint) {
                         throw new IntelError(409, "flow_tool_schema_changed", `Review the current schema before publishing: ${node.label}`);
                     }
                 }

package/dist/flows/flows.types.d.ts

@@ -209,8 +209,8 @@ export interface FlowDeps {
      * kinder than the door it describes — which is what #17 and #19 were sent back for.
      */
     visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
-    toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
-    unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
+    toolSurfaceFingerprint(actor: FlowActor, server: string, allow: string[] | null): Promise<string | null>;
+    unavailableServers(actor: FlowActor, servers: string[]): Promise<string[]>;
 }
 export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
 export interface FlowService {

package/dist/tools/tools.js

@@ -203,11 +203,5 @@ export function createTools(deps) {
             }
             return await call(actor, input);
         },
-        async unavailable(actor, names) {
-            if (names.length === 0)
-                return [];
-            const available = new Set((await capabilities(actor)).map((capability) => capability.name));
-            return names.filter((name) => !available.has(name));
-        },
     };
 }

package/dist/tools/tools.types.d.ts

@@ -53,5 +53,4 @@ export interface ToolService {
     servers(actor: ToolActor): Promise<ToolServerCatalog>;
     execute(actor: ToolActor, input: ExecuteToolInput): Promise<ToolTestResult>;
     test(actor: ToolActor, input: TestToolInput): Promise<ToolTestResult>;
-    unavailable(actor: ToolActor, names: string[]): Promise<string[]>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.15.0",
-    "@anchrd/intel-contract": "^0.17.0",
+    "@anchrd/intel-contract": "^0.18.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",