@pipeshub-ai/mcp 2.2.0 → 2.3.1

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

@@ -15,11 +15,23 @@ import {
 
 /**
  * Parse a fetch Response as JSON, returning a CallToolResult error when the
- * body is missing / malformed.
+ * status is not ok, or the body is missing / malformed.
+ *
+ * The status check has to happen here rather than in each caller. The SDK funcs
+ * are generated with `errorCodes: []`, so `result.ok` reports transport
+ * failures only and a 401 arrives looking exactly like a success. Parsing that
+ * body yields an envelope with no results in it, which every caller then
+ * reports as an empty corpus — a failed credential becomes "no documents
+ * found". Guarding at the single point where a body is turned into a value
+ * closes that for every present and future caller.
  */
 export async function readJson<T = unknown>(
   response: Response,
+  context = "PipesHub request",
 ): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr) return { ok: false, result: httpErr };
+
   const text = await response.text();
   if (!text) {
     return {
@@ -48,6 +60,24 @@ export async function readJson<T = unknown>(
   }
 }
 
+/**
+ * Reject an access token whose own expiry has already passed.
+ *
+ * Expiry is the one part of a credential's validity that can be established
+ * without asking the server, so it is worth checking before spending a
+ * round-trip — and it still answers when the server is unreachable. Returns
+ * `null` when the token is unexpired or carries no usable `exp`.
+ */
+export function expiredTokenError(exp: unknown): CallToolResult | null {
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+  if (exp * 1000 > Date.now()) return null;
+  return errorResult(
+    `The access token expired on ${new Date(exp * 1000).toISOString()}. `
+      + "Mint a new personal access token in PipesHub under "
+      + "Developer Settings → Personal Access Tokens.",
+  );
+}
+
 /** Return a CallToolResult holding a single JSON-stringified text block. */
 export function jsonResult(value: unknown): CallToolResult {
   return {
@@ -105,7 +135,12 @@ export async function httpErrorResult(
     }
   }
 
-  const detail = message ? ` ${message.slice(0, 400)}` : "";
+  // The server's reason rarely ends in punctuation, which runs it straight
+  // into the hint below ("Invalid token Check that ...").
+  const reason = message.slice(0, 400).trim();
+  const detail = reason
+    ? ` ${/[.!?]$/.test(reason) ? reason : `${reason}.`}`
+    : "";
   const auth = (response.status === 401 || response.status === 403)
     ? " Check that the bearer token / credentials are valid and not expired."
     : "";
@@ -122,7 +157,12 @@ export async function httpErrorResult(
 export async function readValidated<T>(
   response: Response,
   schema: z.ZodType<T>,
+  context = "PipesHub request",
 ): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  // Same reasoning as readJson: never let a non-2xx body reach the parser.
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr) return { ok: false, result: httpErr };
+
   const text = await response.text();
   if (!text) {
     return { ok: false, result: errorResult("Empty response from server") };
@@ -224,17 +264,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,
     };
   });
 }

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

@@ -1,24 +1,13 @@
 // `POST /conversations/stream` (and
 // `POST /conversations/{conversationId}/messages/stream` for follow-ups),
 // accumulate the frames server-side, and hand the LLM a single trimmed
-// `CallToolResult` once the stream emits its terminal `complete` (or
-// `error`) frame.
+// `CallToolResult` once the stream reaches a terminal frame.
 //
-// Frame types we know about (from live wire traces):
-//   - connected        — handshake; ignored
-//   - status           — { status: "started" | "searching" | "processing"
-//                         | "checking_tools" | ... }; ignored (UI-only)
-//   - answer_chunk     — { content, accumulated, ... }; we keep the latest
-//                        `accumulated` as a fallback in case the stream
-//                        ends without a `complete` frame
-//   - tool_call        — model invoked an internal tool; we collect these
-//                        as observability breadcrumbs but the LLM doesn't
-//                        need them to answer
-//   - tool_success     — paired with tool_call; same treatment
-//   - complete         — terminal; payload is `{ conversation, meta }`,
-//                        matching the non-stream response shape, so we
-//                        feed it through `trimConversation` like before
-//   - error            — terminal; surface to the LLM as a tool error
+// The wire protocol is AG-UI. The legacy `connected` / `answer_chunk` /
+// `complete` / `error` vocabulary was removed with the new agent loop and is
+// never emitted. The frames that matter — CUSTOM{conversation_created},
+// TEXT_MESSAGE_CONTENT, RUN_FINISHED, RUN_ERROR — are folded by `./_agui.js`,
+// which is kept separate so the fold stays a pure function over frames.
 
 import * as z from "zod";
 import { conversationsStreamConversation } from "../../funcs/conversationsStreamConversation.js";
