@ziggs-ai/agent-sdk 0.10.8 → 0.11.1

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

@@ -1,6 +1,6 @@
 import { isBroadcastTarget, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
-// ZIG-1111: the link-summary rule lives in AgreementClient, at the point the
+// the link-summary rule lives in AgreementClient, at the point the
 // document is parsed. Every verb here inherits it through the client instead of
 // each one restating `engagementKind === 'link' ? linkSummary(a) : a` — which is
 // how counter, fulfill and subcontract came to return the raw document.
@@ -12,12 +12,12 @@ function normalizeState(state) {
         return 'failed';
     return state;
 }
-// ZIG-793: the `plan` tool-schema is underspecified (`plan: {type:'object'}`,
+// the `plan` tool-schema is underspecified (`plan: {type:'object'}`,
 // `planReviewTiming: 'string'`), so the LLM emits steps missing stepId/order and an
 // out-of-enum planReviewTiming, which the backend DTO rejects. Normalize in-place
 // before the write.
 //
-// ZIG-1095: task-spawn is the only op left that carries a plan. Propose, counter
+// task-spawn is the only op left that carries a plan. Propose, counter
 // and subcontract used to run this too — and their plans were then dropped on the
 // floor, since no agreement route has ever accepted one.
 // Returns the clamped review timing rather than only writing it back, so the
@@ -46,7 +46,7 @@ function normalizePlanInPlace(payload) {
         : 'with_proposal';
 }
 export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, writeKeys = null, 
-/** ZIG-1120 #8 — prefer the cached session snapshot over a fresh HTTP read. */
+/** #8 — prefer the cached session snapshot over a fresh HTTP read. */
 cachedAgreements) {
     if (!payload?.operation)
         return null;
@@ -63,7 +63,7 @@ cachedAgreements) {
                 return null;
             return agreementService.respond(payload.agreementId, payload.action);
         case 'agreement-claim': {
-            // ZIG-1021: the one claim verb — quest, standing offer, or link invite.
+            // the one claim verb — quest, standing offer, or link invite.
             if (!payload.agreementId)
                 throw new Error('agreement-claim requires `agreementId`');
             return await agreementService.claim(payload.agreementId);
@@ -101,11 +101,11 @@ cachedAgreements) {
                 return null;
             let spawnAgreementId = payload.agreementId;
             const ags = await agreementsInChat(services, chatId, cachedAgreements);
-            // b2 (ZIG-832): if the assignee is not a party on the cited agreement,
+            // b2: if the assignee is not a party on the cited agreement,
             // redirect the spawn to the ACTIVE sub-agreement (same root) where the
             // assignee IS the provider — the orchestrator often cites the top-level
             // hire, which the backend rejects with "assignee not a party".
-            // ZIG-858: also redirect when the cited agreement is no longer active —
+            // also redirect when the cited agreement is no longer active —
             // a count-bound sub fulfills after its quota (default 1), and the LLM
             // keeps citing that now-terminal sub for the next spawn even when a
             // fresh active sub for the same executor exists.
@@ -120,14 +120,14 @@ cachedAgreements) {
                         spawnAgreementId = sub.agreementId;
                 }
             }
-            // Safety guard (ZIG-832, B): a spawn against an agreement that is not active,
+            // Safety guard: a spawn against an agreement that is not active,
             // or whose assignee is not a party on it, hard-400s at the backend AND makes
             // the worker invent a "connection needed" message. That happens when the
             // orchestrator spawns before its sub-agreement is subcontracted/approved.
             // Skip GRACEFULLY instead — the sub-agreement's activation event will wake
             // the orchestrator to spawn correctly on a later turn, no 400, no cascade.
             const target = ags.find((a) => a.agreementId === spawnAgreementId);
-            // ZIG-858: a TERMINAL target is not the same as a not-yet-active one — no
+            // a TERMINAL target is not the same as a not-yet-active one — no
             // activation event will ever arrive, so the "wait for a later turn" skip
             // below would stall the run. Tell the caller the actionable next step:
             // subcontract a fresh sub for this executor, then spawn under it.
