@anchrd/intel 0.59.0

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

@@ -0,0 +1,685 @@
+import {
+  BoardGetInput,
+  BoardTaskCreateInput,
+  BoardTaskUpdateInput,
+  BoardUpdateInput,
+  BoardView,
+  DirectoryPersonList,
+} from "@contract/board.ts";
+import { BundleImportResult } from "@contract/bundle.ts";
+import { type NamedOrCounted, ProblemDetails, SessionUser } from "@contract/contract.ts";
+import { FeedListResponse } from "@contract/feed.ts";
+import {
+  ArchiveFlowInput,
+  CreateFlowInput,
+  Flow,
+  FlowDocument,
+  FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowValidation,
+  FlowVersionList,
+  ListFlowsInput,
+  PreviewFlowPublishInput,
+  PublishFlowInput,
+  PurgeFlowInput,
+  PurgeFlowResult,
+  RelationGraph,
+  RelationGraphInput,
+  SaveFlowVersionInput,
+  UpdateFlowInput,
+} from "@contract/flow.ts";
+import {
+  CompleteFlowRunStepInput,
+  FlowRunHistory,
+  FlowRunList,
+  FlowRunStep,
+  ListFlowRunsInput,
+  StartFlowRunInput,
+} from "@contract/flow-run.ts";
+import {
+  ArchiveNodeInput,
+  CreateNodeInput,
+  ListNodesInput,
+  Node,
+  NodeDocument,
+  NodeGraph,
+  NodeLinkList,
+  NodeList,
+  NodeTable,
+  NodeVersionList,
+  PurgeNodeInput,
+  PurgeNodePreview,
+  PurgeNodePreviewInput,
+  PurgeNodeResult,
+  ReindexResult,
+  ResolveNodeLinksInput,
+  ResolveNodeLinksResult,
+  SaveAttachmentBytesInput,
+  SaveAttachmentInput,
+  SaveNodeVersionInput,
+  SearchInput,
+  SearchResult,
+  UpdateNodeInput,
+} from "@contract/node.ts";
+import {
+  ResourceAccessList,
+  ResourceGrantList,
+  RevokeFlowGrantInput,
+  RevokeGrantInput,
+  RevokeGrantResult,
+  ShareFlowInput,
+  ShareInput,
+  ShareResult,
+} from "@contract/share.ts";
+import {
+  AppendTableRowsInput,
+  AppendTableRowsResult,
+  DefineTableInput,
+  RedefineTableInput,
+} from "@contract/table.ts";
+import { ToolCatalog, ToolServerCatalog } from "@contract/tool.ts";
+import type { z } from "zod";
+import { createBrowserSignIn } from "@/data/sign-in/sign-in.ts";
+import type { IntelDataProvider, TreeEntry } from "./intel-data-provider.types.ts";
+
+// ⚠️ 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.
+// One request's own deadline, beside everything `fetch` takes. An upload needs minutes where a
+// read needs seconds, and the difference belongs to the call rather than to the whole provider.
+type IntelRequestInit = RequestInit & { timeoutMs?: number };
+
+export class IntelRequestError extends Error {
+  /**
+   * ⚠️ `callers` is the structured half of the two refusals that name flows — `folder_execute_in_use`
+   * (#448) and `flow_in_use_by_flow` (#593): the flows this reader may see, by name, and a count of
+   * the ones they may not. It is `null` for every other failure, and a screen that reads it has to
+   * say which code it read it for — the field is only meaningful beside its own.
+   *
+   * `message` still holds the server's finished English sentence. It is no longer what the dialog
+   * shows; it is what a log or a report has when nobody translated anything.
+   */
+  constructor(
+    public readonly status: number,
+    public readonly code: string | null,
+    message: string,
+    public readonly callers: NamedOrCounted | null = null,
+  ) {
+    super(message);
+    this.name = "IntelRequestError";
+  }
+}
+
+// Attachment uploads and downloads share this budget, so it is generous rather than snappy.
+const RequestTimeoutMs = 60_000;
+
+// ⚠️ A file upload gets its own, and it is a consequence of the 50 MB limit rather than a taste for
+// patience (#821): 50 MB inside a minute needs about 7 Mbit/s of upstream, which a home connection
+// does not have. On the old 15 MB limit that arithmetic never came up.
+const UploadTimeoutMs = 300_000;
+
+// 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).
+ */
+// ⚠️ `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 };
+}
+
+export function createIntelDataProvider(
+  deps: {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    onUnauthorized?(): void;
+    navigate?(url: string): void;
+  } = {},
+): IntelDataProvider {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = deps.baseUrl?.replace(/\/$/, "") ?? "";
+  const navigate =
+    deps.navigate ??
+    ((url: string) => {
+      if (typeof window !== "undefined") window.location.assign(url);
+    });
+  // ⚠️ The default goes through `createBrowserSignIn` rather than redirecting straight away, and it
+  // has to: this is the code path that produced the endless reload (#118). A caller that supplies
+  // its own `onUnauthorized` takes the guard on as well — `main.tsx` does, because it also has to
+  // put something on the screen once the redirect is refused.
+  const unauthorized =
+    deps.onUnauthorized ??
+    (() => {
+      if (typeof window !== "undefined") createBrowserSignIn(loginPath).attempt();
+    });
+
+  async function response(path: string, init: IntelRequestInit = {}): Promise<Response> {
+    // Without a deadline a stalled request would leave the view in a permanent loading state, and a
+    // caller-supplied signal (query cancellation) has to keep working alongside it.
+    const { timeoutMs = RequestTimeoutMs, ...rest } = init;
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const result = await doFetch(`${baseUrl}/api/v1${path}`, {
+      ...rest,
+      credentials: "include",
+      signal: rest.signal ? AbortSignal.any([rest.signal, deadline]) : deadline,
+      headers: {
+        ...(rest.body === undefined ? {} : { "content-type": "application/json" }),
+        ...rest.headers,
+      },
+    });
+    if (result.status === 401) unauthorized();
+    if (!result.ok) {
+      const parsed = ProblemDetails.safeParse(
+        await result
+          .clone()
+          .json()
+          .catch(() => null),
+      );
+      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}`,
+        parsed.success ? (parsed.data.callers ?? null) : null,
+      );
+    }
+    return result;
+  }
+
+  async function request<T>(
+    path: string,
+    schema: z.ZodType<T>,
+    init: IntelRequestInit = {},
+  ): Promise<T> {
+    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 ?? "" },
+    );
+    // Same rule as `parentId`: only the asked-for case is sent. The default is the server's, and a
+    // provider that spells it out anyway would have to be changed whenever the server's is.
+    if (query.includeArchived) params.set("includeArchived", "true");
+    if (query.archivedOnly) params.set("archivedOnly", "true");
+    const search = params.toString();
+    return await request(`/flows${search ? `?${search}` : ""}`, FlowList);
+  }
+
+  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(`/nodes?${params}`, NodeList);
+  }
+
+  return {
+    async getSession() {
+      return await request("/session", SessionUser);
+    },
+    async reindexNodes() {
+      return await request("/nodes/reindex", ReindexResult, { method: "POST", body: "{}" });
+    },
+    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 [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[] = [
+        ...nodes.items.map((node) => ({
+          type: "node" as const,
+          id: node.id,
+          title: node.title,
+          kind: node.kind,
+          openable: openable.has(node.id),
+          node,
+        })),
+        ...flows.items.map((flow) => flowEntry(flow, openable.has(flow.id))),
+      ];
+      // 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 getNode(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}`, NodeDocument);
+    },
+    async createNodes(input) {
+      return await request("/nodes", Node, {
+        method: "POST",
+        body: JSON.stringify(CreateNodeInput.parse(input)),
+      });
+    },
+    async getNodeGraph(limit = 250) {
+      return await request(`/nodes/graph?limit=${encodeURIComponent(limit)}`, NodeGraph);
+    },
+    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 resolveNodeLinks(input) {
+      return await request("/nodes/links/resolve", ResolveNodeLinksResult, {
+        method: "POST",
+        body: JSON.stringify(ResolveNodeLinksInput.parse(input)),
+      });
+    },
+    async saveNode(input) {
+      const parsed = SaveNodeVersionInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/versions`, NodeDocument, {
+        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),
+      });
+    },
+    // The body IS the file, so everything about it travels in the headers — the same reading the
+    // server does, and the same shape the bundle import beside it already had (#821).
+    async saveNodeAttachmentBytes(input) {
+      const parsed = SaveAttachmentBytesInput.parse({
+        nodeId: input.nodeId,
+        baseVersionId: input.baseVersionId,
+        mediaType: input.file.type || "application/octet-stream",
+        size: input.file.size,
+        idempotencyKey: input.idempotencyKey,
+      });
+      return await request(
+        `/nodes/${encodeURIComponent(parsed.nodeId)}/attachment/bytes`,
+        NodeDocument,
+        {
+          method: "POST",
+          body: input.file,
+          timeoutMs: UploadTimeoutMs,
+          headers: {
+            "content-type": parsed.mediaType,
+            "idempotency-key": parsed.idempotencyKey,
+            // `none` rather than an absent header: a first upload says so, and a caller who merely
+            // forgot the field is refused instead of overwriting the newest version.
+            "intel-base-version-id": parsed.baseVersionId ?? "none",
+          },
+        },
+      );
+    },
+    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 getNodeTable(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/table`, NodeTable);
+    },
+    async defineTable(input) {
+      const parsed = DefineTableInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/table`, NodeTable, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async appendTableRows(input) {
+      const parsed = AppendTableRowsInput.parse(input);
+      return await request(
+        `/nodes/${encodeURIComponent(parsed.nodeId)}/table/rows`,
+        AppendTableRowsResult,
+        { method: "POST", body: JSON.stringify(parsed) },
+      );
+    },
+    // ⚠️ `PATCH`, where the two writes above are `POST`. The route is the same address as the
+    // header itself, and this changes it — `POST /nodes/:id/table` is the one that WRITES a header
+    // and refuses on a table that already has one.
+    async redefineTable(input) {
+      const parsed = RedefineTableInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}/table`, NodeTable, {
+        method: "PATCH",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async listNodeVersions(nodeId) {
+      return await request(`/nodes/${encodeURIComponent(nodeId)}/versions`, NodeVersionList);
+    },
+    async getBoard(input) {
+      const parsed = BoardGetInput.parse(input);
+      // ⚠️ Only the filters the caller actually named travel. Sending an empty `status` would ask
+      // the server for the column called "" rather than for every column — the same rule the flow
+      // list follows above, and for the same reason.
+      const params = new URLSearchParams();
+      if (parsed.status !== undefined) params.set("status", parsed.status);
+      if (parsed.assigneeId !== undefined) params.set("assigneeId", parsed.assigneeId);
+      if (parsed.dueBefore !== undefined) params.set("dueBefore", parsed.dueBefore);
+      if (parsed.dependsOn !== undefined) params.set("dependsOn", parsed.dependsOn);
+      if (parsed.includeArchived) params.set("includeArchived", "true");
+      const query = params.toString();
+      return await request(
+        `/boards/${encodeURIComponent(parsed.boardId)}${query === "" ? "" : `?${query}`}`,
+        BoardView,
+      );
+    },
+    async updateBoard(input) {
+      const parsed = BoardUpdateInput.parse(input);
+      return await request(`/boards/${encodeURIComponent(parsed.boardId)}`, BoardView, {
+        method: "PATCH",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async createBoardTask(input) {
+      const parsed = BoardTaskCreateInput.parse(input);
+      return await request(`/boards/${encodeURIComponent(parsed.boardId)}/tasks`, BoardView, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    // ⚠️ The board id is in the path although the call identifies the card by its own id: the route
+    // mirrors the tool name segment for segment (`board_task_update`), and a card that could be
+    // addressed without its board would invite a caller to move one between boards — which the
+    // service refuses on purpose (#377).
+    async updateBoardTask(boardId, input) {
+      const parsed = BoardTaskUpdateInput.parse(input);
+      return await request(
+        `/boards/${encodeURIComponent(boardId)}/tasks/${encodeURIComponent(parsed.taskId)}`,
+        BoardView,
+        { method: "PATCH", body: JSON.stringify(parsed) },
+      );
+    },
+    async searchBoardAssignees(boardId, query) {
+      return await request(
+        `/boards/${encodeURIComponent(boardId)}/assignees?q=${encodeURIComponent(query)}`,
+        DirectoryPersonList,
+      );
+    },
+    // ⚠️ A POST although it reads, mirroring the route: a hundred identifiers in a query string
+    // land in proxy logs and in browser history, and they would hit the length limit long before
+    // the hundredth.
+    async resolveNames(ids) {
+      return await request("/directory/resolve", DirectoryPersonList, {
+        method: "POST",
+        body: JSON.stringify({ ids }),
+      });
+    },
+    async updateNode(input) {
+      const parsed = UpdateNodeInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}`, Node, {
+        method: "PATCH",
+        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 purgeNode(input) {
+      const parsed = PurgeNodeInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.nodeId)}`, PurgeNodeResult, {
+        method: "DELETE",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async previewNodePurge(input) {
+      const parsed = PurgeNodePreviewInput.parse(input);
+      return await request(
+        `/nodes/${encodeURIComponent(parsed.nodeId)}/purge-preview`,
+        PurgeNodePreview,
+      );
+    },
+    async purgeFlow(input) {
+      const parsed = PurgeFlowInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}`, PurgeFlowResult, {
+        method: "DELETE",
+      });
+    },
+    async searchNodes(input) {
+      return await request("/nodes/search", SearchResult, {
+        method: "POST",
+        body: JSON.stringify(SearchInput.parse(input)),
+      });
+    },
+    async listGrants(resourceId) {
+      return await request(`/nodes/${encodeURIComponent(resourceId)}/grants`, ResourceGrantList);
+    },
+    async listEffectiveAccess(resourceId) {
+      return await request(
+        `/nodes/${encodeURIComponent(resourceId)}/effective-access`,
+        ResourceAccessList,
+      );
+    },
+    async shareNode(input) {
+      const parsed = ShareInput.parse(input);
+      return await request(`/nodes/${encodeURIComponent(parsed.resourceId)}/grants`, ShareResult, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async revokeGrant(input) {
+      const parsed = RevokeGrantInput.parse(input);
+      return await request(
+        `/nodes/${encodeURIComponent(parsed.resourceId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
+        RevokeGrantResult,
+        { method: "POST", body: JSON.stringify(parsed) },
+      );
+    },
+    async listFlowGrants(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/grants`, ResourceGrantList);
+    },
+    async listEffectiveFlowAccess(flowId) {
+      return await request(
+        `/flows/${encodeURIComponent(flowId)}/effective-access`,
+        ResourceAccessList,
+      );
+    },
+    async shareFlow(input) {
+      const parsed = ShareFlowInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}/grants`, ShareResult, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async revokeFlowGrant(input) {
+      const parsed = RevokeFlowGrantInput.parse(input);
+      return await request(
+        `/flows/${encodeURIComponent(parsed.flowId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
+        RevokeGrantResult,
+        { method: "POST", body: JSON.stringify(parsed) },
+      );
+    },
+    listFlows,
+    async getFlow(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}`, FlowDocument);
+    },
+    async validateFlow(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/validation`, FlowValidation);
+    },
+    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 updateFlow(input) {
+      const parsed = UpdateFlowInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}`, Flow, {
+        method: "PATCH",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async archiveFlow(input) {
+      const parsed = ArchiveFlowInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}/archive`, Flow, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async saveFlow(input) {
+      const parsed = SaveFlowVersionInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}/versions`, FlowDocument, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async listFlowVersions(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/versions`, FlowVersionList);
+    },
+    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, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async startFlow(input) {
+      const parsed = StartFlowRunInput.parse(input);
+      return await request(`/flows/${encodeURIComponent(parsed.flowId)}/runs`, FlowRunStep, {
+        method: "POST",
+        body: JSON.stringify(parsed),
+      });
+    },
+    async listFeed(input) {
+      // Only what was asked for travels: an empty `actor` or `before` in the query string is not
+      // the same as leaving it out, and the contract refuses the empty string.
+      const params = new URLSearchParams({ limit: String(input.limit) });
+      if (input.actor) params.set("actor", input.actor);
+      if (input.before) params.set("before", input.before);
+      return await request(`/feed?${params}`, FeedListResponse);
+    },
+    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);
+      // Two addresses, one answer (#774): under the flow when one is named, at the root when the
+      // question is "did anything run at all".
+      return await request(
+        parsed.flowId === null
+          ? `/flow-runs?${params}`
+          : `/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)}/steps/complete`,
+        FlowRunStep,
+        {
+          method: "POST",
+          body: JSON.stringify(parsed),
+        },
+      );
+    },
+    async listTools() {
+      return await request("/tools", ToolCatalog);
+    },
+    // The servers behind the same live list (D30). Its own call rather than a grouping done in the
+    // browser: which server a tool belongs to is the portal's answer, and a UI that split tool
+    // names would be guessing where the namespace ends.
+    async listToolServers() {
+      return await request("/tools/servers", ToolServerCatalog);
+    },
+    // 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.
+    startPortalSignIn(returnTo = "/tools") {
+      navigate(`${baseUrl}/auth/connect?returnTo=${encodeURIComponent(returnTo)}&silent=1`);
+    },
+    async logout() {
+      const response = await doFetch(`${baseUrl}/auth/logout`, {
+        method: "POST",
+        credentials: "include",
+      });
+      if (!response.ok) throw new Error(`Intel responded with ${response.status}`);
+    },
+  };
+}