@ziggs-ai/api-client 0.34.1 → 0.35.0

package/dist/capabilities/agreementVerbs.js

@@ -165,7 +165,7 @@ export const agreementBuyCapability = {
         sdk: 'Ask a named counterparty to do work your side pays for. They provide, you pay. For work you would do for them instead, use agreement_bid; to reach whoever is available rather than someone named, use agreement_request.',
         mcp: 'Ask a named counterparty to do work your side pays for: they provide, you pay. Prefer claiming their listing first if they have one (ziggs_marketplace_view then ziggs_agreement_claim) — listings are take-it-or-leave-it and most published agents refuse direct proposals. Use this for bespoke terms, renegotiation, or a counterparty with no listing. For work you would do for them, use ziggs_agreement_bid; to reach whoever is available, use ziggs_agreement_request.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
@@ -197,7 +197,7 @@ export const agreementBidCapability = {
         sdk: 'Offer to do work for a named counterparty, who pays. You provide. To publish the same offer to whoever wants it rather than one named party, use agreement_offer.',
         mcp: 'Offer to do work for a named counterparty, who pays: you provide. This is the direct form of a listing — to publish the same offer to whoever wants it, use ziggs_agreement_offer instead. To ask someone else to do work you pay for, use ziggs_agreement_buy.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
@@ -229,7 +229,7 @@ export const agreementBrokerCapability = {
         sdk: 'Introduce a provider to a customer: the provider does the work, the counterparty pays, and neither side is you. The provider must already have a matching active offer.',
         mcp: 'Introduce a provider to a customer: the named provider does the work, the counterparty pays, and you are neither. The provider needs a matching active offer for this to stand. This is the one verb where naming a provider is the point — every other agreement verb infers it from the direction of work.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: {
             ...COUNTERPARTY_PARAM,
@@ -268,7 +268,7 @@ export const agreementRequestCapability = {
         sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. To offer work you would do instead, use agreement_offer.',
         mcp: 'Post work you want done and will pay for: whoever claims it does the work. Use this when nothing already listed fits, rather than proposing to named counterparties one at a time. To offer work you would do, use ziggs_agreement_offer. Claimable via ziggs_agreement_claim; visible in ziggs_marketplace_view.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         audience: AUDIENCE_PARAM,
         ...TERMS_PARAMS,
@@ -323,7 +323,7 @@ export const agreementOfferCapability = {
         sdk: 'Publish work you will do, for whoever claims it and pays. You provide. This is your listing: it stands until revoked or exhausted. To offer one named counterparty instead, use agreement_bid.',
         mcp: 'Publish work you will do, for whoever claims it and pays: you provide. This is your listing — it stands until revoked or exhausted, and claimers take it as posted rather than countering it. To offer one named counterparty instead, use ziggs_agreement_bid. To ask for work rather than supply it, use ziggs_agreement_request.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS, maxClaims: MAX_CLAIMS_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -366,7 +366,7 @@ export const listingPauseCapability = {
         sdk: 'Stop taking new customers on a listing you publish, without deleting it. New claims on it are refused until you resume it with listing_resume. Same listing, same id; hires already sold keep running. To end a listing for good, use agreement_revoke.',
         mcp: 'Stop taking new customers on a listing you publish, without deleting it. New claims on it are refused until you resume it with ziggs_listing_resume. Same listing, same id; hires already sold keep running. Use it when the person you act for asks you to stop taking work for now. To end a listing for good, use ziggs_agreement_revoke. Only the publisher of a listing can pause it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -382,7 +382,7 @@ export const listingResumeCapability = {
         sdk: 'Reopen a listing you paused with listing_pause: same listing, same id, taking new customers again. A listing closed because every seat is taken, or because its agent stopped answering, reopens on its own and needs no resume.',
         mcp: 'Reopen a listing you paused with ziggs_listing_pause: same listing, same id, taking new customers again. A listing closed because every seat is taken, or because its agent stopped answering, reopens on its own and needs no resume. Only the publisher of a listing can resume it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -399,7 +399,7 @@ export const agreementHandoffCapability = {
         sdk: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves becomes the customer the work is done for. Omit `to` to make it claimable by anyone. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed.',
         mcp: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves is the CUSTOMER the work is done for, never the worker. Omit `to` to publish it claimable; name `to` and that party approves directly. On a priced hand-off the claimer is also the payer; omit price (or 0) and nobody is billed for their tasks. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed. The provider is read from the parent hire, so you do not pass it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         parentAgreementId: {
             type: 'string',
@@ -475,7 +475,7 @@ export const agreementSubcontractCapability = {
         sdk: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room.',
         mcp: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room. Spawn tasks for the worker under the sub-agreement once it is active.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         parentAgreementId: {
             type: 'string',

package/dist/capabilities/agreements.js

@@ -86,7 +86,7 @@ export const agreementClaimCapability = {
         sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are 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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. 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. To hire an agent into a room, claim its listing with that room\'s chatId.',
         mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are 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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast. To hire an agent into a room, claim its listing with that room\'s chatId.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         agreementId: {
             type: 'string',
@@ -107,12 +107,30 @@ export const agreementClaimCapability = {
             type: 'string',
             description: 'The room this hire is for — only when claiming an agent\'s listing. When the hire activates the agent joins that exact room, with no invitation and no second approval; if it waits for a yes, the room shows it as a proposal. You must be in the room. The answer\'s room.status says where it stands.',
         },
+        connections: {
+            type: 'object',
+            description: 'Only when the listing\'s requiredConnections name a kind (e.g. ledger, customer): one of YOUR connections for each, as { "<kind>": "<connectionId>" }. The hire is granted exactly that connection and the grant ends with it. Leave it out when claiming inside a job (mandateAgreementId) — the job\'s choice is used.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}) });
+        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}), ...(claimConnections(args['connections']) ?? {}) });
         return presentClaimResult(agreement, kind, env, room);
     },
 };
+/** `{ connections }` when the caller named any, as strings; anything else is refused here. */
+function claimConnections(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('connections must be an object of { <kind>: <connectionId> }');
+    const connections = {};
+    for (const [kind, id] of Object.entries(raw)) {
+        if (typeof id !== 'string' || !id.trim())
+            throw new Error(`connections.${kind} must be one of your connection ids`);
+        connections[kind] = id.trim();
+    }
+    return Object.keys(connections).length ? { connections } : undefined;
+}
 export const AGREEMENT_CAPABILITIES = [agreementClaimCapability];

package/dist/capabilities/artifacts.js

@@ -479,7 +479,7 @@ export const shareArtifactCapability = {
             'in the chat you are working in. The receiver then reads it with ziggs_context_read ' +
             'via=artifact:<id>.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: {
             type: 'string',
@@ -555,7 +555,7 @@ export const attachArtifactCapability = {
             'to the container. To hand it to ONE specific agent without opening a chat, use ' +
             'ziggs_artifact_share instead.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: { type: 'string', required: true, description: 'Artifact to attach' },
         chatId: { type: 'string', description: 'Chat to attach it to' },
@@ -797,7 +797,7 @@ export const reextractArtifactCapability = {
         mcp: 'Re-queue extract for a file you authored (extractionStatus ok or failed only). ' +
             'Creates a new derived text artifact and supersedes the old one — no in-place mutate.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: { type: 'string', required: true, description: 'File artifact id' },
     },

package/dist/capabilities/connections.js

@@ -25,7 +25,7 @@ export const connectionProxyCapability = {
             'Not for remote MCP servers (provider "mcp") — those use ziggs_mcp_tool_call / ziggs_mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Call ziggs_connection_list first.",
     },
-    annotation: "write",
+    annotation: "destructive",
     params: {
         connectionId: {
             type: "string",
@@ -83,7 +83,7 @@ export const requestConnectionCapability = {
             "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it (there is no MCP tool to approve it). " +
             "On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.",
     },
-    annotation: "write",
+    annotation: "destructive",
     params: {
         chatId: {
             type: "string",

package/dist/capabilities/context.js

@@ -375,7 +375,7 @@ export const contextRequestCapability = {
         sdk: 'Ask a human owner for temporary read-only access to one artifact you were given a reference for. Use your existing chat with that owner. Creates an approval agreement; gives no access until the owner approves. You are the only recipient. After approval, open the original artifact. Never use a generic service agreement as a substitute for this access request.',
         mcp: 'Request access to a restricted artifact directly from its human owner. Pass the artifact id you were given, your conversation with the owner, and in ownerId who to ask (a pick the server cannot use here is refused with the list). This creates a pending approval agreement, NOT a grant. No prior grant is needed. The human approves at the agreement link. After approval, ziggs_open the original artifact. Scope is read-only, one artifact, for 1–168 hours (default 24); no other artifacts or chats. Include the intended summary recipient in reason. Keep polling for the decision when asked to wait. A request does not confirm that the artifact exists or belongs to the named owner; ownership is checked at approval.',
     },
-    annotation: 'write', needsAgentId: true,
+    annotation: 'destructive', needsAgentId: true,
     params: {
         artifactId: { type: 'string', required: true },
         chatId: { type: 'string', required: true },
@@ -411,7 +411,7 @@ export const accessRequestCapability = {
     key: 'access_request',
     names: { sdk: 'access_request', mcp: 'ziggs_access_request' },
     title: 'Request access for yourself',
-    annotation: 'write', needsAgentId: true,
+    annotation: 'destructive', needsAgentId: true,
     descriptions: {
         sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
         mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Name who to ask in recipientId; a pick the server cannot use here is refused, and the refusal lists who you can ask. Artifact requests also require chatId. permission=work on an agreement asks to create work under it; send it when a refusal says you can read but not work on it. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',

package/dist/capabilities/everyday.d.ts

@@ -7,15 +7,12 @@
  * the inbox, and the SDK has no context-grant revoke.
  *
  * Everything else stays callable. It is named by the catalog and reached
- * through the read or write dispatcher, not mounted as its own schema.
+ * through the read or write dispatcher, not mounted as its own schema. A
+ * tool's destructive hint never decides this list: the write dispatcher is
+ * itself marked destructive, so a host can warn before any dispatched write,
+ * and nothing has to be native just to carry the hint.
  */
 export declare const EVERYDAY_MCP_TOOLS: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_open", "ziggs_context_read", "ziggs_chat_open", "ziggs_chat_send", "ziggs_task_set_result", "ziggs_agreement_revoke", "ziggs_context_revoke_grant"];
-/**
- * Irreversible tools stay natively listed, and the write dispatcher refuses
- * them. A host reads `destructiveHint` off the tool it is asked to run; a
- * dispatcher would present the warning as an ordinary write.
- */
-export declare const EVERYDAY_DESTRUCTIVE_MCP: readonly ["ziggs_agreement_revoke", "ziggs_context_revoke_grant"];
 /** Everyday MCP tools the hosted brain does not register. */
 export declare const EVERYDAY_NO_SDK_TWIN: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_context_revoke_grant"];
 /** SDK names of the everyday set. Same order as the MCP list, twins only. */

package/dist/capabilities/everyday.js

@@ -7,7 +7,10 @@
  * the inbox, and the SDK has no context-grant revoke.
  *
  * Everything else stays callable. It is named by the catalog and reached
- * through the read or write dispatcher, not mounted as its own schema.
+ * through the read or write dispatcher, not mounted as its own schema. A
+ * tool's destructive hint never decides this list: the write dispatcher is
+ * itself marked destructive, so a host can warn before any dispatched write,
+ * and nothing has to be native just to carry the hint.
  */
 export const EVERYDAY_MCP_TOOLS = [
     'ziggs_inbox',
@@ -23,16 +26,8 @@ export const EVERYDAY_MCP_TOOLS = [
     'ziggs_chat_open',
     'ziggs_chat_send',
     'ziggs_task_set_result',
-    // And every irreversible tool — see EVERYDAY_DESTRUCTIVE_MCP below.
-    'ziggs_agreement_revoke',
-    'ziggs_context_revoke_grant',
-];
-/**
- * Irreversible tools stay natively listed, and the write dispatcher refuses
- * them. A host reads `destructiveHint` off the tool it is asked to run; a
- * dispatcher would present the warning as an ordinary write.
- */
-export const EVERYDAY_DESTRUCTIVE_MCP = [
+    // The two ways out, everyday because taking access back must never need a
+    // lookup first (Ido, 2026-09-16).
     'ziggs_agreement_revoke',
     'ziggs_context_revoke_grant',
 ];

package/dist/capabilities/index.d.ts

@@ -16,6 +16,6 @@ export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCa
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, type SendPresentation, } from './chat.js';
-export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
+export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/index.js

@@ -16,6 +16,6 @@ export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCa
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';
-export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
+export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/introductions.js

@@ -63,7 +63,7 @@ export const redeemIntroductionCapability = {
         sdk: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} If they are a stranger, this stages a link proposal from them to you which both humans must approve. After approval, reach their agent with chat_open using the returned counterparty.agentId. If you already share an org or a link, it says so instead of proposing another. One use — a second redeem is refused.`,
         mcp: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} If they are a stranger, this stages a link proposal from them to you which both humans must approve. After approval, open a room with ziggs_chat_open using the returned counterparty.agentId. If you already share an org or a link, it says so instead of proposing another. One use — a second redeem is refused. A self-chosen display name is not verified identity.`,
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         token: {
             type: 'string',
@@ -142,7 +142,7 @@ export const revokeIntroductionCapability = {
     // A write, not a destructive act: nobody holds anything from an unredeemed
     // hello, so taking one back removes no access and loses no data. The
     // destructive annotation is reserved for the two tools that end live access.
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         token: {
             type: 'string',

package/dist/capabilities/links.js

@@ -140,7 +140,7 @@ export const proposeLinkCapability = {
         sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organisation is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
         mcp: "Connect with a person (NOT a third-party service connection — see ziggs_connection_list for that): pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent answering to an organisation is refused, because a link connects two people. Leave `to` out and you get shareUrl: one public page that is the whole invite, which you hand to your human to paste wherever they like. Someone with no Ziggs account signs up from that page and accepts in the same step, and their assistant handed the same URL reads the connect instructions off it. A link is reach and nothing else: no chat, no money, no work. The answer is identical every time, so it never reveals whether an address has an account. Approve links proposed to you with ziggs_agreement_respond; end one with ziggs_agreement_revoke.",
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         to: {
             type: 'string',

package/dist/capabilities/payments.js

@@ -40,8 +40,8 @@ export const paymentBalanceCapability = {
     names: { sdk: 'payment_balance', mcp: 'ziggs_payment_balance' },
     title: 'Check your points',
     descriptions: {
-        sdk: "Check the caller's points balance and available balance (total minus points held against active agreements). Points move as a consequence of an agreement settling.",
-        mcp: "Check the caller's points balance and available balance (total minus points held against active agreements). Points move as a consequence of an agreement settling — there is no tool to move them on their own, so earning and spending both happen when an agreement settles.",
+        sdk: "Check the caller's points balance and available balance (total minus points held against active agreements). Points settle through work. They cannot be cashed out or resold; point purchases are only available in the Ziggs app.",
+        mcp: "Check the caller's points balance and available balance (total minus points held against active agreements). Points settle through work. They cannot be cashed out or resold, and cannot be transferred on their own. Point purchases are only available in the Ziggs app; this connector has no purchase or checkout tool.",
     },
     annotation: 'read-only',
     params: {},

package/dist/capabilities/tasks.js

@@ -76,7 +76,7 @@ export const cancelTaskCapability = {
         sdk: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
         mcp: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         taskId: {
             type: 'string',

package/dist/http/AgreementClient.d.ts

@@ -325,6 +325,12 @@ export interface ClaimOptions {
      * agent joins that room; the claimer must take part in it.
      */
     chatId?: string;
+    /**
+     * Your connection for each kind of access the listing asks for,
+     * `{ <kind>: <connectionId> }`. The hire is granted exactly that connection. A claim made inside a job (mandateAgreementId)
+     * takes the job's and names none.
+     */
+    connections?: Record<string, string>;
 }
 /**
  * Where a hire made in a room stands on getting its agent in.

package/dist/http/AgreementClient.js

@@ -554,7 +554,7 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.chatId ? { chatId: opts.chatId } : {}) }),
+        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.chatId ? { chatId: opts.chatId } : {}), ...(opts.connections && Object.keys(opts.connections).length ? { connections: opts.connections } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

package/dist/http/AssistantConnectionClient.d.ts

@@ -15,13 +15,13 @@ export declare class AssistantConnectionClient {
     private readonly baseUrl;
     constructor(creds: Creds, baseUrl?: string);
     request<T>(path: string, body?: unknown): Promise<T>;
-    /** Live: a workspace joined since connecting shows up here with its assistant. */
+    /** Read existing enabled assistant hires. Provisioning is an explicit sync action. */
     workspaces(): Promise<AssistantWorkspace[]>;
     /** Which of the connection's assistants is on an existing thing. */
     resolve(kind: string, id: string): Promise<{
         workspace: AssistantWorkspace | null;
         choices: AssistantWorkspace[];
     }>;
-    inbox(waitSeconds?: number): Promise<Record<string, unknown>>;
+    inbox(waitSeconds?: number, snapshot?: boolean): Promise<Record<string, unknown>>;
     ack(upTo: string, handledResourceIds?: string[]): Promise<unknown>;
 }

package/dist/http/AssistantConnectionClient.js

@@ -31,7 +31,7 @@ export class AssistantConnectionClient {
         }
         return JSON.parse(text);
     }
-    /** Live: a workspace joined since connecting shows up here with its assistant. */
+    /** Read existing enabled assistant hires. Provisioning is an explicit sync action. */
     async workspaces() {
         return (await this.request('workspaces'))
             .workspaces;
@@ -40,8 +40,8 @@ export class AssistantConnectionClient {
     resolve(kind, id) {
         return this.request(`resolve?${new URLSearchParams({ kind, id })}`);
     }
-    inbox(waitSeconds = 0) {
-        return this.request(`inbox?wait=${waitSeconds}`);
+    inbox(waitSeconds = 0, snapshot = false) {
+        return this.request(`inbox${snapshot ? "/snapshot" : ""}?wait=${waitSeconds}`);
     }
     ack(upTo, handledResourceIds = []) {
         return this.request('inbox/ack', { upTo, handledResourceIds });

package/dist/http/InboxClient.d.ts

@@ -20,6 +20,10 @@ export declare class InboxClient {
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, instanceId?: string);
     private headers;
     private inboxUrl;
+    /** Read without acquiring worker ownership or recording receipts. */
+    getSnapshot(opts?: InboxReadOptions & {
+        signal?: AbortSignal;
+    }): Promise<InboxEnvelope>;
     getInbox(opts?: InboxReadOptions & {
         signal?: AbortSignal;
     }): Promise<InboxEnvelope>;

package/dist/http/InboxClient.js

@@ -47,6 +47,16 @@ export class InboxClient {
         }
         return url.toString();
     }
+    /** Read without acquiring worker ownership or recording receipts. */
+    async getSnapshot(opts = {}) {
+        const res = await fetch(this.inboxUrl('/inbox/snapshot', opts), {
+            method: 'GET', headers: this.headers(), signal: opts.signal,
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok)
+            throw pollSurfaceError('InboxClient.getSnapshot', res, body);
+        return JSON.parse(body);
+    }
     async getInbox(opts = {}) {
         const res = await fetch(this.inboxUrl('/inbox', opts), {
             headers: this.headers(),

package/dist/http/PaymentsClient.d.ts

@@ -10,10 +10,6 @@ export interface WalletBalance {
     balance: number;
     availableBalance: number;
 }
-export interface PaymentTransactionView {
-    transactionId?: string;
-    [key: string]: unknown;
-}
 /**
  * A resolved wallet reference (GET /payments/wallets/resolve).
  *
@@ -24,27 +20,6 @@ export interface PaymentTransactionView {
  */
 import type { WalletRef } from '@ziggs-ai/contracts';
 export type { WalletRef };
-export type TransferResult = {
-    status: 'approval_required';
-    approvalId: string | null;
-    expiresAt: string | null;
-    reason: string | null;
-    toWalletId: string;
-    amount: number;
-} | {
-    status: 'transferred';
-    transactionId: string | null;
-    toWalletId: string;
-    amount: number;
-};
-export interface HoldResult {
-    transaction?: PaymentTransactionView;
-    [key: string]: unknown;
-}
-export interface ReleaseResult {
-    transaction?: PaymentTransactionView;
-    [key: string]: unknown;
-}
 /**
  * A payment grant as this rail answers it.
  *
@@ -69,40 +44,14 @@ export interface RevokeGrantResult {
     revoked?: unknown;
     [key: string]: unknown;
 }
-export interface PaymentApproval {
-    approvalId?: string;
-    status?: string;
-    executedTransactionId?: string | null;
-    [key: string]: unknown;
-}
-export type WaitForApprovalResult = {
-    status: 'gone';
-} | {
-    status: 'executed';
-    approval: PaymentApproval;
-    transactionId: string | null;
-} | {
-    status: 'rejected' | 'expired' | 'timeout';
-    approval: PaymentApproval;
-};
-/**
- * Who to pay on a transfer. Kind is declared by the caller — never inferred
- * from id shape. A bare string is only a wallet id (`wal_…`).
- */
-export type TransferPayee = string | {
-    walletId: string;
-} | {
-    agentId: string;
-} | {
-    userId: string;
-};
 /**
  * the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
  * ops ride the operator key; agent-impersonated calls send X-Agent-Id and are
- * policy-gated server-side (transfers above threshold return
- * `approval_required`). Wallet-rail grant mutations (issue / attenuate /
- * revoke) live here; grant *listing* is the unified GET /grants.
+ * policy-gated server-side. Points move only when an agreement or a task
+ * settles, and the server does that; there is no standalone movement verb on
+ * this client. Wallet-rail grant mutations (issue / attenuate / revoke) live
+ * here; grant *listing* is the unified GET /grants.
  */
 export declare class PaymentsClient {
     private readonly operatorKey;
@@ -128,60 +77,6 @@ export declare class PaymentsClient {
         userId?: string;
         agentId?: string;
     }): Promise<WalletRef | null>;
-    /**
-     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
-     * user payees must name their kind.
-     */
-    private resolvePayeeWalletId;
-    transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
-        to: TransferPayee;
-        amount: number;
-        idempotencyKey?: string;
-        description?: string;
-        paymentGrantId?: string;
-        /**
-         * The hire this spend belongs to. Used for attribution, and to prefer that
-         * hire's own grant over a standing one — a preference about which budget is
-         * billed, never about which grants may be spent. That answer is the
-         * server's, and it turns on who gave the grant.
-         */
-        agreementId?: string;
-    }): Promise<TransferResult>;
-    hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
-        amount: number;
-        idempotencyKey?: string;
-        description?: string;
-        paymentGrantId?: string;
-        /**
-         * The hire this spend belongs to. Used for attribution, and to prefer that
-         * hire's own grant over a standing one — a preference about which budget is
-         * billed, never about which grants may be spent. That answer is the
-         * server's, and it turns on who gave the grant.
-         */
-        agreementId?: string;
-    }): Promise<HoldResult>;
-    /**
-     * Choose the grant that actually covers this spend.
-     *
-     * This used to be `grants[0]` — the first active grant, matched against
-     * nothing. An agent holding both its standing grant and an
-     * agreement-conferred one presented whichever came back first, the backend
-     * correctly refused it against wallet or amount, and the agent was refused a
-     * spend it was genuinely authorized to make.
-     *
-     * The source wallet is read rather than assumed: a grant on some other
-     * wallet cannot authorize money leaving this one, and the agent may hold
-     * grants on a counterparty's wallet from an engagement. A failure to read it
-     * is not fatal — selection then skips the wallet test and the server still
-     * validates, which is the same position we were in before.
-     */
-    private selectPaymentGrant;
-    release({ holdId, action, toWalletId, idempotencyKey, }: {
-        holdId: string;
-        action?: string;
-        toWalletId?: string;
-        idempotencyKey?: string;
-    }): Promise<ReleaseResult>;
     history(params?: {
         limit?: number;
         offset?: number;
@@ -213,16 +108,6 @@ export declare class PaymentsClient {
         description?: string;
         idempotencyKey?: string;
     }): Promise<unknown>;
-    approvals({ status }?: {
-        status?: string;
-    }): Promise<PaymentApproval[]>;
-    getApproval(approvalId: string): Promise<PaymentApproval | null>;
-    decide(approvalId: string, decision: string, note?: string): Promise<unknown>;
-    waitForApproval(approvalId: string, opts?: {
-        pollMs?: number;
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<WaitForApprovalResult>;
     private _request;
     private _get;
     private _post;

package/dist/http/PaymentsClient.js

@@ -1,7 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
-import { describeNoGrant, selectPaymentGrant, } from './paymentGrantSelection.js';
 import { throwApiError } from '../shared/apiError.js';
 function randomIdempotencyKey(prefix = 'op') {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
@@ -10,9 +9,10 @@ function randomIdempotencyKey(prefix = 'op') {
  * the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
  * ops ride the operator key; agent-impersonated calls send X-Agent-Id and are
- * policy-gated server-side (transfers above threshold return
- * `approval_required`). Wallet-rail grant mutations (issue / attenuate /
- * revoke) live here; grant *listing* is the unified GET /grants.
+ * policy-gated server-side. Points move only when an agreement or a task
+ * settles, and the server does that; there is no standalone movement verb on
+ * this client. Wallet-rail grant mutations (issue / attenuate / revoke) live
+ * here; grant *listing* is the unified GET /grants.
  */
 export class PaymentsClient {
     operatorKey;
@@ -61,139 +61,6 @@ export class PaymentsClient {
         const res = (await this._get(`/payments/wallets/resolve?${params}`));
         return res['wallet'] || null;
     }
-    /**
-     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
-     * user payees must name their kind.
-     */
-    async resolvePayeeWalletId(to) {
-        if (typeof to === 'string') {
-            const id = to.trim();
-            if (!id)
-                throw new Error('transfer: `to` is required');
-            if (id.startsWith('wal_'))
-                return id;
-            throw new Error('transfer: string `to` must be a wallet id (wal_…); pass { agentId } or { userId } for a principal');
-        }
-        if ('walletId' in to && typeof to.walletId === 'string' && to.walletId.trim()) {
-            return to.walletId.trim();
-        }
-        if ('agentId' in to && typeof to.agentId === 'string' && to.agentId.trim()) {
-            const w = await this.resolve({ agentId: to.agentId.trim() });
-            if (!w?.walletId) {
-                throw new Error(`transfer: could not resolve wallet for agent "${to.agentId}"`);
-            }
-            return w.walletId;
-        }
-        if ('userId' in to && typeof to.userId === 'string' && to.userId.trim()) {
-            const w = await this.resolve({ userId: to.userId.trim() });
-            if (!w?.walletId) {
-                throw new Error(`transfer: could not resolve wallet for user "${to.userId}"`);
-            }
-            return w.walletId;
-        }
-        throw new Error('transfer: `to` must be a wallet id (wal_…) or { walletId | agentId | userId }');
-    }
-    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
-        if (to == null || to === '')
-            throw new Error('transfer: `to` is required');
-        if (!(Number.isInteger(amount) && amount > 0))
-            throw new Error('transfer: `amount` must be a positive integer (cents)');
-        // The recipient is resolved BEFORE choosing a grant: an `allowed_recipients`
-        // caveat cannot be checked against a name the client has not resolved yet.
-        const toWalletId = await this.resolvePayeeWalletId(to);
-        // Choose the grant that covers this spend when the caller omitted one.
-        // An explicit id still wins — a caller who names a grant means it.
-        if (this.agentId && !paymentGrantId) {
-            const picked = await this.selectPaymentGrant({ amount, toWalletId, agreementId });
-            if (!picked.grant) {
-                throw new Error(describeNoGrant('transfer', { amount, toWalletId, agreementId }, picked.rejected));
-            }
-            paymentGrantId = picked.grant.grantId;
-        }
-        const result = (await this._post('/payments/transfer', {
-            toWalletId,
-            amount,
-            idempotencyKey: idempotencyKey || randomIdempotencyKey('xfer'),
-            description,
-            paymentGrantId,
-        }));
-        if (result?.['status'] === 'approval_required') {
-            const approval = result['approval'] || {};
-            return {
-                status: 'approval_required',
-                approvalId: approval['approvalId'] || null,
-                expiresAt: approval['expiresAt'] || null,
-                reason: approval['reason'] || 'Amount exceeds auto-approve threshold',
-                toWalletId,
-                amount,
-            };
-        }
-        const tx = result?.['transaction'];
-        return {
-            status: 'transferred',
-            transactionId: tx?.['transactionId'] || null,
-            toWalletId,
-            amount,
-        };
-    }
-    async hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
-        if (!(Number.isInteger(amount) && amount > 0))
-            throw new Error('hold: `amount` must be a positive integer (cents)');
-        // A hold reserves the owner's money, so it needs a grant like a transfer.
-        // It has no counterparty, so no recipient is offered to the caveats.
-        if (this.agentId && !paymentGrantId) {
-            const picked = await this.selectPaymentGrant({ amount, agreementId });
-            if (!picked.grant) {
-                throw new Error(describeNoGrant('hold', { amount, agreementId }, picked.rejected));
-            }
-            paymentGrantId = picked.grant.grantId;
-        }
-        return (await this._post('/payments/hold', {
-            amount,
-            idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'),
-            description,
-            paymentGrantId,
-        }));
-    }
-    /**
-     * Choose the grant that actually covers this spend.
-     *
-     * This used to be `grants[0]` — the first active grant, matched against
-     * nothing. An agent holding both its standing grant and an
-     * agreement-conferred one presented whichever came back first, the backend
-     * correctly refused it against wallet or amount, and the agent was refused a
-     * spend it was genuinely authorized to make.
-     *
-     * The source wallet is read rather than assumed: a grant on some other
-     * wallet cannot authorize money leaving this one, and the agent may hold
-     * grants on a counterparty's wallet from an engagement. A failure to read it
-     * is not fatal — selection then skips the wallet test and the server still
-     * validates, which is the same position we were in before.
-     */
-    async selectPaymentGrant(spend) {
-        let grants = [];
-        try {
-            grants = await this.listGrants();
-        }
-        catch {
-            return { grant: null, rejected: [] };
-        }
-        let fromWalletId = null;
-        try {
-            fromWalletId = (await this.balance()).walletId;
-        }
-        catch {
-            fromWalletId = null;
-        }
-        return selectPaymentGrant(grants, { ...spend, fromWalletId });
-    }
-    async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
-        return (await this._post(`/payments/release/${holdId}`, {
-            idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'),
-            action,
-            toWalletId,
-        }));
-    }
     async history(params = {}) {
         const q = new URLSearchParams();
         if (params.limit != null)
@@ -237,68 +104,6 @@ export class PaymentsClient {
             description,
         });
     }
-    async approvals({ status = 'pending' } = {}) {
-        const res = (await this._get(`/payments/approvals?status=${encodeURIComponent(status)}`));
-        return res['approvals'] || [];
-    }
-    async getApproval(approvalId) {
-        if (!approvalId)
-            throw new Error('getApproval: approvalId is required');
-        try {
-            const res = (await this._get(`/payments/approvals/${approvalId}`));
-            return res?.['approval'] || null;
-        }
-        catch (err) {
-            if (err.status === 404)
-                return null;
-            throw err;
-        }
-    }
-    async decide(approvalId, decision, note = '') {
-        return this._post(`/payments/approvals/${approvalId}/decide`, { decision, note });
-    }
-    async waitForApproval(approvalId, opts = {}) {
-        const pollMs = Math.max(500, opts.pollMs ?? 3_000);
-        const timeoutMs = Math.max(pollMs, opts.timeoutMs ?? 120_000);
-        const signal = opts.signal;
-        const deadline = Date.now() + timeoutMs;
-        const sleep = (ms) => new Promise((resolve, reject) => {
-            const timer = setTimeout(resolve, ms);
-            if (signal) {
-                if (signal.aborted) {
-                    clearTimeout(timer);
-                    reject(new Error('aborted'));
-                    return;
-                }
-                signal.addEventListener('abort', () => {
-                    clearTimeout(timer);
-                    reject(new Error('aborted'));
-                }, { once: true });
-            }
-        });
-        while (true) {
-            if (signal?.aborted)
-                throw new Error('aborted');
-            const approval = await this.getApproval(approvalId);
-            if (!approval)
-                return { status: 'gone' };
-            const s = approval.status;
-            if (s === 'executed')
-                return {
-                    status: 'executed',
-                    approval,
-                    transactionId: approval.executedTransactionId || null,
-                };
-            if (s === 'rejected')
-                return { status: 'rejected', approval };
-            if (s === 'expired')
-                return { status: 'expired', approval };
-            const remaining = deadline - Date.now();
-            if (remaining <= 0)
-                return { status: 'timeout', approval };
-            await sleep(Math.min(pollMs, remaining));
-        }
-    }
     async _request(method, path, body) {
         const init = {
             method,

package/dist/http/index.d.ts

@@ -22,7 +22,7 @@ export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, Cont
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, GrantHolderKind, GrantAccessKind, GrantBasisKind, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
-export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferPayee, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
+export type { PaymentsError, WalletBalance, WalletRef, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
 export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, } from './OrgsClient.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",

package/dist/http/paymentGrantSelection.d.ts

@@ -1,58 +0,0 @@
-import { type GrantView } from './grants.js';
-/**
- * Which grant to present for a spend, and — when none fits — why each candidate
- * did not.
- *
- * The client used to take `grants[0]` from the active list. It matched nothing
- * else: not the source wallet, not the amount, not the agreement the spend
- * belongs to. An agent holding both its standing grant and an agreement-conferred
- * one presented whichever came back first, the backend correctly refused it
- * against wallet or amount, and the agent was refused a spend it was genuinely
- * authorized to make.
- *
- * Selection is a pure function of the grants and the spend so it can be tested
- * without a server, and so the refusal can name what it considered.
- */
-export interface SpendShape {
-    /** The wallet the money leaves. A grant on another wallet cannot authorize it. */
-    fromWalletId?: string | null;
-    /** Cents. Checked against `max_amount`. */
-    amount: number;
-    /** The wallet receiving it, when known. Checked against `allowed_recipients`. */
-    toWalletId?: string | null;
-    /** The engagement this spend belongs to, when the caller names one. */
-    agreementId?: string | null;
-}
-export interface RejectedGrant {
-    grantId: string;
-    reason: string;
-}
-export interface GrantSelection {
-    grant: GrantView | null;
-    /** Every grant that was looked at and did not fit, with the reason. */
-    rejected: RejectedGrant[];
-}
-/**
- * Pick the grant to present, preferring the one that belongs to the engagement.
- *
- * Order among grants that all fit: the agreement's own grant first when the
- * spend names one, then the standing grant. A standing grant is the buyer
- * bootstrap and the right default; reaching for it while an agreement grant
- * covers the same spend would bill the wrong budget.
- *
- * This is a preference, never a fence. Every grant here is already one the
- * server said this wake may spend, so picking a different one cannot reach
- * another party's authority — it would only bill the wrong budget of the same
- * party. That is why the mismatch is no longer a rejection above.
- */
-export declare function selectPaymentGrant(grants: readonly GrantView[], spend: SpendShape): GrantSelection;
-/**
- * The sentence an agent gets when nothing fits.
- *
- * It names every grant considered and why each was not it, because "no payment
- * grant" is a condition and an agent cannot act on a condition — it retries,
- * and every retry is a full model call. Which ceiling was in the way is the
- * thing that tells the agent whether to ask for a bigger grant, name the
- * agreement, or stop.
- */
-export declare function describeNoGrant(verb: string, spend: SpendShape, rejected: readonly RejectedGrant[]): string;

package/dist/http/paymentGrantSelection.js

@@ -1,121 +0,0 @@
-import { grantCaveat } from './grants.js';
-/**
- * A caveat off a grant that may not carry the array at all.
- *
- * `grantCaveat` assumes `caveats` is populated, which the unified list read
- * does. A caller handing us a partial view should get "no such caveat", not a
- * crash — this runs on the spend path, where throwing would turn a missing
- * field into a refused payment.
- */
-function caveatValue(grant, type) {
-    const caveats = grant.caveats;
-    if (!Array.isArray(caveats))
-        return undefined;
-    return grantCaveat(grant, type);
-}
-function numericCaveat(grant, type) {
-    const raw = caveatValue(grant, type);
-    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
-}
-function recipientCaveat(grant) {
-    const raw = caveatValue(grant, 'allowed_recipients');
-    if (!Array.isArray(raw))
-        return null;
-    const ids = raw.filter((r) => typeof r === 'string');
-    return ids.length ? ids : null;
-}
-/**
- * Why this grant cannot authorize this spend, or null if it can.
- *
- * `daily_budget` is deliberately not checked. It is a ceiling on spend already
- * made, which only the server can see — guessing here would refuse a grant that
- * would have worked. The server validates it inside the same transaction as the
- * ledger write, which is the only place the answer is not already stale.
- */
-function whyNot(grant, spend) {
-    // A stated kind that is not `wallet` is disqualifying. An ABSENT one is not:
-    // `listGrants` asks the server for `scopeKind: 'wallet'`, so the rail has
-    // already answered, and treating a field the response did not populate as a
-    // wrong answer would refuse every grant. Same reading as an unread source
-    // wallet below — absence means unknown, never no.
-    if (grant.scope?.kind && grant.scope.kind !== 'wallet') {
-        return `is a ${grant.scope.kind} grant, not a wallet grant`;
-    }
-    if (spend.fromWalletId && grant.scope?.id && grant.scope.id !== spend.fromWalletId) {
-        return `is on wallet ${grant.scope.id}, and this spend leaves ${spend.fromWalletId}`;
-    }
-    const maxAmount = numericCaveat(grant, 'max_amount');
-    if (maxAmount !== null && spend.amount > maxAmount) {
-        return `caps a single spend at ${maxAmount}, and this one is ${spend.amount}`;
-    }
-    const allowed = recipientCaveat(grant);
-    if (allowed && spend.toWalletId && !allowed.includes(spend.toWalletId)) {
-        return `may only pay ${allowed.join(', ')}, and this one pays ${spend.toWalletId}`;
-    }
-    // A grant's agreement is NOT checked here, deliberately.
-    //
-    // It used to be refused when it did not match the spend's agreement, which
-    // made a customer's own grant unusable inside their second hire of the same
-    // agent, and made a standing grant unusable on any spend that named a deal.
-    // Whether a grant may be spent at all is the server's answer, and it turns on
-    // who GAVE the grant against who the agent is acting for — not on which of
-    // that party's deals is running. A list the server answered for this wake
-    // holds only grants it may spend, so there is nothing left to refuse here.
-    //
-    // The agreement still decides the ORDER below, which is a budget preference
-    // rather than a question of authority.
-    return null;
-}
-/**
- * Pick the grant to present, preferring the one that belongs to the engagement.
- *
- * Order among grants that all fit: the agreement's own grant first when the
- * spend names one, then the standing grant. A standing grant is the buyer
- * bootstrap and the right default; reaching for it while an agreement grant
- * covers the same spend would bill the wrong budget.
- *
- * This is a preference, never a fence. Every grant here is already one the
- * server said this wake may spend, so picking a different one cannot reach
- * another party's authority — it would only bill the wrong budget of the same
- * party. That is why the mismatch is no longer a rejection above.
- */
-export function selectPaymentGrant(grants, spend) {
-    const rejected = [];
-    const fitting = [];
-    for (const grant of grants) {
-        const reason = whyNot(grant, spend);
-        if (reason)
-            rejected.push({ grantId: grant.grantId, reason });
-        else
-            fitting.push(grant);
-    }
-    if (fitting.length === 0)
-        return { grant: null, rejected };
-    // Explicit both ways, because the deal is no longer a fence: until it was
-    // removed, a deal-bound grant simply never reached this list on a spend that
-    // named nothing, so "prefer the standing grant" happened by accident of the
-    // rejection. Now it has to be said.
-    const standing = fitting.find((g) => !g.agreementId);
-    const preferred = spend.agreementId
-        ? (fitting.find((g) => g.agreementId === spend.agreementId) ?? standing)
-        : standing;
-    return { grant: preferred ?? fitting[0], rejected };
-}
-/**
- * The sentence an agent gets when nothing fits.
- *
- * It names every grant considered and why each was not it, because "no payment
- * grant" is a condition and an agent cannot act on a condition — it retries,
- * and every retry is a full model call. Which ceiling was in the way is the
- * thing that tells the agent whether to ask for a bigger grant, name the
- * agreement, or stop.
- */
-export function describeNoGrant(verb, spend, rejected) {
-    if (rejected.length === 0) {
-        return (`${verb}: you hold no active payment grant, so this spend cannot be ` +
-            `authorized. The wallet owner issues one; nothing you can do from here.`);
-    }
-    const lines = rejected.map((r) => `  - ${r.grantId} ${r.reason}`).join('\n');
-    return (`${verb}: none of your ${rejected.length} active payment grant(s) covers ` +
-        `this spend of ${spend.amount}.\n${lines}`);
-}