@@ -176,7 +176,7 @@ cachedAgreements) {
             });
         }
         case 'task-update': {
-            // ZIG-1057: `state` only — legacy `status` alias removed. Fleet prompts
+            // `state` only — legacy `status` alias removed. Fleet prompts
             // must emit state (coffee / fruit / ledger / agent-definer).
             const terminalRaw = typeof payload.state === 'string' && payload.state ? payload.state : '';
             if (!payload.taskId || !terminalRaw)
@@ -193,7 +193,7 @@ cachedAgreements) {
                 throw new Error('task-update-plan-step requires `stepId`');
             if (!payload.status)
                 throw new Error('task-update-plan-step requires `status`');
-            // ZIG-793: a plan-step tick is cosmetic progress. Worker subtasks usually
+            // a plan-step tick is cosmetic progress. Worker subtasks usually
             // have NO plan (only the orchestrator's job task does), and the LLM may tick
             // a stepId that isn't in the plan — the backend 400s on both. That must never
             // hard-fail the tool → fail the task → wake-loop. Make it best-effort.
@@ -213,7 +213,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     if (!payload.proposedTo)
         throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To create a task under an existing agreement, use `task_create` instead.');
     const isBroadcast = isBroadcastTarget(payload.proposedTo);
-    // ZIG-1022: a link proposal is an agreement with engagementKind 'link' —
+    // a link proposal is an agreement with engagementKind 'link' —
     // no chat, no money; the target owner approves. Folds the old request_link.
     if (payload.engagementKind === 'link') {
         if (isBroadcast) {
@@ -225,7 +225,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         throw new Error('agreement-propose requires `providerId` — name who does the work: your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient).');
     }
     if (isBroadcast && payload.providerId) {
-        // ZIG-1022: providerId = self on a broadcast publishes a STANDING OFFER
+        // providerId = self on a broadcast publishes a STANDING OFFER
         // (seller side open to any claimer). Any other providerId stays an error.
         if (actingAgentId && payload.providerId === actingAgentId) {
             const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
@@ -256,7 +256,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     });
     return services.agreementService.propose({ ...fields, chatId, idempotencyKey });
 }
-// ── ZIG-832: deterministic sub-agreement resolution ─────────────────────────
+// ── deterministic sub-agreement resolution ─────────────────────────
 // The orchestrator delegates one task per worker, but the LLM inconsistently
 // (a) re-subcontracts the same worker (duplicate sub-agreements) and (b)
 // task_spawns a worker under the TOP-LEVEL hire — where the worker is not a
@@ -267,7 +267,7 @@ const TERMINAL_STATUS = new Set(['fulfilled', 'cancelled', 'refunded', 'rejected
 async function agreementsInChat(services, chatId, cachedAgreements) {
     if (!chatId)
         return [];
-    // ZIG-1120 #8 — createZiggsEffectHandler already cached the session snapshot;
+    // #8 — createZiggsEffectHandler already cached the session snapshot;
     // prefer that over another GET /context/snapshot just for the agreements array.
     // Empty array is a real answer ("none in this chat") — do not re-fetch.
     if (cachedAgreements !== undefined) {
@@ -297,14 +297,14 @@ function agActive(a) {
 // Spawnable = actually ACTIVE. A freshly-subcontracted sub is `draft` until its
 // counterparty auto-approves; spawning under a draft (or citing an agreement the
 // assignee isn't a party on) 400s and cascades into a bogus worker "connection
-// needed" message. We treat only 'active' as spawnable (ZIG-832).
+// needed" message. We treat only 'active' as spawnable.
 function agIsActiveStatus(a) {
     return String(a.status ?? '') === 'active';
 }
 async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null, cachedAgreements) {
     if (!payload.description || !payload.executorId)
         return null;
-    // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
+    // b1: idempotent subcontract — if a non-terminal sub-agreement for
     // this executor already exists under the same parent, reuse it instead of
     // creating a duplicate (which bloats the chain and blocks the fulfill cascade).
     if (chatId) {
@@ -316,7 +316,7 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
     }
     const priced = applyFleetPricingForProtocol('agreement-subcontract', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;
-    // ZIG-832: a subcontract must carry a working close condition, or it hangs
+    // a subcontract must carry a working close condition, or it hangs
     // 'active' forever — and because the backend only auto-fulfills a parent hire
     // once every child sub-agreement is terminal (the fulfill cascade), one
     // never-closing child leaves the whole engagement open. Deciding lifecycle is
@@ -328,7 +328,7 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
     // sub — which then cascades the parent closed. A genuinely durable subcontract
     // still opts out by setting maxExecutions>1 or a time-bound expiresAt.
     const f = fields;
-    // ZIG-858: repair incomplete terms instead of clobbering them. The model
+    // repair incomplete terms instead of clobbering them. The model
     // often emits a real quota or deadline but gets the envelope wrong — a
     // numeric-string maxExecutions, or a quota/deadline with the lifecycle field
     // missing or mismatched. The old check treated all of those as "no close

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

@@ -2,7 +2,7 @@ import { defineTool } from '../../../tools/defineTool.js';
 import { requireProtocolOperation } from '../../../tasks/protocolRegistry.js';
 import { dispatchProtocolOp } from './protocolRunner.js';
 import { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, } from '@ziggs-ai/api-client';
-/** ZIG-957 — keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
+/** keep these enums in lockstep with MCP ziggs_agreement_* / ziggs_task_create. */
 const LIFECYCLE_ENUM = ['open', 'time-bound', 'count-bound'];
 const PLAN_REVIEW_TIMING_ENUM = ['with_proposal', 'before_execution'];
 const lifecycleParam = {
@@ -17,7 +17,7 @@ const planReviewTimingParam = {
 };
 /**
  * The handler for a protocol verb, looked up by tool name in the registry
- * (ZIG-1110). Keying off the tool name rather than restating the operation is
+ *. Keying off the tool name rather than restating the operation is
  * what makes half-registration impossible: a verb missing from
  * PROTOCOL_TOOL_TO_OPERATION throws here, while this module loads, instead of
  * dispatching correctly and then being unrecognised as protocol at every
@@ -43,13 +43,13 @@ 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', 'link'], description: "Contract type. Defaults to service. 'link' proposes a bilateral trust link (no work, no money)." }, 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). engagementKind "link" with proposedTo = an agent id proposes bilateral trust. 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 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 taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
-    // ZIG-957: same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
+    // same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
     state: { type: 'string', required: true, enum: ['completed', 'failed', 'cancelled'] },
     // Same object contract as MCP ({ summary, status, links, … }).
     result: {

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

@@ -1,7 +1,7 @@
 import { ARTIFACT_CAPABILITIES, recordArtifactCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-899 / ZIG-956 — deliberate artifact recording, defined once in
-// api-client's shared capability layer (including the ZIG-560 result-slot
+// deliberate artifact recording, defined once in
+// api-client's shared capability layer (including the result-slot
 // teaching, worded per surface task grammar).
 export const recordArtifactTool = toolFromCapability(recordArtifactCapability);
 export const ARTIFACT_TOOLS = toolsFromCapabilities(ARTIFACT_CAPABILITIES);

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

@@ -1,7 +1,7 @@
 import { CHAT_CAPABILITIES, openConversationCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-900 / ZIG-956 — chat_open only (chat listing stays a
-// context-rail read, ZIG-626 rule); defined once in api-client's shared
+// chat_open only (chat listing stays a
+// context-rail read, rule); defined once in api-client's shared
 // capability layer.
 export const openConversationTool = toolFromCapability(openConversationCapability);
 export const CHAT_TOOLS = toolsFromCapabilities(CHAT_CAPABILITIES);

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

@@ -1,9 +1,9 @@
 import { connectionProxyCapability, requestConnectionCapability, ConnectionsClient, } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
 import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
-// ZIG-956 — connection_proxy / connection_request are shared capability
+// connection_proxy / connection_request are shared capability
 // definitions (api-client). connection_list_grants stays SDK-only: the MCP
-// surface folds connection listing into ziggs_connection_list (ZIG-893
+// surface folds connection listing into ziggs_connection_list (
 // allowance in the parity table).
 export const connectionProxyTool = toolFromCapability(connectionProxyCapability);
 export const requestConnectionTool = toolFromCapability(requestConnectionCapability);
@@ -35,7 +35,7 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', {
         throw wrapped;
     }
 }, {
-    // ZIG-1128: this shipped with no description at all — the model was handed a
+    // this shipped with no description at all — the model was handed a
     // name and a parameter and left to guess what the tool was for. Found by the
     // new SDK tool-text guard.
     description: "List the grants issued to this agent on one stored connection. Returns the grantId that connection_proxy needs. Use it when you have a connectionId but not the grantId — grant_list (scopeKind=connection) is the wider read across every connection.",

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

@@ -1,6 +1,6 @@
 import { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-869 / ZIG-775 / ZIG-956 — context grant tools ride the same api-client
+// context grant tools ride the same api-client
 // clients as ziggs-mcp; the whole definition (schema + handler) is now shared
 // via the capability layer, so the two surfaces cannot fork.
 export const contextReadTool = toolFromCapability(contextReadCapability);

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

@@ -1,7 +1,7 @@
 import { agentSearchCapability, agentGetCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
-// ZIG-956 — agent discovery is a shared capability definition (api-client),
-// so search shaping (ZIG-664 zero-hit hint, reachability rows) is identical
+// agent discovery is a shared capability definition (api-client),
+// so search shaping (zero-hit hint, reachability rows) is identical
 // on both surfaces.
 export const agentSearchTool = toolFromCapability(agentSearchCapability);
 export const agentGetTool = toolFromCapability(agentGetCapability);

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

@@ -1,6 +1,6 @@
 import { GRANTS_CAPABILITIES, listGrantsCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-893 / ZIG-956 — the single "what authority do I hold?" tool, defined
+// the single "what authority do I hold?" tool, defined
 // once in api-client's shared capability layer.
 export const listGrantsTool = toolFromCapability(listGrantsCapability);
 export const GRANTS_TOOLS = toolsFromCapabilities(GRANTS_CAPABILITIES);

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

@@ -1,11 +1,11 @@
 import { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-898 / ZIG-956 — links are agreements with engagementKind 'link':
+// links are agreements with engagementKind 'link':
 // bilateral agent-to-agent trust that gives any unpublished agent cross-org
 // reach. Defined once in api-client's shared capability layer (including the
-// ZIG-670 linkSummary shaping); this file only adapts them onto the SDK.
+// linkSummary shaping); this file only adapts them onto the SDK.
 //
-// ZIG-1021/1022 shrank the rail to two tools. The agreement verbs carry the
+///1022 shrank the rail to two tools. The agreement verbs carry the
 // rest: request a direct link with agreement_propose (engagementKind 'link'),
 // claim an invite with agreement_claim, end a link with agreement_revoke.
 export const linkCreateInviteTool = toolFromCapability(createLinkInviteCapability);

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

@@ -1,6 +1,6 @@
 import { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-1023 / ZIG-956 — the marketplace read (quests AND standing offers),
+// the marketplace read (quests 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);

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

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const mcpToolsListTool: ToolDefinition;
+export declare const mcpToolCallTool: ToolDefinition;
+export declare const MCP_CONNECTION_TOOLS: ToolDefinition[];

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

@@ -0,0 +1,136 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
+import { defineTool } from '../../../tools/defineTool.js';
+import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
+/**
+ * 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
+ * remote MCP server is stored with `provider: 'mcp'`, which no connector matches,
+ * so every attempt came back "Unknown provider: mcp". A hosted agent therefore had
+ * no way to use an MCP connection at all — found when a Linear grant was issued to
+ * `shipped-digest` and its task still failed after two proxy attempts.
+ *
+ * The gateway (`POST /connections/:id/mcp`) has always been the right door and is
+ * already in production; what was missing was a tool that walks through it. The
+ * transport, headers and MCP handshake are the same ones `McpAdapter`'s `ziggs`
+ * transport uses — reused rather than re-derived, so a change to the gateway
+ * contract lands in one place.
+ *
+ * Discovery is deliberate: with no `connectionId`/`grantId` the tool asks
+ * `GET /grants` for the agent's own live connection grants. One connection means
+ * no argument to guess; several means the caller must name one, because picking
+ * for them is how an agent reads the wrong workspace and reports it as fact.
+ */
+async function resolveTarget(ctx, connectionId, grantId) {
+    if (connectionId && grantId)
+        return { connectionId, grantId };
+    const operatorKey = ctx['operatorKey'];
+    const agentId = ctx['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    // No explicit baseUrl: ConnectionsClient already resolves it the way the fleet
+    // configures it (HTTP_URL). Passing BACKEND_URL here was the same mistake as in
+    // the transport — undefined in deployment.
+    const groups = await new ConnectionsClient(operatorKey, agentId).listForHolder();
+    const live = groups.filter((g) => (g.grants ?? []).length > 0);
+    if (live.length === 0) {
+        throw new Error('No live connection grant. Ask the connection owner to issue one for this agent, then retry.');
+    }
+    const chosen = connectionId
+        ? live.find((g) => g.connectionId === connectionId)
+        : live.length === 1
+            ? live[0]
+            : undefined;
+    if (!chosen) {
+        throw new Error(`Name the connection to use — grants exist on ${live
+            .map((g) => g.connectionId)
+            .join(', ')}`);
+    }
+    const grant = grantId
+        ? (chosen.grants ?? []).find((g) => g.grantId === grantId)
+        : (chosen.grants ?? [])[0];
+    if (!grant) {
+        throw new Error(`No live grant on ${chosen.connectionId} for this agent`);
+    }
+    return { connectionId: chosen.connectionId, grantId: grant.grantId };
+}
+async function withClient(ctx, connectionId, grantId, run) {
+    const target = resolveZiggsGatewayTarget({
+        type: 'ziggs',
+        connectionId,
+        grantId,
+        operatorKey: ctx['operatorKey'],
+        agentId: ctx['agentId'],
+    }, { agentId: ctx['agentId'] });
+    const transport = new StreamableHTTPClientTransport(target.url, {
+        requestInit: { headers: target.headers },
+    });
+    const client = new Client({ name: 'ziggs-agent-sdk', version: '1.0.0' });
+    try {
+        await client.connect(transport);
+        return await run(client);
+    }
+    finally {
+        // A leaked session holds an upstream connection open on the gateway.
+        await client.close().catch(() => { });
+    }
+}
+export const mcpToolsListTool = defineTool('mcp_tools_list', {
+    connectionId: {
+        type: 'string',
+        description: 'Connection to inspect. Omit when you hold a grant on exactly one — it is then resolved for you.',
+    },
+    grantId: {
+        type: 'string',
+        description: 'Grant to use. Omit to use the live grant found on that connection.',
+    },
+}, async (args, ctx) => {
+    const t = await resolveTarget(ctx, args['connectionId'], args['grantId']);
+    const tools = await withClient(ctx, t.connectionId, t.grantId, async (c) => {
+        const res = await c.listTools();
+        return (res.tools ?? []).map((tool) => ({
+            name: tool.name,
+            description: tool.description ?? null,
+        }));
+    });
+    return { connectionId: t.connectionId, grantId: t.grantId, tools };
+}, {
+    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.",
+});
+export const mcpToolCallTool = defineTool('mcp_tool_call', {
+    tool: {
+        type: 'string',
+        required: true,
+        description: 'Tool name on the connected MCP server, e.g. list_issues.',
+    },
+    args: {
+        type: 'object',
+        description: "Arguments for that tool, as the server's schema defines them.",
+    },
+    connectionId: {
+        type: 'string',
+        description: 'Connection to call through. Omit when you hold a grant on exactly one.',
+    },
+    grantId: {
+        type: 'string',
+        description: 'Grant to use. Omit to use the live grant found on that connection.',
+    },
+}, async (args, ctx) => {
+    const name = args['tool'];
+    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({
+        name,
+        arguments: args['args'] ?? {},
+    }));
+    return { connectionId: t.connectionId, tool: name, result };
+}, {
+    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.",
+});
+export const MCP_CONNECTION_TOOLS = [mcpToolsListTool, mcpToolCallTool];

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

@@ -1,6 +1,6 @@
 import { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// ZIG-956 — the wallet toolset is defined once in api-client's shared
+// 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.

package/dist/shared/operatorKeyClaims.d.ts

@@ -1,7 +1,7 @@
 /**
  * Client-side peek at an operator key's JWT payload (signature NOT verified —
  * identity hint only, the backend remains the authority). Used by the fleet
- * launcher to warn when the key is agent-bound (ZIG-911): a bound key
+ * launcher to warn when the key is agent-bound: a bound key
  * collapses the operator multiplex to its one agent and 403s every other
  * per-agent loop, so a large fleet quietly watches a single agent.
  */
@@ -14,7 +14,7 @@ export interface OperatorKeyClaims {
 }
 export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
 /**
- * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * The startup check: warn (never refuse — a one-agent launcher on a
  * bound key is legitimate) when the fleet's control key is bound to a single
  * agent while more than one agent is registered. Returns the warning line, or
  * null when the setup is coherent.

package/dist/shared/operatorKeyClaims.js

@@ -18,7 +18,7 @@ export function decodeOperatorKeyClaims(token) {
     }
 }
 /**
- * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * The startup check: warn (never refuse — a one-agent launcher on a
  * bound key is legitimate) when the fleet's control key is bound to a single
  * agent while more than one agent is registered. Returns the warning line, or
  * null when the setup is coherent.

package/dist/tasks/protocolRegistry.d.ts

@@ -1,7 +1,7 @@
 /**
  * The protocol verbs and the state operation each one performs.
  *
- * This is the single place the set is written down (ZIG-1110). It used to be
+ * This is the single place the set is written down. It used to be
  * restated: the tool definitions passed their operation string to `handlerFor`
  * by hand, and this table listed them again. `agreement_fulfill` was in the
  * first list and not the second, so it dispatched fine but

package/dist/tasks/protocolRegistry.js

@@ -1,7 +1,7 @@
 /**
  * The protocol verbs and the state operation each one performs.
  *
- * This is the single place the set is written down (ZIG-1110). It used to be
+ * This is the single place the set is written down. It used to be
  * restated: the tool definitions passed their operation string to `handlerFor`
  * by hand, and this table listed them again. `agreement_fulfill` was in the
  * first list and not the second, so it dispatched fine but

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) {
@@ -10,7 +11,7 @@ function makeError(message, type, extra) {
     return err;
 }
 /**
- * ZIG-1215 — Ajv's own wording for a rejected unknown param is "must NOT have
+ * Ajv's own wording for a rejected unknown param is "must NOT have
  * additional properties", which names neither the offending key nor the ones
  * that would have worked. An agent reading that has nothing to correct against,
  * so the typo is named alongside the menu it should have come from.
@@ -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/capabilityAdapter.d.ts

@@ -1,7 +1,7 @@
 import { type ToolDefinition } from './defineTool.js';
 import type { CapabilityDefinition } from '@ziggs-ai/api-client';
 /**
- * ZIG-956 — the SDK surface adapter for shared capability definitions
+ * the SDK surface adapter for shared capability definitions
  * (api-client `capabilities/`). One capability (schema + handler + guidance)
  * becomes a defineTool ToolDefinition: the neutral param DSL feeds defineTool's
  * JSON-schema converter unchanged, and the handler runs with creds pulled from

package/dist/tools/capabilityAdapter.js

@@ -1,6 +1,6 @@
 import { defineTool } from './defineTool.js';
 /**
- * ZIG-956 — the SDK surface adapter for shared capability definitions
+ * the SDK surface adapter for shared capability definitions
  * (api-client `capabilities/`). One capability (schema + handler + guidance)
  * becomes a defineTool ToolDefinition: the neutral param DSL feeds defineTool's
  * JSON-schema converter unchanged, and the handler runs with creds pulled from
@@ -10,8 +10,8 @@ export function toolFromCapability(cap) {
     return defineTool(cap.names.sdk, cap.params, async (args, ctx) => {
         const operatorKey = ctx?.['operatorKey'];
         const agentId = ctx?.['agentId'];
-        // ZIG-1092 — the lane was already threaded to this exact point by
-        // ZIG-775's shared executor (`chatId: effect.sessionId` in
+        // the lane was already threaded to this exact point by
+        //'s shared executor (`chatId: effect.sessionId` in
         // executeToolWithSideEffects); it just was not used to narrow anything.
         // Reading it here makes the fence brain-agnostic by construction: the
         // Claude brain and the FSM brain both arrive through this adapter.

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,12 +43,24 @@ 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');
     if (!handler || typeof handler !== 'function')
         throw new Error('defineTool: handler function is required');
-    // ZIG-1215 — the top level is closed so a misspelled param is rejected by
+    // the top level is closed so a misspelled param is rejected by
     // ToolManager's Ajv pass instead of being dropped on the floor. JSON Schema
     // allows unknown keys by default, so without this the validation ran and
     // passed while the handler quietly ignored what the model asked for.