@anchrd/intel-ui 0.3.0 → 0.5.0

package/src/components/ui/tooltip.tsx

@@ -0,0 +1,51 @@
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import type * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-balance text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

package/src/data/intel-data-provider/intel-data-provider.ts

@@ -1,27 +1,37 @@
 import {
+  AppendKnowledgeTableRowsInput,
+  AppendKnowledgeTableRowsResult,
   ArchiveKnowledgeNodeInput,
   CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateKnowledgeLinkInput,
   CreateKnowledgeNodeInput,
-  DeleteKnowledgeLinkInput,
+  DefineKnowledgeTableInput,
   Flow,
   FlowDocument,
   FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowRunHistory,
+  FlowRunList,
   FlowRunStep,
   KnowledgeDocument,
   KnowledgeGraph,
-  KnowledgeLink,
   KnowledgeLinkList,
   KnowledgeNode,
   KnowledgeNodeList,
+  KnowledgeTable,
   KnowledgeVersionList,
+  ListFlowRunsInput,
+  ListFlowsInput,
   ListKnowledgeNodesInput,
+  PreviewFlowPublishInput,
   ProblemDetails,
   PublishFlowInput,
-  ResourceGrant,
+  RelationGraph,
+  RelationGraphInput,
+  ResolveKnowledgeLinksInput,
+  ResolveKnowledgeLinksResult,
   ResourceGrantList,
-  RevokeFlowGrantInput,
   RevokeGrantResult,
   RevokeKnowledgeGrantInput,
   SaveFlowVersionInput,
@@ -29,31 +39,50 @@ import {
   SaveKnowledgeVersionInput,
   SearchKnowledgeInput,
   SearchKnowledgeResult,
-  ShareFlowInput,
+  SessionUser,
   ShareKnowledgeInput,
+  ShareKnowledgeResult,
   StartFlowRunInput,
-  TestToolInput,
   ToolCatalog,
-  ToolTestResult,
+  UpdateFlowInput,
   UpdateKnowledgeNodeInput,
 } from "@anchrd/intel-contract";
-import { z } from "zod";
-import type { IntelDataProvider, KnowledgeTreeNode } from "./intel-data-provider.types.ts";
+import type { z } from "zod";
+import type { IntelDataProvider, TreeEntry } from "./intel-data-provider.types.ts";
 
-const DeleteResult = z.strictObject({ deleted: z.boolean() });
+// ⚠️ The refusal's `code`, not only its prose. A view that has to tell four different refusals
+// apart — "you may not write there", "that is not a folder", "that would be a cycle", "someone
+// else changed it" — cannot do so from `detail`, which is a sentence the server is free to
+// reword. The code is the contract (`ProblemDetails.code`); the message stays what it was.
+export class IntelRequestError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string | null,
+    message: string,
+  ) {
+    super(message);
+    this.name = "IntelRequestError";
+  }
+}
 
 // Attachment uploads and downloads share this budget, so it is generous rather than snappy.
 const RequestTimeoutMs = 60_000;
 
-// Deeper nesting than this is not a tree anyone navigates; the limit exists to bound the request
-// fan-out on first paint, not to express a product rule.
-const MaxTreeDepth = 12;
-
 // The Worker serves the login route, so the path belongs to the data layer rather than to any view.
 export function loginPath(returnTo?: string): string {
   return returnTo ? `/auth/login?returnTo=${encodeURIComponent(returnTo)}` : "/auth/login";
 }
 
