@pipeshub-ai/mcp 2.2.0 → 2.3.0

package/src/funcs/connectorLookupRecordByIdentifier.ts

@@ -0,0 +1,200 @@
+/*
+ * Adapted from Speakeasy-generated connectorLookupRecordByIdentifier.
+ */
+
+import { PipeshubCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  LookupRecordByIdentifierRequest,
+  LookupRecordByIdentifierRequest$zodSchema,
+} from "../models/lookuprecordbyidentifierop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Resolve a URL, issue key or external ID to a Record ID
+ *
+ * @remarks
+ * Turn an external reference into the matching PipesHub record. Accepts a
+ * pasted link, a Jira-style issue key, or a bare external system ID from
+ * any connected source. Repeat `identifiers` to batch-resolve up to ten
+ * in one call.
+ *
+ * The response carries a rendered `text` view — each match's metadata
+ * block followed by a `Next:` line naming a follow-up call. The structured
+ * fields carry the same information for programmatic use.
+ *
+ * **Accepted identifiers**
+ * - Jira issue URL — `https://acme.atlassian.net/browse/PA-1787`
+ * - Jira issue key — `PA-1787`
+ * - Confluence page URL —
+ *   `https://acme.atlassian.net/wiki/spaces/SD/pages/450625553/Agent+Loop`
+ * - Google Drive / Docs URL — `https://docs.google.com/document/d/1AbC.../edit`
+ * - Slack message link — `https://acme.slack.com/archives/C0123/p1720000000000100`
+ * - Bare external system ID — `450625553`
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - **This endpoint** converts an *external* reference into an internal
+ *   Record ID. Reach for it whenever you meet a link or ticket key and
+ *   need the record behind it.
+ * - `GET /connectors/record/{recordId}/content` reads a record you have
+ *   already identified. It needs an internal Record ID, which is exactly
+ *   what this endpoint returns.
+ * - `GET /connectors/navigate` browses the hierarchy when you have a
+ *   position in the tree rather than a specific identifier.
+ *
+ * **Typical flow:** call this with the reference, take a match's `id`
+ * from the response, then call
+ * `GET /connectors/record/{recordId}/content` to read the record.
+ *
+ * **Multiple matches:** one identifier can legitimately match more than
+ * one record — the same external ID may exist in several connected
+ * instances. In that case the response sets `ambiguous: true` and
+ * `matches` holds every candidate. Present the choice rather than taking
+ * the first; `connectorName` narrows a retry.
+ *
+ * **Misses are not errors.**
+ *
+ * Only records the caller can see are returned, and a miss is a `200`
+ * with an empty `matches` array and the input echoed in
+ * `not_found_identifiers` — not a `404`. The identifier resolved to
+ * nothing *or* to something the caller may not access; the two are
+ * deliberately indistinguishable, because an identifier is
+ * caller-supplied and guessable, and confirming existence would leak
+ * records across organizations. `searched_connectors` names what was
+ * covered, so a retry with `connectorName` is often the right next move.
+ *
+ * **Scope:** resolution searches every connector the caller can access,
+ * regardless of any source filter used elsewhere.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export function connectorLookupRecordByIdentifier(
+  client$: PipeshubCore,
+  request: LookupRecordByIdentifierRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: PipeshubCore,
+  request: LookupRecordByIdentifierRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => LookupRecordByIdentifierRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/record/lookup")();
+  const query$ = encodeFormQuery({
+    "connectorName": payload$.connectorName,
+    "identifiers": payload$.identifiers,
+  });
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "lookupRecordByIdentifier",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}

package/src/funcs/connectorNavigateKnowledgeGraph.ts

