@pipeshub-ai/mcp 2.0.0 → 2.1.0

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

@@ -1,12 +1,17 @@
-// Curated-tool helpers. Hand-written, NOT regenerated by Speakeasy.
 //
 // Each curated tool fetches a Response from one of the SDK funcs and then
 // trims / restructures the body before handing it to the LLM. The helpers
 // here keep that work out of the individual tool files.
 
+import * as z from "zod";
 import { Security } from "../../models/security.js";
 import { PipeshubCore } from "../../core.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { agentsListAgents } from "../../funcs/agentsListAgents.js";
+import {
+  AgentListEnvelope$zodSchema,
+  AgentSummary,
+} from "../../models/agentops.js";
 
 /**
  * Parse a fetch Response as JSON, returning a CallToolResult error when the
@@ -58,6 +63,94 @@ export function errorResult(message: string): CallToolResult {
   };
 }
 
+/**
+ * Guard a (possibly streaming) `Response` on its HTTP status. The streaming
+ * SDK funcs configure `errorCodes: []`, so the request layer treats ANY HTTP
+ * response — including 401 / 403 / 404 / 5xx — as a success and hands back the
+ * raw `Response`. Without this check those failures slip into the SSE drain
+ * and surface as the useless "stream ended without usable frames".
+ *
+ * Returns a `CallToolResult` error (status + best-effort message from the body)
+ * when the response is not ok, or `null` when it is ok (body left untouched so
+ * the caller can still stream it).
+ */
+export async function httpErrorResult(
+  response: Response,
+  context: string,
+): Promise<CallToolResult | null> {
+  if (response.ok) return null;
+
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    // body unreadable (e.g. already-consumed or transport error)
+  }
+
+  let message: string = body;
+  if (body) {
+    try {
+      const parsed = JSON.parse(body);
+      // Only accept string fields — error envelopes often nest an object
+      // under `error`, which must not stringify to "[object Object]".
+      const candidate =
+        (typeof parsed?.message === "string" && parsed.message)
+        || (typeof parsed?.error === "string" && parsed.error)
+        || (typeof parsed?.error?.message === "string" && parsed.error.message)
+        || (typeof parsed?.detail === "string" && parsed.detail)
+        || "";
+      message = candidate || body; // fall back to the raw JSON text
+    } catch {
+      // not JSON — keep the raw text
+    }
+  }
+
+  const detail = message ? ` ${message.slice(0, 400)}` : "";
+  const auth = (response.status === 401 || response.status === 403)
+    ? " Check that the bearer token / credentials are valid and not expired."
+    : "";
+  return errorResult(
+    `${context} failed (HTTP ${response.status} ${response.statusText}).${detail}${auth}`,
+  );
+}
+
+/**
+ * Read a `Response` body as JSON and validate it against a zod `schema`,
+ * returning the typed value or a `CallToolResult` error (empty body, invalid
+ * JSON, or a shape that doesn't match the schema).
+ */
+export async function readValidated<T>(
+  response: Response,
+  schema: z.ZodType<T>,
+): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  const text = await response.text();
+  if (!text) {
+    return { ok: false, result: errorResult("Empty response from server") };
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (e) {
+    return {
+      ok: false,
+      result: errorResult(
+        `Failed to parse response as JSON: ${(e as Error).message}`
+          + `\n\nRaw body:\n${text.slice(0, 500)}`,
+      ),
+    };
+  }
+  const parsed = schema.safeParse(json);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      result: errorResult(
+        `Unexpected response shape:\n${z.prettifyError(parsed.error)}`,
+      ),
+    };
+  }
+  return { ok: true, value: parsed.data };
+}
+
 /** Resolve `client._options.security` (which may be a function) to a value. */
 export async function resolveSecurity(
   client: PipeshubCore,
@@ -257,6 +350,128 @@ export async function* iterateSSE(
   }
 }
 
