@anchrd/intel-ui 0.8.8 → 0.9.0

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

@@ -1,12 +1,15 @@
 import {
-  AppendKnowledgeTableRowsInput,
-  AppendKnowledgeTableRowsResult,
+  AppendTableRowsInput,
+  AppendTableRowsResult,
   ArchiveFlowInput,
-  ArchiveKnowledgeNodeInput,
+  ArchiveNodeInput,
+  BundleImportResult,
   CompleteFlowRunStepInput,
+  CreateAgentInput,
+  CreatedAgent,
   CreateFlowInput,
-  CreateKnowledgeNodeInput,
-  DefineKnowledgeTableInput,
+  CreateNodeInput,
+  DefineTableInput,
   Flow,
   FlowDocument,
   FlowList,
@@ -16,40 +19,50 @@ import {
   FlowRunList,
   FlowRunStep,
   FlowValidation,
-  KnowledgeDocument,
-  KnowledgeGraph,
-  KnowledgeLinkList,
-  KnowledgeNode,
-  KnowledgeNodeList,
-  KnowledgeTable,
-  KnowledgeVersionList,
+  IntelCapabilities,
   ListFlowRunsInput,
   ListFlowsInput,
-  ListKnowledgeNodesInput,
+  ListNodesInput,
+  Node,
+  NodeAgent,
+  NodeDocument,
+  NodeGraph,
+  NodeLinkList,
+  NodeList,
+  NodeTable,
+  NodeVersionList,
   PreviewFlowPublishInput,
   ProblemDetails,
   PublishFlowInput,
   RelationGraph,
   RelationGraphInput,
-  ResolveKnowledgeLinksInput,
-  ResolveKnowledgeLinksResult,
+  ResolveNodeLinksInput,
+  ResolveNodeLinksResult,
   ResourceGrantList,
+  RevokeGrantInput,
   RevokeGrantResult,
-  RevokeKnowledgeGrantInput,
+  SaveAgentDefinitionInput,
+  SaveAttachmentInput,
   SaveFlowVersionInput,
-  SaveKnowledgeAttachmentInput,
-  SaveKnowledgeVersionInput,
-  SearchKnowledgeInput,
-  SearchKnowledgeResult,
+  SaveNodeVersionInput,
+  SearchInput,
+  SearchResult,
   SessionUser,
-  ShareKnowledgeInput,
-  ShareKnowledgeResult,
+  ShareInput,
+  ShareResult,
   StartFlowRunInput,
   ToolCatalog,
   UpdateFlowInput,
-  UpdateKnowledgeNodeInput,
+  UpdateNodeInput,
 } from "@anchrd/intel-contract";
 import type { z } from "zod";
+import {
+  AgentManualRun,
+  AgentRunDetail,
+  AgentRunList,
+  AgentState,
+  agentRuntimePath,
+} from "@/data/agent-runtime/agent-runtime.ts";
 import { createBrowserSignIn } from "@/data/sign-in/sign-in.ts";
 import type { IntelDataProvider, TreeEntry } from "./intel-data-provider.types.ts";
 
@@ -82,10 +95,10 @@ export function loginPath(returnTo?: string): string {
  * copies of this would keep returning something plausible and slowly stop agreeing on what a flow
  * row is (#30).
  */
-// ⚠️ `openable` ist hier voreingestellt falsch — genauer: unbekannt. Wer die Ebene kennt, setzt es
-// (`listTreeChildren`); wer nur eine einzelne Zeile baut, weiß es nicht und behauptet deshalb das
-// Zurückhaltendere. Ein Pfeil, der zu Unrecht fehlt, kostet einen Klick auf die Zeile; einer, der
-// zu Unrecht steht, kostet Vertrauen (#59).
+// ⚠️ `openable` defaults to false here — more precisely: unknown. Whoever knows the level sets it
+// (`listTreeChildren`); whoever only builds a single row does not know and therefore claims the
+// more reserved of the two. An arrow that is wrongly missing costs a click on the row; one that
+// is wrongly there costs trust (#59).
 export function flowEntry(flow: Flow, openable = false): TreeEntry {
   return { type: "flow", id: flow.id, title: flow.title, kind: "flow", openable, flow };
 }
@@ -170,39 +183,37 @@ export function createIntelDataProvider(
     return await request(`/flows${search ? `?${search}` : ""}`, FlowList);
   }
 
-  async function listKnowledge(
-    input: Partial<ListKnowledgeNodesInput> = {},
-  ): Promise<z.infer<typeof KnowledgeNodeList>> {
-    const query = ListKnowledgeNodesInput.parse(input);
+  async function listNodes(input: Partial<ListNodesInput> = {}): Promise<z.infer<typeof NodeList>> {
+    const query = ListNodesInput.parse(input);
     const params = new URLSearchParams({ includeArchived: String(query.includeArchived) });
     if (query.parentId !== null) params.set("parentId", query.parentId);
     // Only the asked-for case travels: `archivedOnly` overrides the folder on the server, so
     // sending it as `false` on every tree read would be noise on the one request it never applies
     // to (#113).
     if (query.archivedOnly) params.set("archivedOnly", "true");
-    return await request(`/knowledge?${params}`, KnowledgeNodeList);
+    return await request(`/nodes?${params}`, NodeList);
   }
 
   return {
     async getSession() {
       return await request("/session", SessionUser);
     },
-    listKnowledge,
+    async getCapabilities() {
+      return await request("/capabilities", IntelCapabilities);
+    },
+    listNodes,
     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 }),
-      ]);
-      // ⚠️ Beide Seiten sagen, welche ihrer Zeilen etwas zum Aufklappen haben (#59) — für DIESEN
-      // Leser. Der Baum weiß es damit beim Zeichnen, ohne die Ebene darunter vorzuladen: Das wäre
-      // ein Ladevorgang pro Zeile statt pro Ordner.
-      const openable = new Set([...knowledge.withChildren, ...flows.withCalls]);
+      const [nodes, flows] = await Promise.all([listNodes({ parentId }), listFlows({ parentId })]);
+      // ⚠️ Both sides say which of their rows have something to expand (#59) — for THIS reader.
+      // The tree therefore knows it while drawing, without preloading the level below: that would
+      // be one load per row instead of per folder.
+      const openable = new Set([...nodes.withChildren, ...flows.withCalls]);
       const entries: TreeEntry[] = [
-        ...knowledge.items.map((node) => ({
-          type: "knowledge" as const,
+        ...nodes.items.map((node) => ({
+          type: "node" as const,
           id: node.id,
           title: node.title,
           kind: node.kind,
@@ -220,115 +231,125 @@ export function createIntelDataProvider(
           left.id.localeCompare(right.id),
       );
     },
-    async getKnowledge(nodeId) {
-      return await request(`/knowledge/${encodeURIComponent(nodeId)}`, KnowledgeDocument);
+    async getNode(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}`, NodeDocument);
     },
-    async createKnowledge(input) {
-      return await request("/knowledge", KnowledgeNode, {
+    async createNodes(input) {
+      return await request("/nodes", Node, {
         method: "POST",
-        body: JSON.stringify(CreateKnowledgeNodeInput.parse(input)),
+        body: JSON.stringify(CreateNodeInput.parse(input)),
       });
     },
-    async getKnowledgeGraph(limit = 250) {
-      return await request(`/knowledge/graph?limit=${encodeURIComponent(limit)}`, KnowledgeGraph);
+    async getNodeGraph(limit = 250) {
+      return await request(`/nodes/graph?limit=${encodeURIComponent(limit)}`, NodeGraph);
     },
-    async listKnowledgeLinks(nodeId) {
-      return await request(`/knowledge/${encodeURIComponent(nodeId)}/links`, KnowledgeLinkList);
+    async listNodeLinks(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/links`, NodeLinkList);
     },
     // ⚠️ 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, {
+    async resolveNodeLinks(input) {
+      return await request("/nodes/links/resolve", ResolveNodeLinksResult, {
         method: "POST",
-        body: JSON.stringify(ResolveKnowledgeLinksInput.parse(input)),
+        body: JSON.stringify(ResolveNodeLinksInput.parse(input)),
       });
     },
-    async saveKnowledge(input) {
-      const parsed = SaveKnowledgeVersionInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.nodeId)}/versions`,
-        KnowledgeDocument,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    async saveNode(input) {
+      const parsed = SaveNodeVersionInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/versions`, NodeDocument, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
     },
-    async saveKnowledgeAttachment(input) {
-      const parsed = SaveKnowledgeAttachmentInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.nodeId)}/attachment`,
-        KnowledgeDocument,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    async saveNodeAttachment(input) {
+      const parsed = SaveAttachmentInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/attachment`, NodeDocument, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
     },
-    async getKnowledgeAttachment(nodeId) {
-      return await (await response(`/knowledge/${encodeURIComponent(nodeId)}/attachment`)).blob();
+    async getNodeAttachment(nodeId) {
+      return await (await response(`/nodes/${encodeURIComponent(nodeId)}/attachment`)).blob();
+    },
+    async exportNodeBundle(nodeId) {
+      const path =
+        nodeId === null ? "/nodes/export" : `/nodes/${encodeURIComponent(nodeId)}/export`;
+      return await (await response(path)).blob();
+    },
+    async exportFlowBundle(flowId) {
+      return await (await response(`/flows/${encodeURIComponent(flowId)}/export`)).blob();
+    },
+    // The body IS the zip, so the idempotency key travels as a header — the same reading the
+    // server does (#137).
+    async importNodeBundle(input) {
+      const path =
+        input.nodeId === null
+          ? "/nodes/import"
+          : `/nodes/${encodeURIComponent(input.nodeId)}/import`;
+      return await request(path, BundleImportResult, {
+        method: "POST",
+        body: input.zip,
+        headers: {
+          "content-type": "application/zip",
+          "idempotency-key": input.idempotencyKey,
+        },
+      });
     },
-    async getKnowledgeTable(nodeId) {
-      return await request(`/knowledge/${encodeURIComponent(nodeId)}/table`, KnowledgeTable);
+    async getNodeTable(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/table`, NodeTable);
     },
-    async defineKnowledgeTable(input) {
-      const parsed = DefineKnowledgeTableInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table`,
-        KnowledgeTable,
-        {
-          method: "POST",
-          body: JSON.stringify(parsed),
-        },
-      );
+    async defineTable(input) {
+      const parsed = DefineTableInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/table`, NodeTable, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
     },
-    async appendKnowledgeTableRows(input) {
-      const parsed = AppendKnowledgeTableRowsInput.parse(input);
+    async appendTableRows(input) {
+      const parsed = AppendTableRowsInput.parse(input);
       return await request(
-        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table/rows`,
-        AppendKnowledgeTableRowsResult,
+        `/nodes/${encodeURIComponent(parsed.nodeId)}/table/rows`,
+        AppendTableRowsResult,
         { method: "POST", body: JSON.stringify(parsed) },
       );
     },
-    async listKnowledgeVersions(nodeId) {
-      return await request(
-        `/knowledge/${encodeURIComponent(nodeId)}/versions`,
-        KnowledgeVersionList,
-      );
+    async listNodeVersions(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/versions`, NodeVersionList);
     },
-    async updateKnowledge(input) {
-      const parsed = UpdateKnowledgeNodeInput.parse(input);
-      return await request(`/knowledge/${encodeURIComponent(parsed.nodeId)}`, KnowledgeNode, {
+    async updateNode(input) {
+      const parsed = UpdateNodeInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}`, Node, {
         method: "PATCH",
         body: JSON.stringify(parsed),
       });
     },
-    async archiveKnowledge(input) {
-      const parsed = ArchiveKnowledgeNodeInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.nodeId)}/archive`,
-        KnowledgeNode,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    async archiveNode(input) {
+      const parsed = ArchiveNodeInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/archive`, Node, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
     },
-    async searchKnowledge(input) {
-      return await request("/knowledge/search", SearchKnowledgeResult, {
+    async searchNodes(input) {
+      return await request("/nodes/search", SearchResult, {
         method: "POST",
-        body: JSON.stringify(SearchKnowledgeInput.parse(input)),
+        body: JSON.stringify(SearchInput.parse(input)),
       });
     },
-    async listKnowledgeGrants(resourceId) {
-      return await request(
-        `/knowledge/${encodeURIComponent(resourceId)}/grants`,
-        ResourceGrantList,
-      );
+    async listGrants(resourceId) {
+      return await request(`/nodes/${encodeURIComponent(resourceId)}/grants`, ResourceGrantList);
     },
-    async shareKnowledge(input) {
-      const parsed = ShareKnowledgeInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.resourceId)}/grants`,
-        ShareKnowledgeResult,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    async shareNode(input) {
+      const parsed = ShareInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.resourceId)}/grants`, ShareResult, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
     },
-    async revokeKnowledgeGrant(input) {
-      const parsed = RevokeKnowledgeGrantInput.parse(input);
+    async revokeGrant(input) {
+      const parsed = RevokeGrantInput.parse(input);
       return await request(
-        `/knowledge/${encodeURIComponent(parsed.resourceId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
+        `/nodes/${encodeURIComponent(parsed.resourceId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
         RevokeGrantResult,
         { method: "POST", body: JSON.stringify(parsed) },
       );
@@ -440,6 +461,66 @@ export function createIntelDataProvider(
     async listTools() {
       return await request("/tools", ToolCatalog);
     },
+    async getAgent(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/agent`, NodeAgent);
+    },
+    // ⚠️ `CreatedAgent`, not `NodeAgent`: the create answer carries the Gate application key once
+    // (#182), and the read schema is strict — parsing this response with it would reject the one
+    // response in the product that has a credential in it.
+    async createAgent(input) {
+      return await request("/nodes/agents", CreatedAgent, {
+        method: "POST",
+        body: JSON.stringify(CreateAgentInput.parse(input)),
+      });
+    },
+    async saveAgentDefinition(input) {
+      const parsed = SaveAgentDefinitionInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/agent`, NodeAgent, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    /**
+     * The agent runtime, asked through intel (#178).
+     *
+     * ⚠️ Plain `request`, with no second origin and no bearer of its own — that is the whole change.
+     * The runtime used to be a Worker this page called directly, which meant CORS it does not
+     * answer and a Gate token the browser cannot have. Intel now proxies `/agents/:agentId/*` and
+     * attaches the caller's own token server-side, so a 401 from here really is intel's session
+     * expiring and the sign-in that follows is the right one.
+     *
+     * ⚠️ A 403 is NOT that. It means the reader may not drive agents, which the agent page renders
+     * as an answer rather than as a failure.
+     */
+    async listAgentRuns(agentId) {
+      return await request(agentRuntimePath(agentId, "/runs"), AgentRunList);
+    },
+    async getAgentRun(agentId, runId) {
+      return await request(
+        agentRuntimePath(agentId, `/runs/${encodeURIComponent(runId)}`),
+        AgentRunDetail,
+      );
+    },
+    async getAgentState(agentId) {
+      return await request(agentRuntimePath(agentId, "/state"), AgentState);
+    },
+    async pauseAgent(agentId) {
+      return await request(agentRuntimePath(agentId, "/pause"), AgentState, { method: "POST" });
+    },
+    async resumeAgent(agentId) {
+      return await request(agentRuntimePath(agentId, "/resume"), AgentState, { method: "POST" });
+    },
+    async runAgentNow(agentId, target) {
+      return await request(agentRuntimePath(agentId, "/run"), AgentManualRun, {
+        method: "POST",
+        body: JSON.stringify({ target }),
+      });
+    },
+    agentChatApi(agentId) {
+      // assistant-ui dials this itself, so it needs the path a browser can use — the same one every
+      // other call above goes to, intel's own `/api/v1`.
+      return `${baseUrl}/api/v1${agentRuntimePath(agentId, "/chat")}`;
+    },
 
     // The Worker serves the connect route, so this navigation belongs to the data layer for the
     // same reason `loginPath` does. `silent=1` is what makes it a redirect nobody has to watch.

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

@@ -1,12 +1,16 @@
 import type {
-  AppendKnowledgeTableRowsInput,
-  AppendKnowledgeTableRowsResult,
+  AgentScheduleTarget,
+  AppendTableRowsInput,
+  AppendTableRowsResult,
   ArchiveFlowInput,
-  ArchiveKnowledgeNodeInput,
+  ArchiveNodeInput,
+  BundleImportResult,
   CompleteFlowRunStepInput,
+  CreateAgentInput,
+  CreatedAgent,
   CreateFlowInput,
-  CreateKnowledgeNodeInput,
-  DefineKnowledgeTableInput,
+  CreateNodeInput,
+  DefineTableInput,
   Flow,
   FlowDocument,
   FlowList,
@@ -16,92 +20,114 @@ import type {
   FlowRunList,
   FlowRunStep,
   FlowValidation,
-  KnowledgeDocument,
-  KnowledgeGraph,
-  KnowledgeLinkList,
-  KnowledgeNode,
-  KnowledgeNodeKind,
-  KnowledgeNodeList,
-  KnowledgeTable,
-  KnowledgeVersionList,
+  IntelCapabilities,
   ListFlowRunsInput,
   ListFlowsInput,
-  ListKnowledgeNodesInput,
+  ListNodesInput,
+  Node,
+  NodeAgent,
+  NodeDocument,
+  NodeGraph,
+  NodeKind,
+  NodeLinkList,
+  NodeList,
+  NodeTable,
+  NodeVersionList,
   PreviewFlowPublishInput,
   PublishFlowInput,
   RelationGraph,
   RelationGraphScope,
-  ResolveKnowledgeLinksInput,
-  ResolveKnowledgeLinksResult,
+  ResolveNodeLinksInput,
+  ResolveNodeLinksResult,
   ResourceGrantList,
+  RevokeGrantInput,
   RevokeGrantResult,
-  RevokeKnowledgeGrantInput,
+  SaveAgentDefinitionInput,
+  SaveAttachmentInput,
   SaveFlowVersionInput,
-  SaveKnowledgeAttachmentInput,
-  SaveKnowledgeVersionInput,
-  SearchKnowledgeInput,
-  SearchKnowledgeResult,
+  SaveNodeVersionInput,
+  SearchInput,
+  SearchResult,
   SessionUser,
-  ShareKnowledgeInput,
-  ShareKnowledgeResult,
+  ShareInput,
+  ShareResult,
   StartFlowRunInput,
   ToolCatalog,
   UpdateFlowInput,
-  UpdateKnowledgeNodeInput,
+  UpdateNodeInput,
 } from "@anchrd/intel-contract";
+import type {
+  AgentManualRun,
+  AgentRunDetail,
+  AgentRunList,
+  AgentState,
+} from "@/data/agent-runtime/agent-runtime.ts";
 
-// One row of the shared tree. Knowledge and Flows share the folder, not their nature (ADR-0004), so
+// One row of the shared tree. Nodes 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.
-// ⚠️ `openable` heißt „hat etwas zum Aufklappen, das DIESER Leser sehen darf" (#59) — nicht „ist
-// von einer Art, die sich aufklappen lässt". Der Unterschied ist der ganze Sinn: Ein Pfeil an einer
-// Zeile, unter der nichts liegt, verspricht Inhalt, den das Aufklappen nicht liefert.
+// ⚠️ `openable` means "has something to expand that THIS reader may see" (#59) — not "is of a kind
+// that can be expanded". The difference is the whole point: an arrow on a row with nothing beneath
+// it promises content that expanding does not deliver.
 export type TreeEntry =
   | {
-      type: "knowledge";
+      type: "node";
       id: string;
       title: string;
-      kind: KnowledgeNodeKind;
+      kind: NodeKind;
       openable: boolean;
-      node: KnowledgeNode;
+      node: Node;
     }
   | { type: "flow"; id: string; title: string; kind: "flow"; openable: boolean; flow: Flow };
 
 export interface IntelDataProvider {
   getSession(): Promise<SessionUser>;
-  listKnowledge(input?: Partial<ListKnowledgeNodesInput>): Promise<KnowledgeNodeList>;
+  // What this installation is equipped to do (#190) — deployment facts, not the caller's
+  // permissions. `/session` stays identity only on purpose; this is the separate question.
+  getCapabilities(): Promise<IntelCapabilities>;
+  listNodes(input?: Partial<ListNodesInput>): Promise<NodeList>;
   // 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>;
+  getNode(nodeId: string): Promise<NodeDocument>;
+  createNodes(input: CreateNodeInput): Promise<Node>;
+  getNodeGraph(limit?: number): Promise<NodeGraph>;
+  listNodeLinks(nodeId: string): Promise<NodeLinkList>;
   // 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,
+  resolveNodeLinks(input: ResolveNodeLinksInput): Promise<ResolveNodeLinksResult>;
+  saveNode(input: SaveNodeVersionInput): Promise<NodeDocument>;
+  saveNodeAttachment(input: SaveAttachmentInput): Promise<NodeDocument>;
+  getNodeAttachment(nodeId: string): Promise<Blob>;
+  // One subtree — or one single node — as the zip bundle the server streams (#136). `null` is the
+  // root: the whole installation as this caller may read it.
+  exportNodeBundle(nodeId: string | null): Promise<Blob>;
+  // The same bundle shape for a single flow, through the flow's own export route.
+  exportFlowBundle(flowId: string): Promise<Blob>;
+  // A zip bundle — or a folder zipped on the client — as a new subtree under the target folder
+  // (#137). `nodeId` null files at the root. Always new nodes; the server is all-or-nothing.
+  importNodeBundle(input: {
+    nodeId: string | null;
+    zip: Blob;
+    idempotencyKey: string;
+  }): Promise<BundleImportResult>;
+  // A table as columns and rows. The CSV stays canonical — `getNode` 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>;
+  getNodeTable(nodeId: string): Promise<NodeTable>;
+  defineTable(input: DefineTableInput): Promise<NodeTable>;
+  appendTableRows(input: AppendTableRowsInput): Promise<AppendTableRowsResult>;
   // Walks the browser through the portal's OAuth flow without asking anybody anything: Gate is the
   // identity provider Cloudflare Access consumes, so a signed-in person is already known there
   // (#60). It navigates away — the caller renders no button for it and gets no answer back.
   startPortalSignIn(returnTo?: string): void;
-  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>;
+  listNodeVersions(nodeId: string): Promise<NodeVersionList>;
+  updateNode(input: UpdateNodeInput): Promise<Node>;
+  archiveNode(input: ArchiveNodeInput): Promise<Node>;
+  searchNodes(input: SearchInput): Promise<SearchResult>;
+  listGrants(resourceId: string): Promise<ResourceGrantList>;
   // 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>;
+  shareNode(input: ShareInput): Promise<ShareResult>;
+  revokeGrant(input: RevokeGrantInput): Promise<RevokeGrantResult>;
   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`
@@ -128,7 +154,7 @@ export interface IntelDataProvider {
   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
+  // never what it produced: a run reads nodes 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>;
@@ -138,5 +164,37 @@ export interface IntelDataProvider {
   // 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>;
+
+  // An agent node and the definition its current version carries. `definition` is `null` in the one
+  // window where the node exists and no version has been written — the same window a document's
+  // content is `null` in.
+  getAgent(nodeId: string): Promise<NodeAgent>;
+  // ⚠️ `CreatedAgent`: the create answer carries the Gate application key ONCE (#182). Nothing in
+  // the UI stores or displays it yet — showing it is its own ticket — but the type has to be honest
+  // about what comes back, or the strict read schema would reject the response.
+  createAgent(input: CreateAgentInput): Promise<CreatedAgent>;
+  // ⚠️ Every change to references, schedules or the model writes a NEW definition version; nothing
+  // is edited in place (ADR-0005). `baseVersionId` is the version the editor read, so a parallel
+  // change is refused rather than silently overwritten.
+  saveAgentDefinition(input: SaveAgentDefinitionInput): Promise<NodeAgent>;
+
+  // ⚠️ The seven below are answered by the agent RUNTIME, a separate Worker — but they are asked of
+  // intel, which proxies them with the caller's own Gate token (#178). One origin, one cookie, no
+  // CORS. What that costs is that a 403 here means "you may not drive agents", which is a state the
+  // agent page renders as an answer rather than as a failure.
+  listAgentRuns(agentId: string): Promise<AgentRunList>;
+  getAgentRun(agentId: string, runId: string): Promise<AgentRunDetail>;
+  // Whether the agent is switched off. Runtime state, deliberately not part of the definition: a
+  // definition is versioned, shared and read into model context (#179).
+  getAgentState(agentId: string): Promise<AgentState>;
+  pauseAgent(agentId: string): Promise<AgentState>;
+  resumeAgent(agentId: string): Promise<AgentState>;
+  // Fires one of the agent's own schedules now. The target must be one it already schedules — a run
+  // acts with the AGENT's grants, so naming any node here would be borrowing them.
+  runAgentNow(agentId: string, target: AgentScheduleTarget): Promise<AgentManualRun>;
+  // Where assistant-ui posts. A URL rather than a method: the chat is an SSE stream the transport
+  // owns end to end, and handing it a string is the whole of what it needs from this layer.
+  agentChatApi(agentId: string): string;
+
   logout(): Promise<void>;
 }