@ziggs-ai/agent-sdk 0.11.1 → 0.13.0

package/dist/server/tools/tier2/mcpConnectionTools.js

@@ -89,19 +89,145 @@ export const mcpToolsListTool = defineTool('mcp_tools_list', {
         type: 'string',
         description: 'Grant to use. Omit to use the live grant found on that connection.',
     },
+    names: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Tool names to return the FULL parameters (inputSchema) for. Omit to get the names and descriptions only — a whole server of schemas is tens of thousands of characters and gets cut, which is worse than not asking.',
+    },
 }, async (args, ctx) => {
     const t = await resolveTarget(ctx, args['connectionId'], args['grantId']);
+    /**
+     * Names first, schemas on demand — the same two-step this platform's own MCP
+     * surface settled on. One Linear server answers 53 tools and 78,000
+     * characters of schema; asking for all of it fills a wake with parameters for
+     * tools the agent will not call, and the cut lands mid-schema where the half
+     * that survives still looks complete.
+     */
+    const wanted = args['names']?.filter((n) => typeof n === 'string' && n);
     const tools = await withClient(ctx, t.connectionId, t.grantId, async (c) => {
         const res = await c.listTools();
-        return (res.tools ?? []).map((tool) => ({
+        const rows = res.tools ?? [];
+        const picked = wanted?.length ? rows.filter((tool) => wanted.includes(tool.name)) : rows;
+        return picked.map((tool) => ({
             name: tool.name,
             description: tool.description ?? null,
+            /**
+             * The parameters, which this used to drop.
+             *
+             * Without them an agent has to GUESS what a tool takes, and a guessed
+             * argument is not an error — most servers ignore what they do not know
+             * and answer with an empty list. That empty list then reads as "nothing
+             * happened": a weekly digest reported one item shipped for a week with
+             * fifty, because `status`, `filter.state.name` and `updatedAfter` were
+             * all invented and all silently matched nothing.
+             */
+            ...(wanted?.length ? { inputSchema: tool.inputSchema ?? null } : {}),
         }));
     });
-    return { connectionId: t.connectionId, grantId: t.grantId, tools };
+    const missing = wanted?.filter((n) => !tools.some((row) => row.name === n)) ?? [];
+    const bounded = boundMcpResult({ tools }, MAX_MCP_TOOLS_LIST_CHARS);
+    return {
+        connectionId: t.connectionId,
+        grantId: t.grantId,
+        ...bounded.result,
+        ...(bounded.truncated ? { truncated: bounded.truncated } : {}),
+        ...(missing.length ? { notFound: missing } : {}),
+        ...(wanted?.length
+            ? {}
+            : {
+                note: 'Names and descriptions only. Call again with names:["<tool>"] to get that tool\'s parameters before you pass any arguments — a parameter the server does not declare is usually ignored, and the empty result reads as real emptiness.',
+            }),
+    };
 }, {
-    description: "List the tools a connected MCP server exposes, through the Ziggs gateway — the owner's credential stays server-side. The grant may allow only some of them; a call outside the grant is refused by the gateway, not by you.",
+    description: "List the tools a connected MCP server exposes, through the Ziggs gateway. Names and descriptions by default; pass names:[\"<tool>\"] for those tools' full parameters (inputSchema) — the owner's credential stays server-side. Read the schema before calling a tool with arguments: a parameter the server does not declare is usually ignored rather than rejected, so a guessed filter comes back as an empty result that looks like real emptiness. The grant may allow only some tools; a call outside it is refused by the gateway, not by you.",
 });
+/**
+ * How much of one MCP tool result a wake will carry.
+ *
+ * A remote MCP server hands back the upstream API's payload verbatim, and those
+ * are sized for programs, not for a context window: GitHub's `list_pull_requests`
+ * with no paging argument answered ~150,000 characters. Past the runtime's limit
+ * the result stops being a result — the Claude SDK spills an oversized tool
+ * result to a file, and a hosted agent has no filesystem tool to read it with, so
+ * the wake ends in "the answer was too big and I cannot see it". Same class of
+ * problem as an MCP server that ships a 30K-character tool description, one layer
+ * later.
+ *
+ * A bounded answer with a marker beats an unreadable one: the model can act on
+ * "truncated, narrow the call", and it cannot act on a file path.
+ */
+export const MAX_MCP_RESULT_CHARS = 24_000;
+/**
+ * Tool schemas are bigger than tool results and are read once per wake, so they
+ * get their own, larger ceiling — a schema cut in half is worse than useless,
+ * because the half that survives looks complete.
+ */
+export const MAX_MCP_TOOLS_LIST_CHARS = 60_000;
+const TRUNCATION_ADVICE = 'Narrow the call instead of repeating it: most servers take paging (perPage/page) ' +
+    'or filter arguments, and a named target usually has a narrower tool than a list.';
+/**
+ * Bound one MCP result, telling the model plainly what was cut.
+ *
+ * Text blocks are cut individually rather than the JSON being sliced, because a
+ * sliced JSON string is invalid and a model handed invalid JSON reports the
+ * server as broken.
+ */
+export function boundMcpResult(result, max = MAX_MCP_RESULT_CHARS) {
+    const whole = JSON.stringify(result) ?? '';
+    if (whole.length <= max)
+        return { result };
+    const content = result?.content;
+    if (!Array.isArray(content)) {
+        return {
+            result: { text: whole.slice(0, max) },
+            truncated: {
+                originalChars: whole.length,
+                keptChars: max,
+                note: `Result was ${whole.length} characters and is cut to ${max}. ${TRUNCATION_ADVICE}`,
+            },
+        };
+    }
+    const kept = [];
+    let used = 0;
+    let dropped = 0;
+    for (const block of content) {
+        const text = block?.text;
+        if (typeof text !== 'string') {
+            const size = (JSON.stringify(block) ?? '').length;
+            if (used + size > max) {
+                dropped += 1;
+                continue;
+            }
+            used += size;
+            kept.push(block);
+            continue;
+        }
+        const room = max - used;
+        if (room <= 0) {
+            dropped += 1;
+            continue;
+        }
+        if (text.length <= room) {
+            used += text.length;
+            kept.push(block);
+            continue;
+        }
+        kept.push({
+            ...block,
+            text: `${text.slice(0, room)}\n\n[…cut here: this block was ${text.length} characters]`,
+        });
+        used = max;
+    }
+    return {
+        result: { ...result, content: kept },
+        truncated: {
+            originalChars: whole.length,
+            keptChars: used,
+            droppedBlocks: dropped,
+            note: `Result was ${whole.length} characters, over the ${max}-character limit, so it is cut. What you have is the beginning, not the whole answer — do not report it as complete. ${TRUNCATION_ADVICE}`,
+        },
+    };
+}
 export const mcpToolCallTool = defineTool('mcp_tool_call', {
     tool: {
         type: 'string',
@@ -125,12 +251,18 @@ export const mcpToolCallTool = defineTool('mcp_tool_call', {
     if (!name)
         throw new Error('tool is required');
     const t = await resolveTarget(ctx, args['connectionId'], args['grantId']);
-    const result = await withClient(ctx, t.connectionId, t.grantId, (c) => c.callTool({
+    const raw = await withClient(ctx, t.connectionId, t.grantId, (c) => c.callTool({
         name,
         arguments: args['args'] ?? {},
     }));
-    return { connectionId: t.connectionId, tool: name, result };
+    const bounded = boundMcpResult(raw);
+    return {
+        connectionId: t.connectionId,
+        tool: name,
+        result: bounded.result,
+        ...(bounded.truncated ? { truncated: bounded.truncated } : {}),
+    };
 }, {
-    description: "Call one tool on a connected MCP server through the Ziggs gateway. Use this for a connection whose provider is a remote MCP server — connection_proxy is for named connectors (github, jira) and refuses these with \"Unknown provider: mcp\". The gateway injects the owner's token upstream and checks the tool name against your grant, so you never hold the credential. Discover names with mcp_tools_list, or read allowed_actions off the grant in grant_list.",
+    description: "Call one tool on a connected MCP server through the Ziggs gateway. Use this for a connection whose provider is a remote MCP server — connection_proxy is for named connectors (github, jira) and refuses these with \"Unknown provider: mcp\". The gateway injects the owner's token upstream and checks the tool name against your grant, so you never hold the credential. Discover names with mcp_tools_list, or read allowed_actions off the grant in grant_list. Results are bounded: a payload over the limit comes back cut, with a `truncated` field saying so — pass the server's paging or filter arguments rather than repeating the call.",
 });
 export const MCP_CONNECTION_TOOLS = [mcpToolsListTool, mcpToolCallTool];

package/dist/server/tools/tier2/paymentTools.d.ts

@@ -1,11 +1,3 @@
 import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const paymentBalanceTool: ToolDefinition;
-export declare const paymentTransferTool: ToolDefinition;
-export declare const paymentWaitForApprovalTool: ToolDefinition;
-export declare const paymentHoldTool: ToolDefinition;
-export declare const paymentReleaseTool: ToolDefinition;
-export declare const paymentResolveWalletTool: ToolDefinition;
-export declare const paymentIssueGrantTool: ToolDefinition;
-export declare const paymentAttenuateGrantTool: ToolDefinition;
-export declare const paymentRevokeGrantTool: ToolDefinition;
 export declare const PAYMENT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/paymentTools.js

@@ -1,16 +1,12 @@
-import { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from '@ziggs-ai/api-client';
+import { PAYMENT_CAPABILITIES, paymentBalanceCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
 // the wallet toolset is defined once in api-client's shared
-// capability layer; this file only adapts it onto the SDK surface. Safety is
-// unchanged: money-moving calls stay policy-gated server-side, and there is
-// deliberately NO approve/decide tool on the agent surface.
+// capability layer; this file only adapts it onto the SDK surface.
+//
+// The movement verbs are gone from both agent surfaces —
+// transfer, hold, release, wait_for_approval, resolve_wallet, and the three
+// grant mutations. Points are a meter, and an agent does not move the meter on
+// its own. Agreements still settle in points server-side, so nothing an agent
+// needs in order to be paid went with them. Reading your own balance survives.
 export const paymentBalanceTool = toolFromCapability(paymentBalanceCapability);
-export const paymentTransferTool = toolFromCapability(paymentTransferCapability);
-export const paymentWaitForApprovalTool = toolFromCapability(paymentWaitForApprovalCapability);
-export const paymentHoldTool = toolFromCapability(paymentHoldCapability);
-export const paymentReleaseTool = toolFromCapability(paymentReleaseCapability);
-export const paymentResolveWalletTool = toolFromCapability(paymentResolveWalletCapability);
-export const paymentIssueGrantTool = toolFromCapability(paymentIssueGrantCapability);
-export const paymentAttenuateGrantTool = toolFromCapability(paymentAttenuateGrantCapability);
-export const paymentRevokeGrantTool = toolFromCapability(paymentRevokeGrantCapability);
 export const PAYMENT_TOOLS = toolsFromCapabilities(PAYMENT_CAPABILITIES);

package/dist/types.d.ts

@@ -4,15 +4,11 @@
  * One outcome vocabulary, one ctx shape, one transition signature.
  * Every state — parked or thinking — re-enters with exactly one Outcome.
  */
+import type { AgreementParties } from '@ziggs-ai/api-client';
 import type { AgentNeed } from './tools/needs.js';
 export interface AgreementRef {
     agreementId: string;
-    parties?: {
-        creator?: string;
-        provider?: string;
-        payer?: string;
-        proposedTo?: string;
-    };
+    parties?: AgreementParties;
     proposal?: {
         status?: 'pending' | 'approved' | 'rejected' | 'cancelled';
     };
@@ -328,11 +324,23 @@ export interface LlmResponse {
         completionTokens?: number;
     };
 }
+/**
+ * One participant on the snapshot roster. `kind` is the declared holder kind the
+ * server projection stamped, so a consumer reads what a participant IS instead
+ * of inferring it from which array the row arrived in. Optional because a
+ * backend that predates it simply omits the field.
+ */
+export interface SnapshotParticipant {
+    role?: string;
+    kind?: string;
+    isYou?: boolean;
+    [key: string]: unknown;
+}
 export interface ContextSnapshot {
     history: HistoryEntry[];
     agreements: unknown[];
-    agents: unknown[];
-    users: unknown[];
+    agents: SnapshotParticipant[];
+    users: SnapshotParticipant[];
     timelineSummary?: string | null;
     latestSequence?: string | null;
     unavailable?: boolean;
@@ -472,10 +480,17 @@ export type Effect = {
     stateId?: string;
     /** Replay-stable write keys for this wake — write-capable tools derive their idempotency key from here, never from the LLM. */
     writeKeys?: DeliveryWriteKeys;
-} | {
+}
+/**
+ * `receiverId` is optional: in a room with one other participant the backend
+ * resolves the recipient from the room itself, which is the only answer
+ * available when the wake's sender belongs to a DIFFERENT room.
+ * Name a receiver whenever the room holds more than two parties.
+ */
+ | {
     kind: 'send-message';
     sessionId: string;
-    receiverId: string;
+    receiverId?: string;
     text: string;
     messageId?: string;
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.10.4",
+    "@ziggs-ai/api-client": "0.12.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",

package/dist/server/questMatch.d.ts

@@ -1,5 +0,0 @@
-/**
- * exact-match triage for marketplace quests.
- * Empty match never hits (token-safe default). Comparison is exact after trim.
- */
-export declare function questExactMatch(match: string, tags: ReadonlyArray<string | null | undefined>): boolean;