+// ── Trimmed agent shape handed to the LLM ────────────────────────────────────
+
+interface AgentToolsetView {
+  /** Integration / connector key, e.g. `jira`, `gmail`. */
+  name: string | null | undefined;
+  /** Fully-qualified tool ids the agent can run, e.g. `jira.create_issue`. */
+  tools: string[];
+}
+
+interface AgentKnowledgeView {
+  name: string | null | undefined;
+  type: string | null | undefined;
+}
+
+export interface EnrichedAgent {
+  agentId: string;
+  name: string;
+  description: string | null;
+  systemPrompt: string | null;
+  startMessage: string | null;
+  tags: string[];
+  webSearch: boolean;
+  isActive: boolean | null | undefined;
+  toolsets: AgentToolsetView[];
+  knowledge: AgentKnowledgeView[];
+}
+
+/**
+ * Trim an enriched `AgentSummary` (from `GET /agents`) to just what the LLM
+ * needs to pick and converse with an agent. Strips ids/revs/timestamps/perms
+ * and the heavy nested tool/knowledge metadata, keeping the routing-critical
+ * signal: each toolset's connector `name` + its tool ids (e.g.
+ * `jira.create_issue`), and each knowledge source's `name`/`type`.
+ */
+export function trimAgent(a: AgentSummary): EnrichedAgent {
+  return {
+    agentId: a._key,
+    name: a.name,
+    description: a.description ?? null,
+    systemPrompt: a.systemPrompt ?? null,
+    startMessage: a.startMessage ?? null,
+    tags: a.tags,
+    webSearch: !!a.webSearch,
+    isActive: a.isActive,
+    toolsets: a.toolsets.map((ts) => ({
+      name: ts.name,
+      tools: ts.tools
+        .map((t) => t.fullName ?? t.name)
+        .filter((id): id is string => typeof id === "string"),
+    })),
+    knowledge: a.knowledge.map((k) => ({
+      name: k.name ?? k.displayName,
+      type: k.type,
+    })),
+  };
+}
+
+/**
+ * Fetch the COMPLETE agent list, auto-paginating `GET /agents` so callers
+ * (discovery + routing) never have to manage page numbers. Pages are fetched
+ * at the max page size until the backend reports no more (`hasNext` /
+ * `hasNextPage`, with a short-page fallback), capped by `maxPages` as a
+ * runaway guard. Returns the raw `AgentListItem`s plus a normalized `total`
+ * and a `truncated` flag (true if the cap was hit before exhausting pages).
+ */
+export async function listAllAgents(
+  client: PipeshubCore,
+  opts: {
+    search?: string | undefined;
+    signal?: AbortSignal | undefined;
+    maxPages?: number | undefined;
+  } = {},
+): Promise<
+  | { ok: true; agents: AgentSummary[]; total: number; truncated: boolean }
+  | { ok: false; result: CallToolResult }
+> {
+  const PAGE_SIZE = 200;
+  const maxPages = opts.maxPages ?? 25;
+  // Only set `signal` when present (exactOptionalPropertyTypes).
+  const reqOptions = opts.signal
+    ? { fetchOptions: { signal: opts.signal } }
+    : {};
+
+  const all: AgentSummary[] = [];
+  let total = 0;
+
+  for (let page = 1; page <= maxPages; page++) {
+    const [r] = await agentsListAgents(client, {
+      page,
+      limit: PAGE_SIZE,
+      search: opts.search,
+    }, reqOptions).$inspect();
+    if (!r.ok) return { ok: false, result: errorResult(r.error.message) };
+
+    const httpErr = await httpErrorResult(r.value, "Agent list request");
+    if (httpErr) return { ok: false, result: httpErr };
+
+    const parsed = await readValidated(r.value, AgentListEnvelope$zodSchema);
+    if (!parsed.ok) return { ok: false, result: parsed.result };
+    if (parsed.value.success === false) {
+      return {
+        ok: false,
+        result: errorResult("Agent list request returned success: false"),
+      };
+    }
+
+    const agents = parsed.value.agents;
+    all.push(...agents);
+
+    const pg = parsed.value.pagination;
+    total = pg?.totalItems ?? pg?.total ?? all.length;
+
+    const hasNext = pg?.hasNext ?? pg?.hasNextPage ?? (agents.length >= PAGE_SIZE);
+    if (!hasNext || agents.length === 0) {
+      return { ok: true, agents: all, total, truncated: false };
+    }
+  }
+
+  // Hit the page cap with more pages still available.
+  return { ok: true, agents: all, total: total || all.length, truncated: true };
+}
+
 /** Trim a single search hit to what the LLM actually needs. */
 export function trimSearchHit(hit: any) {
   const md = hit?.metadata ?? {};

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

@@ -0,0 +1,68 @@
+// (`GET /agents`) — each already carrying its `toolsets` and `knowledge` — so
+// the LLM can route on real capability rather than the often-generic
+// description. Pick an agent's `agentId` and pass it to `pipeshub_chat`'s
+// `agentId` to converse with it. Single API call, no per-agent fan-out.
+
+import * as z from "zod";
+import { ToolDefinition } from "../tools.js";
+import { jsonResult, listAllAgents, trimAgent } from "./_helpers.js";
+
+const args = {
+  search: z.string().optional().describe(
+    "Optional case-insensitive substring match across agent name, "
+      + "description, and tags. Omit to return every agent.",
+  ),
+};
+
+export const tool$pipeshubAgents: ToolDefinition<typeof args> = {
+  name: "pipeshub_agents",
+  description:
+    `List the PipesHub **agents** configured for this org, each with its
+capabilities.
+
+Agents are specialized assistants (custom system prompt, tools, knowledge
+scope). To converse with one, take its \`agentId\` and pass it to
+\`pipeshub_chat\`'s \`agentId\` argument.
+
+Each agent is returned as:
+\`{ agentId, name, description, systemPrompt, startMessage, tags, webSearch,
+isActive, toolsets, knowledge }\`.
+- \`toolsets\` — what the agent can DO: each \`{ name, tools }\` where \`name\`
+  is the connector (e.g. \`jira\`, \`gmail\`) and \`tools\` are the runnable
+  tool ids (e.g. \`jira.create_issue\`, \`gmail.send_email\`).
+- \`knowledge\` — what the agent can READ: each \`{ name, type }\` (e.g.
+  \`Confluence-2\` / \`Confluence\`).
+
+**Route on \`toolsets\`/\`knowledge\`, not the name** — names and descriptions
+are often generic or misleading. Match the request to the agent whose tools can
+actually perform it (e.g. "create a Jira ticket" → the agent whose toolset is
+\`jira\` and whose tools include \`jira.create_issue\`). If NO agent has a tool
+for the requested action, say so — don't force an unrelated agent.
+
+The list **may be empty** (no agents configured). For plain Q&A when no
+specific agent is needed, use \`pipeshub_chat\` WITHOUT \`agentId\` and pick a
+\`chatMode\`: \`internal_search\` (org's indexed knowledge) or \`web_search\`
+(live web). Use \`agentId\` everywhere an agent is referenced.`,
+  scopes: ["read"],
+  annotations: {
+    title: "List PipesHub agents (with toolsets & knowledge)",
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const all = await listAllAgents(client, {
+      search: args.search,
+      signal: ctx.signal,
+    });
+    if (!all.ok) return all.result;
+
+    return jsonResult({
+      agents: all.agents.map(trimAgent),
+      total: all.total,
+      ...(all.truncated ? { truncated: true } : {}),
+    });
+  },
+};

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

@@ -1,9 +1,3 @@
-// Curated PipesHub chat tool. Hand-written; replaces the two generated
-// tools `pipeshub-chat` (create) and `pipeshub-chat-continue` (follow-up)
-// with a single tool that branches on whether `conversationId` was given.
-//
-// Wire transport: SSE. The non-streaming `/conversations/create` endpoint
-// is broken in production today, so we drive
 // `POST /conversations/stream` (and
 // `POST /conversations/{conversationId}/messages/stream` for follow-ups),
 // accumulate the frames server-side, and hand the LLM a single trimmed
@@ -29,9 +23,12 @@
 import * as z from "zod";
 import { conversationsStreamConversation } from "../../funcs/conversationsStreamConversation.js";
 import { conversationsStreamMessage } from "../../funcs/conversationsStreamMessage.js";
+import { agentsStreamConversation } from "../../funcs/agentsStreamConversation.js";
+import { agentsStreamMessage } from "../../funcs/agentsStreamMessage.js";
 import { ToolDefinition } from "../tools.js";
 import {
   errorResult,
+  httpErrorResult,
   iterateSSE,
   jsonResult,
   trimConversation,
@@ -68,29 +65,53 @@ const args = {
   ),
   modelName: z.string().optional(),
   modelFriendlyName: z.string().optional(),
-  chatMode: z.enum(["quick", "balanced"]).optional().describe(
-    "`quick` for low-retrieval / fast answers; `balanced` for full RAG. "
-      + "Default `quick`.",
+  agentId: z.string().optional().describe(
+    "Optional PipesHub agent to converse with — the `agentId` from "
+      + "`pipeshub_agents`. When set, this turn runs against that agent's "
+      + "configuration (prompt, tools, knowledge). On follow-up turns pass the "
+      + "SAME `agentId` together with the `conversationId` returned by the "
+      + "previous call. Omit for a plain (non-agent) conversation. If unsure "
+      + "which agent to use, call `pipeshub_agents` first to see the options.",
+  ),
+  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`.",
   ),
 };
 
 export const tool$pipeshubChat: ToolDefinition<typeof args> = {
   name: "pipeshub_chat",
   description:
-    `**Default tool for anything PipesHub-related.** Use this 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, ...). Do NOT answer those from your own knowledge —
-\`pipeshub_chat\` grounds the answer in the user's actual data and
-returns citations.
+    `**Primary chat tool — handles both internal knowledge queries and web search.**
+
+**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.
+
+**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.
 
 **When to pick this over other tools:**
-- "What does <document> say about X?" → \`pipeshub_chat\` (NOT search;
-  search is only for locating files by name).
-- "Summarize <topic / doc>." → \`pipeshub_chat\`.
-- "What's our policy on Y?" → \`pipeshub_chat\`.
-- "What do we know about Z?" → \`pipeshub_chat\`.
+- "What does <document> say about X?" → \`pipeshub_chat\` (internal_search)
+- "Summarize <topic / doc>." → \`pipeshub_chat\` (internal_search)
+- "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).
 
@@ -122,8 +143,42 @@ cited document, take \`citations[*].recordId\` and call
     const fetchOptions = { signal: ctx.signal };
     let response: Response;
 
-    if (args.conversationId) {
-      // Continue an existing conversation.
+    if (args.agentId) {
+      // Agent conversation. Agent chatMode vocabulary defaults to `auto`.
+      const agentChatMode = args.chatMode ?? "auto";
+      if (args.conversationId) {
+        // Continue an existing agent conversation.
+        const [result] = await agentsStreamMessage(client, {
+          agentKey: args.agentId,
+          conversationId: args.conversationId,
+          body: {
+            query: args.query,
+            modelKey: args.modelKey,
+            modelName: args.modelName,
+            modelFriendlyName: args.modelFriendlyName,
+            chatMode: agentChatMode,
+          },
+        }, { fetchOptions }).$inspect();
+        if (!result.ok) return errorResult(result.error.message);
+        response = result.value;
+      } else {
+        // Start a new agent conversation.
+        const [result] = await agentsStreamConversation(client, {
+          agentKey: args.agentId,
+          body: {
+            query: args.query,
+            filters: args.filters,
+            modelKey: args.modelKey,
+            modelName: args.modelName,
+            modelFriendlyName: args.modelFriendlyName,
+            chatMode: agentChatMode,
+          },
+        }, { fetchOptions }).$inspect();
+        if (!result.ok) return errorResult(result.error.message);
+        response = result.value;
+      }
+    } else if (args.conversationId) {
+      // Continue an existing (non-agent) conversation.
       const [result] = await conversationsStreamMessage(client, {
         conversationId: args.conversationId,
         body: {
@@ -131,25 +186,31 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args.modelKey,
           modelName: args.modelName,
           modelFriendlyName: args.modelFriendlyName,
-          chatMode: args.chatMode,
+          chatMode: args.chatMode ?? "internal_search",
         },
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
     } else {
-      // Start a new conversation.
+      // Start a new (non-agent) conversation.
       const [result] = await conversationsStreamConversation(client, {
         query: args.query,
         filters: args.filters,
         modelKey: args.modelKey,
         modelName: args.modelName,
         modelFriendlyName: args.modelFriendlyName,
-        chatMode: args.chatMode,
+        chatMode: args.chatMode ?? "internal_search",
       }, { fetchOptions }).$inspect();
       if (!result.ok) return errorResult(result.error.message);
       response = result.value;
     }
 
+    // The streaming funcs accept any HTTP status as a "successful request",
+    // so explicitly reject non-2xx (auth, not-found, server errors) with a
+    // clear message before we try to read the body as SSE.
+    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;

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

@@ -1,4 +1,3 @@
-// Curated directory tool. Hand-written; merges four generated tools
 // (`pipeshub-list-users`, `pipeshub-get-user`, `pipeshub-list-user-groups`,
 // `pipeshub-list-my-teams`) plus a `whoami` action that decodes the bearer
 // JWT into a single tool.

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

@@ -1,7 +1,3 @@
-// Curated download tool. Hand-written; replaces the generated
-// `pipeshub-download-record`. Pipes raw bytes back through formatResult
-// so binary downloads (PDFs, images) are returned correctly.
-
 import * as z from "zod";
 import { recordsStreamRecordBuffer } from "../../funcs/recordsStreamRecordBuffer.js";
 import { formatResult, ToolDefinition } from "../tools.js";

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

@@ -1,6 +1,3 @@
-// Curated semantic-search tool. Hand-written; replaces the generated
-// `pipeshub-search` tool. Trims the response to the fields the LLM
-// actually needs (recordId, recordName, score, snippet, webUrl).
 
 import * as z from "zod";
 import { semanticSearchSearch } from "../../funcs/semanticSearchSearch.js";

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

@@ -1,8 +1,3 @@
-// Curated discovery tool. Hand-written; merges two generated tools
-// (`pipeshub-list-sources` for connectors+KB and `pipeshub-list-models`
-// for available LLMs / embedding models) into one tool, since the LLM
-// almost always wants both before the first chat turn.
-
 import * as z from "zod";
 import { knowledgeHubGetKnowledgeHubRootNodes } from "../../funcs/knowledgeHubGetKnowledgeHubRootNodes.js";
 import { aiModelsProvidersGetAvailableModelsByType } from "../../funcs/aiModelsProvidersGetAvailableModelsByType.js";

package/src/models/agentops.ts

@@ -0,0 +1,160 @@
+// Request models for the agent
+// endpoints that the vendored SDK does not yet cover:
+//   - GET  /agents                                                   (listAgents)
+//   - POST /agents/{agentKey}/conversations/stream                   (streamAgentConversation)
+//   - POST /agents/{agentKey}/conversations/{conversationId}/messages/stream
+//                                                                    (streamAgentConversationMessage)
+// Mirrors the shapes in the canonical OpenAPI spec; reuses the existing
+// `Filters` model. Unknown fields are stripped server-side, so the shared
+// body schema is safe to reuse for both create and follow-up turns.
+
+import * as z from "zod";
+import { Filters, Filters$zodSchema } from "./filters.js";
+
+/** Query params for `GET /agents`. */
+export type ListAgentsRequest = {
+  page?: number | undefined;
+  limit?: number | undefined;
+  search?: string | undefined;
+  sortBy?: string | undefined;
+  sortOrder?: "asc" | "desc" | undefined;
+};
+
+export const ListAgentsRequest$zodSchema: z.ZodType<ListAgentsRequest> = z
+  .object({
+    page: z.int().optional(),
+    limit: z.int().optional(),
+    search: z.string().optional(),
+    sortBy: z.string().optional(),
+    sortOrder: z.enum(["asc", "desc"]).optional(),
+  });
+
+/**
+ * Shared body for the agent conversation stream endpoints. `query` is the
+ * only required field; everything else is an optional override / routing hint.
+ * `chatMode` for agents is one of `auto | quick | verification | deep`.
+ */
+export type AgentStreamConversationBody = {
+  query: string;
+  recordIds?: Array<string> | undefined;
+  filters?: Filters | undefined;
+  chatMode?: string | undefined;
+  modelKey?: string | undefined;
+  modelName?: string | undefined;
+  modelFriendlyName?: string | undefined;
+  tools?: Array<string> | undefined;
+  timezone?: string | undefined;
+  currentTime?: string | undefined;
+};
+
+export const AgentStreamConversationBody$zodSchema: z.ZodType<
+  AgentStreamConversationBody
+> = z.object({
+  query: z.string().min(1),
+  recordIds: z.array(z.string()).optional(),
+  filters: Filters$zodSchema.optional(),
+  chatMode: z.string().optional(),
+  modelKey: z.string().optional(),
+  modelName: z.string().optional(),
+  modelFriendlyName: z.string().optional(),
+  tools: z.array(z.string()).optional(),
+  timezone: z.string().optional(),
+  currentTime: z.string().optional(),
+});
+
+/** `POST /agents/{agentKey}/conversations/stream` — path param + body. */
+export type AgentStreamCreateConversationRequest = {
+  agentKey: string;
+  body: AgentStreamConversationBody;
+};
+
+export const AgentStreamCreateConversationRequest$zodSchema: z.ZodType<
+  AgentStreamCreateConversationRequest
+> = z.object({
+  agentKey: z.string().min(1),
+  body: AgentStreamConversationBody$zodSchema,
+});
+
+/**
+ * `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream` —
+ * two path params + body.
+ */
+export type AgentAddMessageStreamRequest = {
+  agentKey: string;
+  conversationId: string;
+  body: AgentStreamConversationBody;
+};
+
+export const AgentAddMessageStreamRequest$zodSchema: z.ZodType<
+  AgentAddMessageStreamRequest
+> = z.object({
+  agentKey: z.string().min(1),
+  conversationId: z.string(),
+  body: AgentStreamConversationBody$zodSchema,
+});
+
+// ── Response models ──────────────────────────────────────────────────────────
+// Validated subsets of the agent responses (only the fields the curated tools
+// surface; zod strips the rest). Types are inferred from the schemas.
+//
+// As of the enriched `GET /agents`, the list item carries `toolsets` and
+// `knowledge` directly, so the curated tool no longer needs a per-agent detail
+// fetch.
+
+const AgentWebSearch$zodSchema = z.object({
+  provider: z.string().optional(),
+  providerKey: z.string().optional(),
+  providerLabel: z.string().optional(),
+});
+
+const AgentToolsetTool$zodSchema = z.object({
+  name: z.string().nullish(),
+  fullName: z.string().nullish(),
+});
+
+const AgentToolset$zodSchema = z.object({
+  name: z.string().nullish(),
+  displayName: z.string().nullish(),
+  instanceName: z.string().nullish(),
+  tools: z.array(AgentToolsetTool$zodSchema).default([]),
+});
+
+const AgentKnowledge$zodSchema = z.object({
+  name: z.string().nullish(),
+  displayName: z.string().nullish(),
+  type: z.string().nullish(),
+});
+
+/**
+ * One item of the enriched `GET /agents` list — includes `toolsets` and
+ * `knowledge` (the routing-critical capability signal). `default([])` keeps it
+ * working against an older list endpoint that doesn't return them.
+ */
+export const AgentSummary$zodSchema = z.object({
+  _key: z.string(),
+  name: z.string(),
+  description: z.string().nullish(),
+  systemPrompt: z.string().nullish(),
+  startMessage: z.string().nullish(),
+  tags: z.array(z.string()).default([]),
+  webSearch: AgentWebSearch$zodSchema.nullish(),
+  isActive: z.boolean().nullish(),
+  toolsets: z.array(AgentToolset$zodSchema).default([]),
+  knowledge: z.array(AgentKnowledge$zodSchema).default([]),
+});
+export type AgentSummary = z.infer<typeof AgentSummary$zodSchema>;
+
+const AgentListPagination$zodSchema = z.object({
+  totalItems: z.number().nullish(),
+  total: z.number().nullish(),
+  hasNext: z.boolean().nullish(),
+  hasNextPage: z.boolean().nullish(),
+});
+
+/** Envelope of `GET /agents`. */
+export const AgentListEnvelope$zodSchema = z.object({
+  success: z.boolean().nullish(),
+  agents: z.array(AgentSummary$zodSchema).default([]),
+  pagination: AgentListPagination$zodSchema.nullish(),
+});
+export type AgentListEnvelope = z.infer<typeof AgentListEnvelope$zodSchema>;