@@ -0,0 +1,215 @@
+/*
+ * Adapted from Speakeasy-generated connectorNavigateKnowledgeGraph.
+ */
+
+import { PipeshubCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  NavigateKnowledgeGraphRequest,
+  NavigateKnowledgeGraphRequest$zodSchema,
+} from "../models/navigateknowledgegraphop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Browse the knowledge graph from a node
+ *
+ * @remarks
+ * Open a node in the knowledge graph and see what is inside it — a file
+ * explorer across every connected source.
+ *
+ * Call it with no `nodeId` for a flat listing of every record group and
+ * record the caller can reach, newest first. This is a starting point to
+ * pick a node from, not a roster of connected apps — app nodes are never
+ * returned in a listing, though an app's `id` is accepted as a `nodeId`
+ * and lists that app's record groups. Pass a node's `id` to descend:
+ * record groups contain records and folders, and a record contains its
+ * own children — comments, attachments, sub-tasks — plus a `related`
+ * section of cross-referenced records, such as the Confluence page linked
+ * from a Jira ticket. `nodeId` is tolerant: a URL or an issue key such as
+ * `PA-1787` is resolved to its record before navigating, so a link can be
+ * pasted straight in without a separate lookup call.
+ *
+ * The response carries a rendered `text` view — breadcrumbs, the current
+ * node, the children listing, `Related:`, and a closing `Next:` line
+ * naming a follow-up call. The structured fields carry the same
+ * information for programmatic use.
+ *
+ * **When to use this vs. the other record endpoints:**
+ * - **This endpoint** is for structural exploration — "what is in this
+ *   project", "what is attached to this ticket", "what else links to this
+ *   page". It returns names, types and IDs; it never returns document
+ *   text.
+ * - `GET /connectors/record/{recordId}/content` returns one record's
+ *   actual parsed text. Use it once navigation has identified the record
+ *   you want to read.
+ * - `GET /connectors/record/lookup` is the way in when you hold a URL or
+ *   an issue key rather than a position in the tree.
+ *
+ * **Typical flow:** call with no `nodeId` to see what is reachable → pass
+ * a record group's `id` to list its records → take a row whose
+ * `is_record` is true and call
+ * `GET /connectors/record/{recordId}/content` to read it.
+ *
+ * **Paging and depth:** results are paginated; `pagination.has_next`
+ * tells you whether to request the next `page`. `depth` above 1 returns
+ * all descendants down to that level as one flat list, each row carrying
+ * its own `level`, instead of only direct children.
+ *
+ * **Scope:** everything the caller can read, across both connectors and
+ * Knowledge Base collections. No connector-level filter is applied — the
+ * listing is bounded by per-node permissions alone.
+ *
+ * **Permission scoping:**
+ *
+ * `rows` and `related` carry only nodes the caller can see, and the
+ * opened node itself is access-checked before any of its details are
+ * returned. A node that does not exist and a node the caller cannot
+ * access are deliberately indistinguishable — both return an empty view
+ * rather than an error.
+ *
+ * `breadcrumbs` is the exception: the ancestor trail is resolved by id
+ * alone, without a permission check. For a record shared directly with
+ * the caller, it can therefore name ancestors the caller cannot open.
+ * Treat breadcrumb entries as labels, not as nodes guaranteed to be
+ * navigable.
+ *
+ * If set, this operation will use either {@link Security.bearerAuth} or {@link Security.oauth2} from the global security.
+ */
+export function connectorNavigateKnowledgeGraph(
+  client$: PipeshubCore,
+  request?: NavigateKnowledgeGraphRequest | undefined,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: PipeshubCore,
+  request?: NavigateKnowledgeGraphRequest | undefined,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) =>
+      NavigateKnowledgeGraphRequest$zodSchema.optional().parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/navigate")();
+  const query$ = encodeFormQuery({
+    "createdAfter": payload$?.createdAfter,
+    "createdBefore": payload$?.createdBefore,
+    "depth": payload$?.depth,
+    "limit": payload$?.limit,
+    "modifiedAfter": payload$?.modifiedAfter,
+    "modifiedBefore": payload$?.modifiedBefore,
+    "nodeId": payload$?.nodeId,
+    "nodeTypes": payload$?.nodeTypes,
+    "page": payload$?.page,
+  });
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "navigateKnowledgeGraph",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}

package/src/lib/base64.ts

@@ -1,12 +1,15 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ *
+ * Exception: `bytesToBase64` is re-exported from the hand-maintained
+ * `./bytes-to-base64.js` (see that file and `.genignore`). Do not restore
+ * the generated one-liner — it overflows the stack on binary payloads.
  */
 
 import * as z from "zod";
 
-export function bytesToBase64(u8arr: Uint8Array): string {
-  return btoa(String.fromCodePoint(...u8arr));
-}
+export { bytesToBase64 } from "./bytes-to-base64.js";
+import { bytesToBase64 } from "./bytes-to-base64.js";
 
 export function bytesFromBase64(encoded: string): Uint8Array {
   return Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));

package/src/lib/bytes-to-base64.ts

@@ -0,0 +1,24 @@
+/**
+ * Hand-maintained base64 encoder for binary payloads.
+ *
+ * Speakeasy's generated helper is:
+ *   btoa(String.fromCodePoint(...u8arr))
+ * which passes one argument per byte and throws "Maximum call stack size
+ * exceeded" once the array is larger than the engine's argument limit
+ * (between 64 KB and 128 KB on Node 24). That is smaller than a typical
+ * PDF or image, so binary MCP results fail outright.
+ *
+ * Keep this file out of Speakeasy regeneration (see `.genignore`). The
+ * generated wrappers in `src/lib/base64.ts` and `src/mcp-server/shared.ts`
+ * re-export / call through here.
+ */
+
+const BASE64_CHUNK = 0x8000;
+
+export function bytesToBase64(u8arr: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < u8arr.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...u8arr.subarray(i, i + BASE64_CHUNK));
+  }
+  return btoa(binary);
+}

