@ziggs-ai/agent-sdk 0.11.0 → 0.12.0

package/dist/server/tools/tier1/protocolRunner.js

@@ -63,7 +63,7 @@ cachedAgreements) {
                 return null;
             return agreementService.respond(payload.agreementId, payload.action);
         case 'agreement-claim': {
-            // the one claim verb — quest, standing offer, or link invite.
+            // the one claim verb — request, standing offer, or link invite.
             if (!payload.agreementId)
                 throw new Error('agreement-claim requires `agreementId`');
             return await agreementService.claim(payload.agreementId);
@@ -240,7 +240,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
                 audience: payload.proposedTo === 'org' ? 'org' : 'everyone',
             });
         }
-        throw new Error('On a broadcast, providerId must be your own agent id (a standing offer) or omitted (a quest — the claiming agent fills the open side).');
+        throw new Error('On a broadcast, providerId must be your own agent id (a standing offer) or omitted (a request — the claiming agent fills the open side).');
     }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;

package/dist/server/tools/tier1/protocolTools.js

@@ -43,10 +43,10 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a quest broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a QUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose (or link_create_invite when you lack the agent id). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
-export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
-export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
-export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose (or link_create_invite when you lack the agent id). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
+export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
+export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (requests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
+export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (request / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
@@ -54,10 +54,10 @@ export const taskSetResultTool = defineTool('task_set_result', {
     // Same object contract as MCP ({ summary, status, links, … }).
     result: {
         type: 'object',
-        description: 'Outcome payload (summary, status, links, …). Finished work is the task result — never a chat message.',
+        description: 'Outcome payload (summary, status, links, …). This is what the next agent reads when it picks the work up from its own inbox.',
     },
-}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Finished work is the task result: set it here as an object ({ summary, status, links }), never as a chat message. Pass state (not status).' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+}, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status).' });
+export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
 export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });

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