+/**
+ * One flow as one row of the tree. Two levels show flows — the contents of a folder, and what an
+ * expanded flow calls — and they are two lists of the same rows, so they are built here once. Two
+ * copies of this would keep returning something plausible and slowly stop agreeing on what a flow
+ * row is (#30).
+ */
+export function flowEntry(flow: Flow): TreeEntry {
+  return { type: "flow", id: flow.id, title: flow.title, kind: "flow", flow };
+}
+
 export function createIntelDataProvider(
   deps: { fetch?: typeof fetch; baseUrl?: string; onUnauthorized?(): void } = {},
 ): IntelDataProvider {
@@ -89,7 +118,9 @@ export function createIntelDataProvider(
           .json()
           .catch(() => null),
       );
-      throw new Error(
+      throw new IntelRequestError(
+        result.status,
+        parsed.success ? (parsed.data.code ?? null) : null,
         parsed.success
           ? (parsed.data.detail ?? parsed.data.title)
           : `Intel responded with ${result.status}`,
@@ -106,6 +137,17 @@ export function createIntelDataProvider(
     return schema.parse(await (await response(path, init)).json());
   }
 
+  async function listFlows(input: ListFlowsInput = {}): Promise<z.infer<typeof FlowList>> {
+    const query = ListFlowsInput.parse(input);
+    // The parameter is only sent when the caller asked for one folder. Sending an empty one for
+    // "everything" would ask the server for the root instead.
+    const params = new URLSearchParams(
+      query.parentId === undefined ? {} : { parentId: query.parentId ?? "" },
+    );
+    const search = params.toString();
+    return await request(`/flows${search ? `?${search}` : ""}`, FlowList);
+  }
+
   async function listKnowledge(
     input: Partial<ListKnowledgeNodesInput> = {},
   ): Promise<z.infer<typeof KnowledgeNodeList>> {
@@ -115,31 +157,37 @@ export function createIntelDataProvider(
     return await request(`/knowledge?${params}`, KnowledgeNodeList);
   }
 
-  // One request per folder, so a deep tree is an N+1 on the first paint. The depth limit bounds that
-  // and, more importantly, makes a cyclic parentId impossible to hang on: without it a cycle would
-  // recurse until the tab dies. `seen` stops a cycle at the first repeat rather than at the limit.
-  async function loadChildren(
-    parentId: string | null,
-    depth = 0,
-    seen: ReadonlySet<string> = new Set(),
-  ): Promise<KnowledgeTreeNode[]> {
-    if (depth >= MaxTreeDepth) return [];
-    const { items } = await listKnowledge({ parentId });
-    return await Promise.all(
-      items.map(async (node) => ({
-        ...node,
-        children:
-          node.kind === "folder" && !seen.has(node.id)
-            ? await loadChildren(node.id, depth + 1, new Set([...seen, node.id]))
-            : [],
-      })),
-    );
-  }
-
   return {
+    async getSession() {
+      return await request("/session", SessionUser);
+    },
     listKnowledge,
-    async loadKnowledgeTree() {
-      return await loadChildren(null);
+    async listTreeChildren(parentId) {
+      // Both sides of one folder, asked for in parallel and merged here rather than on the server:
+      // the folder is shared, the two records are not, and no endpoint may return a row that is a
+      // bit of both (ADR-0004).
+      const [knowledge, flows] = await Promise.all([
+        listKnowledge({ parentId }),
+        listFlows({ parentId }),
+      ]);
+      const entries: TreeEntry[] = [
+        ...knowledge.items.map((node) => ({
+          type: "knowledge" as const,
+          id: node.id,
+          title: node.title,
+          kind: node.kind,
+          node,
+        })),
+        ...flows.items.map(flowEntry),
+      ];
+      // Folders first, then everything else by title: a document and a flow sit side by side, and
+      // the icon is what tells them apart.
+      return entries.sort(
+        (left, right) =>
+          Number(right.kind === "folder") - Number(left.kind === "folder") ||
+          left.title.localeCompare(right.title) ||
+          left.id.localeCompare(right.id),
+      );
     },
     async getKnowledge(nodeId) {
       return await request(`/knowledge/${encodeURIComponent(nodeId)}`, KnowledgeDocument);
@@ -156,21 +204,13 @@ export function createIntelDataProvider(
     async listKnowledgeLinks(nodeId) {
       return await request(`/knowledge/${encodeURIComponent(nodeId)}/links`, KnowledgeLinkList);
     },
-    async createKnowledgeLink(input) {
-      const parsed = CreateKnowledgeLinkInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.sourceNodeId)}/links`,
-        KnowledgeLink,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
-    },
-    async deleteKnowledgeLink(input) {
-      const parsed = DeleteKnowledgeLinkInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.sourceNodeId)}/links/${encodeURIComponent(parsed.linkId)}/revoke`,
-        DeleteResult,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    // ⚠️ POST, not GET. The identifiers of the documents a text links to belong in a body: a
+    // query string of them would end up in logs and referrers.
+    async resolveKnowledgeLinks(input) {
+      return await request("/knowledge/links/resolve", ResolveKnowledgeLinksResult, {
+        method: "POST",
+        body: JSON.stringify(ResolveKnowledgeLinksInput.parse(input)),
+      });
     },
     async saveKnowledge(input) {
       const parsed = SaveKnowledgeVersionInput.parse(input);
@@ -191,6 +231,28 @@ export function createIntelDataProvider(
     async getKnowledgeAttachment(nodeId) {
       return await (await response(`/knowledge/${encodeURIComponent(nodeId)}/attachment`)).blob();
     },
+    async getKnowledgeTable(nodeId) {
+      return await request(`/knowledge/${encodeURIComponent(nodeId)}/table`, KnowledgeTable);
+    },
+    async defineKnowledgeTable(input) {
+      const parsed = DefineKnowledgeTableInput.parse(input);
+      return await request(
+        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table`,
+        KnowledgeTable,
+        {
+          method: "POST",
+          body: JSON.stringify(parsed),
+        },
+      );
+    },
+    async appendKnowledgeTableRows(input) {
+      const parsed = AppendKnowledgeTableRowsInput.parse(input);
+      return await request(
+        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table/rows`,
+        AppendKnowledgeTableRowsResult,
+        { method: "POST", body: JSON.stringify(parsed) },
+      );
+    },
     async listKnowledgeVersions(nodeId) {
       return await request(
         `/knowledge/${encodeURIComponent(nodeId)}/versions`,
@@ -228,7 +290,7 @@ export function createIntelDataProvider(
       const parsed = ShareKnowledgeInput.parse(input);
       return await request(
         `/knowledge/${encodeURIComponent(parsed.resourceId)}/grants`,
-        ResourceGrant,
+        ShareKnowledgeResult,
         { method: "POST", body: JSON.stringify(parsed) },
       );
     },
@@ -240,39 +302,46 @@ export function createIntelDataProvider(
         { method: "POST", body: JSON.stringify(parsed) },
       );
     },
-    async listFlows() {
-      return await request("/flows", FlowList);
-    },
+    listFlows,
     async getFlow(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}`, FlowDocument);
     },
+    async listFlowCalls(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/calls`, FlowList);
+    },
+    async getRelationGraph(scope, limit) {
+      const parsed = RelationGraphInput.parse({
+        scope,
+        ...(limit === undefined ? {} : { limit }),
+      });
+      const params = new URLSearchParams({
+        of: parsed.scope.of,
+        limit: String(parsed.limit),
+        // A folder scope without an ID is the root of the shared tree, and an absent parameter is
+        // how that is said — the same distinction `/flows?parentId=` makes.
+        ...(parsed.scope.of === "flow"
+          ? { flowId: parsed.scope.flowId }
+          : parsed.scope.folderId
+            ? { folderId: parsed.scope.folderId }
+            : {}),
+      });
+      return await request(`/flows/graph?${params}`, RelationGraph);
+    },
+    async getFlowRequirements(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/requirements`, FlowRequirements);
+    },
     async createFlow(input) {
       return await request("/flows", Flow, {
         method: "POST",
         body: JSON.stringify(CreateFlowInput.parse(input)),
       });
     },
-    async listFlowGrants(flowId) {
-      return await request(`/flows/${encodeURIComponent(flowId)}/grants`, ResourceGrantList);
-    },
-    async shareFlow(input) {
-      const parsed = ShareFlowInput.parse(input);
-      return await request(
-        `/flows/${encodeURIComponent(parsed.resourceId)}/grants`,
-        ResourceGrant,
-        {
-          method: "POST",
-          body: JSON.stringify(parsed),
-        },
-      );
-    },
-    async revokeFlowGrant(input) {
-      const parsed = RevokeFlowGrantInput.parse(input);
-      return await request(
-        `/flows/${encodeURIComponent(parsed.resourceId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
-        RevokeGrantResult,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    async updateFlow(input) {
+      const parsed = UpdateFlowInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}`, Flow, {
+        method: "PATCH",
+        body: JSON.stringify(parsed),
+      });
     },
     async saveFlow(input) {
       const parsed = SaveFlowVersionInput.parse(input);
@@ -281,6 +350,13 @@ export function createIntelDataProvider(
         body: JSON.stringify(parsed),
       });
     },
+    async previewFlowPublish(input) {
+      const parsed = PreviewFlowPublishInput.parse(input);
+      return await request(
+        `/flows/${encodeURIComponent(parsed.flowId)}/versions/${encodeURIComponent(parsed.versionId)}/publish-preview`,
+        FlowPublishPreview,
+      );
+    },
     async publishFlow(input) {
       const parsed = PublishFlowInput.parse(input);
       return await request(`/flows/${encodeURIComponent(parsed.flowId)}/publish`, Flow, {
@@ -295,9 +371,24 @@ export function createIntelDataProvider(
         body: JSON.stringify(parsed),
       });
     },
+    async listFlowRuns(input) {
+      const parsed = ListFlowRunsInput.parse(input);
+      // Only what was actually asked for travels. `failedOnly` is the parameter's presence rather
+      // than a value, which is the same shape the server reads it back with.
+      const params = new URLSearchParams({ limit: String(parsed.limit) });
+      if (parsed.failedOnly) params.set("failedOnly", "");
+      if (parsed.cursor) params.set("cursor", parsed.cursor);
+      return await request(
+        `/flows/${encodeURIComponent(parsed.flowId)}/runs?${params}`,
+        FlowRunList,
+      );
+    },
     async getFlowRun(runId) {
       return await request(`/flow-runs/${encodeURIComponent(runId)}`, FlowRunStep);
     },
+    async getFlowRunSteps(runId) {
+      return await request(`/flow-runs/${encodeURIComponent(runId)}/steps`, FlowRunHistory);
+    },
     async completeFlowStep(input) {
       const parsed = CompleteFlowRunStepInput.parse(input);
       return await request(`/flow-runs/${encodeURIComponent(parsed.runId)}/complete`, FlowRunStep, {
@@ -308,12 +399,6 @@ export function createIntelDataProvider(
     async listTools() {
       return await request("/tools", ToolCatalog);
     },
-    async testTool(input) {
-      return await request("/tools/test", ToolTestResult, {
-        method: "POST",
-        body: JSON.stringify(TestToolInput.parse(input)),
-      });
-    },
 
     portalConnectUrl(returnTo = "/tools") {
       return `${baseUrl}/auth/connect?returnTo=${encodeURIComponent(returnTo)}`;

package/src/data/intel-data-provider/intel-data-provider.types.ts

@@ -1,26 +1,37 @@
 import type {
+  AppendKnowledgeTableRowsInput,
+  AppendKnowledgeTableRowsResult,
   ArchiveKnowledgeNodeInput,
   CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateKnowledgeLinkInput,
   CreateKnowledgeNodeInput,
-  DeleteKnowledgeLinkInput,
+  DefineKnowledgeTableInput,
   Flow,
   FlowDocument,
   FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowRunHistory,
+  FlowRunList,
   FlowRunStep,
   KnowledgeDocument,
   KnowledgeGraph,
-  KnowledgeLink,
   KnowledgeLinkList,
   KnowledgeNode,
+  KnowledgeNodeKind,
   KnowledgeNodeList,
+  KnowledgeTable,
   KnowledgeVersionList,
+  ListFlowRunsInput,
+  ListFlowsInput,
   ListKnowledgeNodesInput,
+  PreviewFlowPublishInput,
   PublishFlowInput,
-  ResourceGrant,
+  RelationGraph,
+  RelationGraphScope,
+  ResolveKnowledgeLinksInput,
+  ResolveKnowledgeLinksResult,
   ResourceGrantList,
-  RevokeFlowGrantInput,
   RevokeGrantResult,
   RevokeKnowledgeGrantInput,
   SaveFlowVersionInput,
@@ -28,51 +39,84 @@ import type {
   SaveKnowledgeVersionInput,
   SearchKnowledgeInput,
   SearchKnowledgeResult,
-  ShareFlowInput,
+  SessionUser,
   ShareKnowledgeInput,
+  ShareKnowledgeResult,
   StartFlowRunInput,
-  TestToolInput,
   ToolCatalog,
-  ToolTestResult,
+  UpdateFlowInput,
   UpdateKnowledgeNodeInput,
 } from "@anchrd/intel-contract";
 
-export interface KnowledgeTreeNode extends KnowledgeNode {
-  children: KnowledgeTreeNode[];
-}
+// One row of the shared tree. Knowledge and Flows share the folder, not their nature (ADR-0004), so
+// this is a union that keeps each side's record whole — never a merged "node" that is a bit of both.
+export type TreeEntry =
+  | { type: "knowledge"; id: string; title: string; kind: KnowledgeNodeKind; node: KnowledgeNode }
+  | { type: "flow"; id: string; title: string; kind: "flow"; flow: Flow };
 
 export interface IntelDataProvider {
+  getSession(): Promise<SessionUser>;
   listKnowledge(input?: Partial<ListKnowledgeNodesInput>): Promise<KnowledgeNodeList>;
-  loadKnowledgeTree(): Promise<KnowledgeTreeNode[]>;
+  // One level of the shared tree: the documents and the flows filed in the same folder, in one
+  // sorted list. Per level rather than recursive, so opening a folder is what costs a request.
+  listTreeChildren(parentId: string | null): Promise<TreeEntry[]>;
   getKnowledge(nodeId: string): Promise<KnowledgeDocument>;
   createKnowledge(input: CreateKnowledgeNodeInput): Promise<KnowledgeNode>;
   getKnowledgeGraph(limit?: number): Promise<KnowledgeGraph>;
   listKnowledgeLinks(nodeId: string): Promise<KnowledgeLinkList>;
-  createKnowledgeLink(input: CreateKnowledgeLinkInput): Promise<KnowledgeLink>;
-  deleteKnowledgeLink(input: DeleteKnowledgeLinkInput): Promise<{ deleted: boolean }>;
+  // The titles of the documents a text links to, for the reader. A target they may not see, or one
+  // that is gone, is absent from the answer — the two look the same on purpose (#41).
+  resolveKnowledgeLinks(input: ResolveKnowledgeLinksInput): Promise<ResolveKnowledgeLinksResult>;
   saveKnowledge(input: SaveKnowledgeVersionInput): Promise<KnowledgeDocument>;
   saveKnowledgeAttachment(input: SaveKnowledgeAttachmentInput): Promise<KnowledgeDocument>;
   getKnowledgeAttachment(nodeId: string): Promise<Blob>;
+  // A table as columns and rows. The CSV stays canonical — `getKnowledge` still answers with it,
+  // which is what the download uses — and this is the same bytes read by the server's one reader.
+  getKnowledgeTable(nodeId: string): Promise<KnowledgeTable>;
+  defineKnowledgeTable(input: DefineKnowledgeTableInput): Promise<KnowledgeTable>;
+  appendKnowledgeTableRows(
+    input: AppendKnowledgeTableRowsInput,
+  ): Promise<AppendKnowledgeTableRowsResult>;
   portalConnectUrl(returnTo?: string): string;
   listKnowledgeVersions(nodeId: string): Promise<KnowledgeVersionList>;
   updateKnowledge(input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode>;
   archiveKnowledge(input: ArchiveKnowledgeNodeInput): Promise<KnowledgeNode>;
   searchKnowledge(input: SearchKnowledgeInput): Promise<SearchKnowledgeResult>;
   listKnowledgeGrants(resourceId: string): Promise<ResourceGrantList>;
-  shareKnowledge(input: ShareKnowledgeInput): Promise<ResourceGrant>;
+  // The grant, and what the grant does not cover: the documents the flows in this folder read that
+  // the new principal still cannot. A warning, never a refusal (ADR-0004 §4).
+  shareKnowledge(input: ShareKnowledgeInput): Promise<ShareKnowledgeResult>;
   revokeKnowledgeGrant(input: RevokeKnowledgeGrantInput): Promise<RevokeGrantResult>;
-  listFlows(): Promise<FlowList>;
+  listFlows(input?: ListFlowsInput): Promise<FlowList>;
   getFlow(flowId: string): Promise<FlowDocument>;
+  // What a flow calls, read out of its graph. It answers a different question from `listTreeChildren`
+  // and deliberately gives a different answer: a shared sub-flow is listed under every caller.
+  listFlowCalls(flowId: string): Promise<FlowList>;
+  // What accesses what, for one level of the shared tree: a folder for its contents, a flow for
+  // itself. ⚠️ Only nodes the signed-in user may see come back, and one they may not is absent
+  // altogether — never a placeholder, because the edge into one would already say that it exists.
+  getRelationGraph(scope: RelationGraphScope, limit?: number): Promise<RelationGraph>;
+  // What a flow touches: the documents and tools its graph names. Documents the signed-in user may
+  // not see are counted rather than named, and nothing here claims anybody may reach them.
+  getFlowRequirements(flowId: string): Promise<FlowRequirements>;
   createFlow(input: CreateFlowInput): Promise<Flow>;
-  listFlowGrants(flowId: string): Promise<ResourceGrantList>;
-  shareFlow(input: ShareFlowInput): Promise<ResourceGrant>;
-  revokeFlowGrant(input: RevokeFlowGrantInput): Promise<RevokeGrantResult>;
+  updateFlow(input: UpdateFlowInput): Promise<Flow>;
   saveFlow(input: SaveFlowVersionInput): Promise<FlowDocument>;
+  // Which version each sub-flow call will take once published, and which of them publishing
+  // freezes. Read before publishing, so the author agrees to the pins rather than discovering them.
+  previewFlowPublish(input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
   publishFlow(input: PublishFlowInput): Promise<Flow>;
   startFlow(input: StartFlowRunInput): Promise<FlowRunStep>;
+  // What this flow has done, newest first, one page at a time. ⚠️ It carries what a run did and
+  // never what it produced: a run reads Knowledge with the rights of whoever started it, so its
+  // result is not automatically readable for everyone who may read the flow.
+  listFlowRuns(input: ListFlowRunsInput): Promise<FlowRunList>;
   getFlowRun(runId: string): Promise<FlowRunStep>;
+  // The drill-down behind one run: every step it took, and the call chain it belongs to.
+  getFlowRunSteps(runId: string): Promise<FlowRunHistory>;
   completeFlowStep(input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
+  // Reading the catalog is the whole of the tool surface here: calling a tool belongs to a flow
+  // or to the Intel MCP surface, not to the screen that shows what the portal offers.
   listTools(): Promise<ToolCatalog>;
-  testTool(input: TestToolInput): Promise<ToolTestResult>;
   logout(): Promise<void>;
 }