package/src/mcp-server/instructions.ts

@@ -71,6 +71,36 @@ the user can verify.
 - \`pipeshub_agents\` — list the org's configured **agents** (specialized
   assistants with their own prompt, tools, and knowledge scope).
 
+## Knowledge Sources
+
+A source (an app connector or a KB) holds record groups (a project, space,
+drive, folder), which hold records (one ticket, page, file). Records nest —
+an epic over its stories, a page over its child pages.
+
+**Every tool returns metadata or content.**
+
+- \`pipeshub_search\` / \`pipeshub_chat\` — content, but only a ranked sample of
+  blocks: never all blocks of a record, never every record that matches, never
+  a complete list of what exists.
+- \`mode:"lookup"\` and \`mode:"navigate"\` — metadata: recordIds, fields, and
+  structure. No document text. \`mode:"content"\` — one whole record.
+
+**Combining them.** Search finds a starting point by wording; navigate on a
+\`recordId\` reveals what search structurally cannot — siblings, children,
+linked records, and the group's total count. For a question that must be
+exhaustive ("all", "how many", "every"), do NOT count search hits or trust a
+chat answer: navigate the record group, which reports the real total. For a
+record's siblings, navigate its parent — take the id from the \`Path\` line.
+
+**A named record** — an issue key, a Confluence / Drive / Slack link, an
+external ID → \`mode:"lookup"\` FIRST. It returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its \`recordId\`, which often
+answers the question outright. Never guess a \`recordId\`.
+
+Pass a source's id from \`pipeshub_sources\` as \`apps: ["<id>"]\` to search or
+chat, and as \`nodeId\` to navigate. Navigate and lookup end in a \`Next:\` line
+naming the exact follow-up call — follow it.
+
 ## Agents
 
 Some orgs configure **agents** for specific jobs (e.g. a Slack messenger, a

package/src/mcp-server/shared.ts

@@ -1,8 +1,14 @@
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ *
+ * Exception: `bytesToBase64` is imported from the hand-maintained
+ * `../lib/bytes-to-base64.js` (see that file and `.genignore`). Do not
+ * restore the generated one-liner — it overflows the stack on binary
+ * payloads.
  */
 
 import * as z from "zod";
+import { bytesToBase64 } from "../lib/bytes-to-base64.js";
 
 type BinaryData =
   | Uint8Array
@@ -14,9 +20,7 @@ type BinaryData =
 
 const base64Schema = z.string().base64();
 
-export function bytesToBase64(u8arr: Uint8Array): string {
-  return btoa(String.fromCodePoint(...u8arr));
-}
+export { bytesToBase64 };
 
 export async function consumeStream(
   stream: ReadableStream<Uint8Array>,

package/src/mcp-server/tools/_agui.ts

@@ -0,0 +1,138 @@
+// AG-UI frame folding for the chat stream.
+//
+// AG-UI is the only wire protocol the conversation and agent stream routes
+// speak; the legacy `connected` / `answer_chunk` / `complete` / `error`
+// vocabulary was removed with the new agent loop and is never emitted.
+//
+// Kept separate from `pipeshubChat.ts` so the fold is a pure function over
+// frames and can be exercised without a live stream.
+
+import type { SSEFrame } from "./_helpers.js";
+
+export const AGUIEvent = {
+  RUN_FINISHED: "RUN_FINISHED",
+  RUN_ERROR: "RUN_ERROR",
+  CUSTOM: "CUSTOM",
+  TEXT_MESSAGE_CONTENT: "TEXT_MESSAGE_CONTENT",
+} as const;
+
+export type ChatStreamState = {
+  /** Persisted conversation from the terminal frame; null until then. */
+  conversation: any | null;
+  recordsUsed: number | undefined;
+  error: string | null;
+  /** From `CUSTOM{name:"conversation_created"}`, available before the answer. */
+  conversationId: string | null;
+  title: string | null;
+  /**
+   * Answer text accumulated per `messageId`. Universal `agent` mode forwards
+   * child-run text alongside the root answer, so a single buffer would splice
+   * sub-agent output into the middle of the reply.
+   */
+  text: Map<string, string>;
+  /** messageIds seen on frames with no `parentRunId` — i.e. the root run. */
+  rootMessageIds: Set<string>;
+};
+
+export function newChatStreamState(): ChatStreamState {
+  return {
+    conversation: null,
+    recordsUsed: undefined,
+    error: null,
+    conversationId: null,
+    title: null,
+    text: new Map(),
+    rootMessageIds: new Set(),
+  };
+}
+
+/**
+ * Fold one frame into `state`. Returns true when the frame is terminal and the
+ * caller should stop draining the stream.
+ */
+/** The subset of AG-UI payload fields this fold reads. */
+type FrameData = {
+  result?: {
+    conversation?: unknown;
+    recordsUsed?: number;
+    meta?: { recordsUsed?: number };
+  };
+  message?: string;
+  error?: string;
+  name?: string;
+  value?: { conversationId?: string; title?: string };
+  delta?: string;
+  messageId?: string;
+  parentRunId?: string | null;
+};
+
+export function applyAGUIFrame(
+  state: ChatStreamState,
+  frame: SSEFrame,
+): boolean {
+  const data = frame.data;
+  const d: FrameData = data && typeof data === "object"
+    ? data as FrameData
+    : {};
+
+  switch (frame.event) {
+    case AGUIEvent.RUN_FINISHED: {
+      // Only the gateway's own re-emitted frame carries `result` — it swallows
+      // the AI backend's root RUN_FINISHED and re-sends an enriched one after
+      // persisting. Sub-agent RUN_FINISHED frames are forwarded verbatim with
+      // no `result`, so keying off the event name alone would end the stream
+      // as soon as the first sub-agent finished.
+      const result = d.result;
+      if (!result || typeof result !== "object") return false;
+      state.conversation = result.conversation ?? null;
+      state.recordsUsed = result.recordsUsed ?? result.meta?.recordsUsed;
+      return true;
+    }
+
+    case AGUIEvent.RUN_ERROR: {
+      state.error = (typeof data === "string" ? data : null)
+        ?? d.message ?? d.error ?? frame.raw ?? "Stream error";
+      return true;
+    }
+
+    case AGUIEvent.CUSTOM: {
+      if (d.name === "conversation_created") {
+        const value = d.value ?? {};
+        state.conversationId = value.conversationId ?? state.conversationId;
+        state.title = value.title ?? state.title;
+      }
+      return false;
+    }
+
+    case AGUIEvent.TEXT_MESSAGE_CONTENT: {
+      if (typeof d.delta !== "string" || d.delta.length === 0) return false;
+      const id = typeof d.messageId === "string" ? d.messageId : "";
+      state.text.set(id, (state.text.get(id) ?? "") + d.delta);
+      if (d.parentRunId == null) state.rootMessageIds.add(id);
+      return false;
+    }
+
+    // RUN_STARTED, STEP_*, TOOL_CALL_*, REASONING_*, STATE_*,
+    // TEXT_MESSAGE_START/END, HEARTBEAT — lifecycle noise.
+    default:
+      return false;
+  }
+}
+
+/**
+ * Best-effort answer when the stream ended without a terminal frame.
+ *
+ * Prefers the longest root-run buffer; falls back to the longest buffer of any
+ * run so a partial answer still reaches the caller.
+ */
+export function salvagedText(state: ChatStreamState): string | null {
+  const pick = (ids: Iterable<string>): string | null => {
+    let best: string | null = null;
+    for (const id of ids) {
+      const text = state.text.get(id);
+      if (text && (best === null || text.length > best.length)) best = text;
+    }
+    return best;
+  };
+  return pick(state.rootMessageIds) ?? pick(state.text.keys());
+}

package/src/mcp-server/tools/_helpers.ts

@@ -224,17 +224,24 @@ export function trimConversation(conv: any) {
 export function trimCitations(citations: unknown) {
   if (!Array.isArray(citations)) return [];
   return citations.map((c: any) => {
-    const md = c?.metadata ?? {};
+    // Two wire shapes exist. Flat: `{ content, chunkIndex, metadata }`.
+    // Nested (current backend): `{ citationId, citationData: { content,
+    // chunkIndex, metadata } }`. Reading only the flat one silently yields
+    // a citation with every field `undefined` — which JSON.stringify drops,
+    // leaving `{"snippet": null}` and no way to identify the source at all.
+    const cd = c?.citationData ?? c;
+    const md = cd?.metadata ?? c?.metadata ?? {};
+    const content = typeof cd?.content === "string" ? cd.content : c?.content;
     return {
-      recordId: md.recordId ?? c?.recordId,
-      recordName: md.recordName ?? c?.recordName,
-      snippet: typeof c?.content === "string"
-        ? c.content.slice(0, 280)
+      recordId: md.recordId ?? cd?.recordId ?? c?.recordId,
+      recordName: md.recordName ?? cd?.recordName ?? c?.recordName,
+      snippet: typeof content === "string"
+        ? content.slice(0, 280)
         : md.blockText ?? null,
       mimeType: md.mimeType,
       webUrl: md.webUrl,
       pageNum: md.pageNum,
-      chunkIndex: c?.chunkIndex ?? md.chunkIndex,
+      chunkIndex: cd?.chunkIndex ?? c?.chunkIndex ?? md.chunkIndex,
     };
   });
 }