@@ -1,9 +1,9 @@
 import { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// the marketplace read (quests AND standing offers),
+// the marketplace read (requests AND standing offers),
 // defined once in api-client's shared capability layer. Publishing is NOT
 // here: it is the tier-1 verb agreement_propose with proposedTo
-// "everyone" | "org" (providerId = own id for an offer, omitted for a quest);
+// "everyone" | "org" (providerId = own id for an offer, omitted for a request);
 // claiming is agreement_claim.
 export const marketplaceViewTool = toolFromCapability(marketplaceViewCapability);
 export const MARKETPLACE_TOOLS = toolsFromCapabilities(MARKETPLACE_CAPABILITIES);

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

@@ -1,4 +1,37 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const mcpToolsListTool: ToolDefinition;
+/**
+ * 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 declare const MAX_MCP_RESULT_CHARS = 24000;
+/**
+ * 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 declare const MAX_MCP_TOOLS_LIST_CHARS = 60000;
+/**
+ * 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 declare function boundMcpResult(result: unknown, max?: number): {
+    result: unknown;
+    truncated?: Record<string, unknown>;
+};
 export declare const mcpToolCallTool: ToolDefinition;
 export declare const MCP_CONNECTION_TOOLS: ToolDefinition[];

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

@@ -4,7 +4,7 @@ import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
 import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
 /**
- * ZIG-1104 — calling a tool on a connected MCP server, one shot.
+ * Calling a tool on a connected MCP server, one shot.
  *
  * `connection_proxy` cannot do this. That path resolves a NAMED connector from
  * `connection.provider` and checks the action against its fixed action list; a
@@ -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/tools/ToolManager.d.ts

@@ -1,5 +1,5 @@
 import { ToolProvider } from './ToolProvider.js';
-import type { ToolDefinition } from './defineTool.js';
+import { type ToolDefinition } from './defineTool.js';
 export declare class ToolManager extends ToolProvider {
     private tools;
     constructor();

package/dist/tools/ToolManager.js

@@ -1,5 +1,6 @@
 import AjvModule from 'ajv';
 import { ToolProvider } from './ToolProvider.js';
+import { toolName } from './defineTool.js';
 const AjvClass = AjvModule.default ?? AjvModule;
 const ajv = new AjvClass({ allErrors: true, strict: false });
 function makeError(message, type, extra) {
@@ -49,7 +50,7 @@ export class ToolManager extends ToolProvider {
             throw makeError('Tool must have a schema', 'invalid_tool');
         if (typeof tool.handler !== 'function')
             throw makeError('Tool must have a handler function', 'invalid_tool');
-        const name = (tool.schema.function?.['name'] || tool.schema['name']);
+        const name = toolName(tool);
         if (!name)
             throw makeError('Tool schema must have a name', 'invalid_tool');
         this.tools.set(name, tool);

package/dist/tools/defineTool.d.ts

@@ -24,4 +24,11 @@ export interface DefineToolOptions {
     isAgreementCreation?: boolean;
     isGenericFallback?: boolean;
 }
+/**
+ * The name a tool registers under. `defineTool` always writes
+ * `schema.function.name`, but hand-built and capability-adapted schemas have put
+ * it at the top level too, so both are read — in one place, rather than at every
+ * call site that needs to identify a tool.
+ */
+export declare function toolName(tool: ToolDefinition | undefined): string | undefined;
 export declare function defineTool(name: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>, options?: DefineToolOptions): ToolDefinition;

package/dist/tools/defineTool.js

@@ -43,6 +43,18 @@ function convertObject(fields) {
         result['required'] = required;
     return result;
 }
+/**
+ * The name a tool registers under. `defineTool` always writes
+ * `schema.function.name`, but hand-built and capability-adapted schemas have put
+ * it at the top level too, so both are read — in one place, rather than at every
+ * call site that needs to identify a tool.
+ */
+export function toolName(tool) {
+    const fromFunction = tool?.schema?.function?.['name'];
+    const fromTop = tool?.schema?.['name'];
+    const name = fromFunction ?? fromTop;
+    return typeof name === 'string' && name ? name : undefined;
+}
 export function defineTool(name, params, handler, options = {}) {
     if (!name || typeof name !== 'string')
         throw new Error('defineTool: name is required');

package/dist/tools/needs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * Scope is agents built on this SDK.
+ */
+import { type ToolDefinition } from './defineTool.js';
+/**
+ * A remote MCP server is stored as `provider: 'mcp'` and goes through the
+ * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export declare const MCP_PROVIDER = "mcp";
+/**
+ * One shape for now, the one we have actually hit. A second kind means a case in
+ * {@link toolsForNeed}: a need nothing derives tools from is a need nothing
+ * enforces.
+ */
+export interface ConnectionNeed {
+    /** Provider, e.g. 'mcp' or a named connector like 'github'. */
+    connection: string;
+}
+export type AgentNeed = ConnectionNeed;
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export declare function normalizeNeeds(input: unknown): AgentNeed[];
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export declare function toolsForNeed(need: AgentNeed): ToolDefinition[];
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export declare function toolsForNeeds(needs: AgentNeed[]): ToolDefinition[];
+/** One line naming what is missing, for a refusal a human can act on. */
+export declare function describeNeed(need: AgentNeed): string;
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export declare function unmetNeeds(needs: AgentNeed[], providers: Array<string | null | undefined>): AgentNeed[];
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export declare function unmetNeedsMessage(unmet: AgentNeed[]): string;

package/dist/tools/needs.js

@@ -0,0 +1,84 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * Scope is agents built on this SDK.
+ */
+import { toolName } from './defineTool.js';
+import { connectionListGrantsTool, connectionProxyTool } from '../server/tools/tier2/connectionTools.js';
+import { MCP_CONNECTION_TOOLS } from '../server/tools/tier2/mcpConnectionTools.js';
+/**
+ * A remote MCP server is stored as `provider: 'mcp'` and goes through the
+ * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export const MCP_PROVIDER = 'mcp';
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export function normalizeNeeds(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const raw of input) {
+        const connection = raw?.connection;
+        if (typeof connection === 'string' && connection.trim()) {
+            out.push({ connection: connection.trim() });
+        }
+    }
+    return out;
+}
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export function toolsForNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? [connectionListGrantsTool, ...MCP_CONNECTION_TOOLS]
+        : [connectionListGrantsTool, connectionProxyTool];
+}
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export function toolsForNeeds(needs) {
+    const byName = new Map();
+    for (const need of needs) {
+        for (const tool of toolsForNeed(need)) {
+            const name = toolName(tool);
+            if (name)
+                byName.set(name, tool);
+        }
+    }
+    return [...byName.values()];
+}
+/** One line naming what is missing, for a refusal a human can act on. */
+export function describeNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? 'a connection to an MCP server'
+        : `a ${need.connection} connection`;
+}
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export function unmetNeeds(needs, providers) {
+    const held = new Set(providers
+        .map((p) => String(p ?? '').split('—')[0].trim().toLowerCase())
+        .filter(Boolean));
+    return needs.filter((n) => !held.has(n.connection.toLowerCase()));
+}
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export function unmetNeedsMessage(unmet) {
+    const list = unmet.map(describeNeed).join(', ');
+    return (`Cannot start this task: no live grant for ${list}. ` +
+        'Ask the connection owner to issue one for this agent, then re-assign the task.');
+}

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * One outcome vocabulary, one ctx shape, one transition signature.
  * Every state — parked or thinking — re-enters with exactly one Outcome.
  */
+import type { AgentNeed } from './tools/needs.js';
 export interface AgreementRef {
     agreementId: string;
     parties?: {
@@ -202,7 +203,7 @@ export interface Ctx {
      * Recent wake timestamps (epoch ms) for this lane (claude-sdk cognition
      * only). Backstop circuit breaker: if a lane wakes faster than any real
      * traffic could drive it, the brain skips the LLM instead of burning the
-     * fleet key on a wake storm.
+     * key on a wake storm.
      */
     recentDeliveries?: number[];
 }
@@ -327,11 +328,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;
@@ -471,10 +484,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;
 } | {
@@ -534,6 +554,13 @@ export interface DefineAgentInput {
     initial: string;
     states: Record<string, State>;
     tools?: unknown[];
+    /**
+     * Access this agent cannot work without. Declaring a need PRODUCES the tools
+     * for it — do not also hand-list them — and makes work that arrives without
+     * the grant fail at task start with the missing thing named, instead of
+     * part-way through a real hire.
+     */
+    needs?: AgentNeed[];
     services?: ServicesConfig;
     operatorKey?: string;
     taskTools?: 'all' | 'none' | string[];
@@ -557,6 +584,8 @@ export interface AgentConfig {
     systemPrompt?: string;
     specialization?: string;
     tools: unknown[];
+    /** Normalized declared needs — see DefineAgentInput.needs. */
+    needs?: AgentNeed[];
     model: string;
     workflow: Workflow;
     services?: ServicesConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.11.0",
+  "version": "0.12.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.0",
+    "@ziggs-ai/api-client": "0.11.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",