@@ -26,6 +15,11 @@ import { conversationsStreamMessage } from "../../funcs/conversationsStreamMessa
 import { agentsStreamConversation } from "../../funcs/agentsStreamConversation.js";
 import { agentsStreamMessage } from "../../funcs/agentsStreamMessage.js";
 import { ToolDefinition } from "../tools.js";
+import {
+  applyAGUIFrame,
+  newChatStreamState,
+  salvagedText,
+} from "./_agui.js";
 import {
   errorResult,
   httpErrorResult,
@@ -36,9 +30,11 @@ import {
 
 const FiltersShape = z.object({
   apps: z.array(z.string()).optional().describe(
-    "Source-scoping ids. Mix connector instance UUIDs with the synthetic "
-      + "`knowledgeBase_<orgId>` id (use pipeshub_sources to discover them). "
-      + "Empty / omitted means no app-side restriction.",
+    "Source-scoping ids from `pipeshub_sources` — connector instance and / "
+      + "or knowledge base ids, mixed freely. The legacy org-wide "
+      + "`knowledgeBase_<orgId>` id is still accepted on deployments that "
+      + "predate per-KB sources. Empty / omitted means no app-side "
+      + "restriction.",
   ),
   kb: z.array(z.string()).optional().describe(
     "Legacy / unused. Leave empty.",
@@ -76,48 +72,53 @@ const args = {
   chatMode: z.enum([
     "internal_search",
     "web_search",
-    "auto",
     "quick",
-    "verification",
-    "deep",
   ]).optional().describe(
     "Response strategy. The valid values depend on whether `agentId` is set:\n"
       + "- WITHOUT `agentId` (plain chat): `internal_search` — answer from the "
       + "org's indexed knowledge (default) — or `web_search` — answer from the "
       + "live web.\n"
-      + "- WITH `agentId` (agent chat): `auto` (let the agent decide; default), "
-      + "`quick`, `verification`, or `deep`.",
+      + "- WITH `agentId` (agent chat): `quick` is the only supported mode and "
+      + "is sent automatically, so this argument can be omitted.",
   ),
 };
 
 export const tool$pipeshubChat: ToolDefinition<typeof args> = {
   name: "pipeshub_chat",
   description:
-    `**Primary chat tool — handles both internal knowledge queries and web search.**
+    `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
 
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-the user asks about their documents, files, knowledge base, company policies,
-or anything that could plausibly be answered by content in their PipesHub-indexed
-sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
-Grounds the answer in the user's actual data and returns citations.
-Answers come from a few retrieved passages, not whole documents — for
-any task needing a document's full content, use
-\`pipeshub_get_record_content\` instead.
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
 
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
 
-**When to pick this over other tools:**
-- "Summarize <doc>" / "key points of <doc>" / "what does <document> say
-  about X?" → NOT this tool. Use \`pipeshub_search\` →
-  \`pipeshub_get_record_content\`: answering for a specific document
-  requires its full content, and chat only sees a few retrieved
-  passages, never the whole document.
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
-- "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -147,11 +148,19 @@ cited document, take \`citations[*].recordId\` and call
   args,
   tool: async (client, args, ctx) => {
     const fetchOptions = { signal: ctx.signal };
+    // `quick` is agent-only. The plain stream schemas accept internal_search /
+    // web_search / agent, so collapse anything else to the default rather than
+    // forwarding a value that path would reject.
+    const plainChatMode = args.chatMode === "web_search"
+      ? "web_search"
+      : "internal_search";
     let response: Response;
 
     if (args.agentId) {
-      // Agent conversation. Agent chatMode vocabulary defaults to `auto`.
-      const agentChatMode = args.chatMode ?? "auto";
+      // `quick` is the only value the agent stream schemas accept, and it is
+      // required — so ignore whatever the caller passed rather than forwarding
+      // a value the gateway would reject.
+      const agentChatMode = "quick" as const;
       if (args.conversationId) {
         // Continue an existing agent conversation.
         const [result] = await agentsStreamMessage(client, {
@@ -192,7 +201,7 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args.modelKey,
           modelName: args.modelName,
           modelFriendlyName: args.modelFriendlyName,
-          chatMode: args.chatMode ?? "internal_search",
+          chatMode: plainChatMode,
         },
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
@@ -205,7 +214,7 @@ cited document, take \`citations[*].recordId\` and call
         modelKey: args.modelKey,
         modelName: args.modelName,
         modelFriendlyName: args.modelFriendlyName,
-        chatMode: args.chatMode ?? "internal_search",
+        chatMode: plainChatMode,
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
@@ -217,72 +226,44 @@ cited document, take \`citations[*].recordId\` and call
     const httpErr = await httpErrorResult(response, "PipesHub chat request");
     if (httpErr) return httpErr;
 
-    // Drain the SSE stream. We only need the terminal `complete` (or
-    // `error`) frame; everything else is observability and ignored.
-    let finalConversation: any = null;
-    let recordsUsed: number | undefined;
-    let lastAccumulated: string | null = null;
-    let errorMessage: string | null = null;
-
+    // Drain the AG-UI stream. `applyAGUIFrame` returns true only on a
+    // genuinely terminal frame — a sub-agent's RUN_FINISHED carries no
+    // `result` and must not end the loop.
+    const state = newChatStreamState();
     try {
       for await (const frame of iterateSSE(response)) {
-        switch (frame.event) {
-          case "complete": {
-            const d = frame.data ?? {};
-            finalConversation = d.conversation ?? null;
-            recordsUsed = d.recordsUsed ?? d.meta?.recordsUsed;
-            break;
-          }
-          case "error": {
-            const d = frame.data ?? {};
-            errorMessage = typeof d === "string"
-              ? d
-              : (d.error ?? d.message ?? frame.raw ?? "Stream error");
-            break;
-          }
-          case "answer_chunk": {
-            const d = frame.data ?? {};
-            if (typeof d.accumulated === "string") {
-              lastAccumulated = d.accumulated;
-            } else if (typeof d.content === "string") {
-              lastAccumulated = (lastAccumulated ?? "") + d.content;
-            }
-            break;
-          }
-          // status / tool_call / tool_success / connected — ignored.
-          default:
-            break;
-        }
-        if (finalConversation || errorMessage) break;
+        if (applyAGUIFrame(state, frame)) break;
       }
     } catch (e: unknown) {
       return errorResult(`SSE stream failed: ${(e as Error).message}`);
     }
 
-    if (errorMessage) return errorResult(errorMessage);
+    if (state.error) return errorResult(state.error);
 
-    if (finalConversation) {
+    if (state.conversation) {
       return jsonResult({
-        ...trimConversation(finalConversation),
-        recordsUsed,
+        ...trimConversation(state.conversation),
+        recordsUsed: state.recordsUsed,
       });
     }
 
-    // Stream ended without a terminal frame — unusual, but salvage what
-    // we accumulated so the LLM has something to work with.
-    if (lastAccumulated) {
+    // Stream ended without a terminal frame — unusual, but salvage what we
+    // accumulated so the LLM has something to work with. `conversation_created`
+    // arrives before any answer text, so a follow-up turn can still resume.
+    const salvaged = salvagedText(state);
+    if (salvaged) {
       return jsonResult({
-        conversationId: null,
-        title: null,
+        conversationId: state.conversationId,
+        title: state.title,
         status: "Inprogress",
-        answer: lastAccumulated,
+        answer: salvaged,
         confidence: null,
         citations: [],
         followUpQuestions: [],
         messageCount: 0,
-        recordsUsed,
-        warning: "Stream ended without a `complete` frame; answer is "
-          + "the last accumulated chunk and citations are unavailable.",
+        recordsUsed: state.recordsUsed,
+        warning: "Stream ended without a terminal RUN_FINISHED; answer is the "
+          + "accumulated TEXT_MESSAGE_CONTENT and citations are unavailable.",
       });
     }
 

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

@@ -12,6 +12,7 @@ import {
   decodeBearer,
   errorResult,
   jsonResult,
+  expiredTokenError,
   readJson,
 } from "./_helpers.js";
 
@@ -24,8 +25,8 @@ const args = {
     "list_my_teams",
   ]).describe(
     "What to do:\n"
-      + "- `whoami` — return the authenticated user's identity (decoded from "
-      + "the bearer JWT). No other args needed.\n"
+      + "- `whoami` — return the authenticated user's identity, confirmed "
+      + "against the server. No other args needed.\n"
       + "- `list_users` — paginated list of org users. Optional `page`, "
       + "`limit`, `search` (substring match against name or email).\n"
       + "- `get_user` — full profile for one user. Required `userId`. "
@@ -56,7 +57,8 @@ actions — pick the right \`action\`:
 
 - \`whoami\` — who is the caller?  Use this whenever you need the
   authenticated user's own id, email, or full name (e.g. before
-  \`get_user\` on themselves).
+  \`get_user\` on themselves). Errors if the credential is expired
+  or revoked.
 - \`list_users\` — search / page through org users.
 - \`get_user\` — full \`User\` document for one user (requires \`userId\`).
 - \`list_groups\` — list user groups with \`userCount\`.
@@ -86,6 +88,56 @@ Output shape varies by action; see each action's docs above.`,
               + "their email and use `list_users` with `search`.",
           );
         }
+        // The claims come out of the local token, which proves nothing about
+        // whether the server still accepts it — a revoked token carries a
+        // perfectly good name and org. Since whoami is the command people run
+        // to check "is my login working?", answering from the token alone
+        // gives a confident yes in exactly the case that matters.
+        //
+        // Expiry is checkable offline, so check it first: it is the common
+        // case and costs no round-trip.
+        const exp = claims["exp"];
+        const expired = expiredTokenError(exp);
+        if (expired) return expired;
+        const tokenExpiresAt = typeof exp === "number"
+          ? new Date(exp * 1000).toISOString()
+          : undefined;
+
+        // Revocation can only be established by asking the server. get_user on
+        // the caller's own id needs `user:read`, which whoami's callers already
+        // hold, and returns 401 for a rejected credential.
+        const userId = claims["userId"];
+        let verified: true | "unchecked" = "unchecked";
+        let unverifiedReason: string | undefined =
+          "No userId claim in the token, so the identity could not be "
+          + "confirmed with the server.";
+
+        if (typeof userId === "string" && userId) {
+          const [probe] = await usersGetUserById(client, { id: userId }, {
+            fetchOptions,
+          }).$inspect();
+
+          if (!probe.ok) {
+            unverifiedReason = `Could not reach PipesHub to confirm the `
+              + `identity (${probe.error.message}). The details below come `
+              + `from the token itself.`;
+          } else if (probe.value.status === 401) {
+            return errorResult(
+              "PipesHub rejected this access token (HTTP 401 Unauthorized), "
+                + "so the identity in it is no longer valid — it has most "
+                + "likely been revoked. Mint a new personal access token "
+                + "under Developer Settings → Personal Access Tokens.",
+            );
+          } else if (probe.value.ok) {
+            verified = true;
+            unverifiedReason = undefined;
+          } else {
+            unverifiedReason = `PipesHub returned HTTP ${probe.value.status} `
+              + `when confirming the identity, so it could not be checked. `
+              + `The details below come from the token itself.`;
+          }
+        }
+
         return jsonResult({
           userId: claims["userId"],
           orgId: claims["orgId"],
@@ -93,6 +145,12 @@ Output shape varies by action; see each action's docs above.`,
           fullName: claims["fullName"],
           mobile: claims["mobile"],
           userSlug: claims["userSlug"],
+          tokenExpiresAt,
+          // Never `false`: that reads as "the server rejected this identity",
+          // which is a different and much more alarming claim than "this was
+          // not checked". A rejection returns an error above instead.
+          identityVerified: verified,
+          note: unverifiedReason,
         });
       }
 
@@ -103,7 +161,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "User listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -120,7 +178,7 @@ Output shape varies by action; see each action's docs above.`,
           id: args.userId,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "User lookup");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -132,7 +190,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "Group listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -144,7 +202,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "Team listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }