@pipeshub-ai/mcp 2.0.1 → 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,16 +65,28 @@ const args = {
   ),
   modelName: z.string().optional(),
   modelFriendlyName: z.string().optional(),
-  chatMode: z.enum(["web_search", "internal_search"]).optional().describe(
-    "Controls retrieval source. "
-      + "`internal_search` (default) — searches the org's indexed knowledge "
-      + "bases (Drive, Confluence, Slack, Gmail, Jira, Box, etc.) and returns "
-      + "citations. Use this for questions about internal docs, policies, or "
-      + "company data. "
-      + "`web_search` — searches the public web instead of internal sources. "
-      + "Use only when the user explicitly asks about current events, public "
-      + "information, or anything not expected to be in the org's KB. "
-      + "Omit this field (or pass `internal_search`) for all normal queries.",
+  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`.",
   ),
 };
 
@@ -134,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: {
@@ -143,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>;

package/src/tool-names.ts

@@ -19,5 +19,9 @@ export const toolNames: Array<{ name: string; description: string }>= [
   {
     "name": "pipeshub_directory",
     "description": "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
+  },
+  {
+    "name": "pipeshub_agents",
+    "description": "List the PipesHub **agents** configured for this org, each with its\ncapabilities.\n\nAgents are specialized assistants (custom system prompt, tools, knowledge\nscope). To converse with one, take its `agentId` and pass it to\n`pipeshub_chat`'s `agentId` argument.\n\nEach agent is returned as:\n`{ agentId, name, description, systemPrompt, startMessage, tags, webSearch,\nisActive, toolsets, knowledge }`.\n- `toolsets` — what the agent can DO: each `{ name, tools }` where `name`\n  is the connector (e.g. `jira`, `gmail`) and `tools` are the runnable\n  tool ids (e.g. `jira.create_issue`, `gmail.send_email`).\n- `knowledge` — what the agent can READ: each `{ name, type }` (e.g.\n  `Confluence-2` / `Confluence`).\n\n**Route on `toolsets`/`knowledge`, not the name** — names and descriptions\nare often generic or misleading. Match the request to the agent whose tools can\nactually perform it (e.g. \"create a Jira ticket\" → the agent whose toolset is\n`jira` and whose tools include `jira.create_issue`). If NO agent has a tool\nfor the requested action, say so — don't force an unrelated agent.\n\nThe list **may be empty** (no agents configured). For plain Q&A when no\nspecific agent is needed, use `pipeshub_chat` WITHOUT `agentId` and pick a\n`chatMode`: `internal_search` (org's indexed knowledge) or `web_search`\n(live web). Use `agentId` everywhere an agent is referenced."
   }
 ];