@ziggs-ai/api-client 0.14.3 → 0.15.1

package/dist/capabilities/agreementVerbs.js

@@ -122,10 +122,27 @@ const COUNTERPARTY_PARAM = {
     required: true,
     description: 'Agent or user id of the counterparty.',
 };
+/**
+ * Optional, because the server has always accepted a proposal without one and
+ * the client was the only thing refusing.
+ *
+ * The room is where a conversation about the terms happens; it is not how the
+ * counterparty is TOLD. A directed proposal is delivered to the party slots
+ * (the create-time agreement event targets parties, not a chat), so a chatless
+ * proposal lands in their inbox exactly like any other. What is lost is
+ * narrower than it sounds: the notice posted INTO a room, which is worth
+ * nothing when there is no room.
+ *
+ * Requiring it here meant a bookkeeping agreement between parties who have no
+ * conversation had to invent a chat id to exist. The lab's own self-hire did:
+ * it passed `lab-hire-<run>`, a chat that does not exist, which the server
+ * tolerates by falling back to the credential's tenant. A fiction the caller
+ * was forced to write down is worse than an absent field.
+ */
 const CHAT_PARAM = {
     type: 'string',
-    required: true,
-    description: 'The room this is proposed in — the counterparty reads it there.',
+    required: false,
+    description: 'The room this is proposed in, when there is one — the counterparty can read and discuss the terms there. Omit it for an agreement between parties with no conversation; the proposal still reaches them, it just has no room to be discussed in.',
 };
 /** Marketplace follow-up: a published listing is claimed, never countered. */
 function publishedNext(env) {

package/dist/capabilities/agreements.js

@@ -25,7 +25,7 @@ export function presentClaimResult(agreement, kind, env) {
     }
     if (agreement?.status !== 'active') {
         const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
-        const approveUrl = `${webAppOrigin(env)}/app/work/agreements/${agreement.agreementId}`;
+        const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
         const remedy = held?.heldReason === 'contact-basis'
             ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
             : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';

package/dist/capabilities/connections.d.ts

@@ -1,4 +1,4 @@
-import { type CapabilityDefinition } from './types.js';
+import { type CapabilityDefinition } from "./types.js";
 export declare const connectionProxyCapability: CapabilityDefinition;
 export declare const requestConnectionCapability: CapabilityDefinition;
 export declare const CONNECTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/connections.js

@@ -1,115 +1,138 @@
-import { ConnectionsClient } from '../http/ConnectionsClient.js';
-import { rethrowWithContext, } from './types.js';
+import { ConnectionsClient } from "../http/ConnectionsClient.js";
+import { rethrowWithContext, } from "./types.js";
 function client(env) {
-    const { operatorKey, agentId } = env.creds;
+    // laneId, not just the key and the agent. The lane is which engagement this
+    // wake is in, and the broker needs it to tell one hirer's grant from
+    // another's: an agent that serves several hirers is the holder of every grant
+    // it has been given, so the holder check alone cannot separate them. Every
+    // other Creds-based client already carries it.
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    return new ConnectionsClient(operatorKey, agentId, env.baseUrl);
+        throw new Error("operatorKey missing from tool context");
+    return new ConnectionsClient(operatorKey, agentId, env.baseUrl, laneId);
 }
 export const connectionProxyCapability = {
-    key: 'connection_proxy',
-    names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
-    title: 'Use a stored connection',
+    key: "connection_proxy",
+    names: { sdk: "connection_proxy", mcp: "ziggs_connection_proxy" },
+    title: "Use a stored connection",
     descriptions: {
         sdk: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira) without ever seeing the credential. " +
-            'Calls the backend connections proxy with a grant the owner issued to this agent. ' +
+            "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use mcp_tool_call / mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Use grant_list (scopeKind=connection) or connection_list_grants first.",
         mcp: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list) without ever seeing the credential. " +
-            'Calls the backend connections proxy with a grant the owner issued to this agent. ' +
+            "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             '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: "write",
     params: {
-        connectionId: { type: 'string', required: true, description: 'Connection to act on' },
+        connectionId: {
+            type: "string",
+            required: true,
+            description: "Connection to act on",
+        },
         grantId: {
-            type: 'string',
+            type: "string",
+            required: true,
+            description: "Grant the owner issued to this agent for the connection",
+        },
+        action: {
+            type: "string",
             required: true,
-            description: 'Grant the owner issued to this agent for the connection',
+            description: "Provider action, e.g. repo:read",
+        },
+        payload: {
+            type: "object",
+            description: "Action-specific arguments (provider-defined)",
         },
-        action: { type: 'string', required: true, description: 'Provider action, e.g. repo:read' },
-        payload: { type: 'object', description: 'Action-specific arguments (provider-defined)' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args['connectionId'])
-            throw new Error('connectionId is required');
-        if (!args['grantId'])
-            throw new Error('grantId is required');
-        if (!args['action'])
-            throw new Error('action is required');
+        if (!args["connectionId"])
+            throw new Error("connectionId is required");
+        if (!args["grantId"])
+            throw new Error("grantId is required");
+        if (!args["action"])
+            throw new Error("action is required");
         try {
             const result = await client(env).proxy({
-                connectionId: args['connectionId'],
-                grantId: args['grantId'],
-                action: args['action'],
-                payload: args['payload'],
+                connectionId: args["connectionId"],
+                grantId: args["grantId"],
+                action: args["action"],
+                payload: args["payload"],
             });
-            return { ok: true, action: args['action'], result };
+            return { ok: true, action: args["action"], result };
         }
         catch (e) {
-            rethrowWithContext(e, 'Connection proxy failed');
+            rethrowWithContext(e, "Connection proxy failed");
         }
     },
 };
 export const requestConnectionCapability = {
-    key: 'connection_request',
-    names: { sdk: 'connection_request', mcp: 'ziggs_connection_request' },
-    title: 'Ask your principal for a connection',
+    key: "connection_request",
+    names: { sdk: "connection_request", mcp: "ziggs_connection_request" },
+    title: "Ask your principal for a connection",
     descriptions: {
-        sdk: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
-            'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. ' +
-            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).',
-        mcp: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
-            'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
-            '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.',
+        sdk: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
+            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. " +
+            "On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).",
+        mcp: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
+            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). " +
+            "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: "write",
     params: {
         chatId: {
-            type: 'string',
+            type: "string",
+            required: true,
+            description: "The chat you are working in — the consent card is opened there",
+        },
+        serverUrl: {
+            type: "string",
             required: true,
-            description: 'The chat you are working in — the consent card is opened there',
+            description: "Remote MCP server URL (https)",
         },
-        serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
         tools: {
-            type: 'array',
-            items: { type: 'string' },
+            type: "array",
+            items: { type: "string" },
             required: true,
             description: "Tool names you want — become the grant's allowed_actions caveats",
         },
-        reason: { type: 'string', description: 'Plain-language reason shown to the human deciding' },
+        reason: {
+            type: "string",
+            description: "Plain-language reason shown to the human deciding",
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args['chatId'])
-            throw new Error('chatId is required');
-        if (!args['serverUrl'])
-            throw new Error('serverUrl is required');
-        const tools = args['tools'];
+        if (!args["chatId"])
+            throw new Error("chatId is required");
+        if (!args["serverUrl"])
+            throw new Error("serverUrl is required");
+        const tools = args["tools"];
         if (!Array.isArray(tools) || tools.length === 0) {
-            throw new Error('tools must be a non-empty array of tool names');
+            throw new Error("tools must be a non-empty array of tool names");
         }
         try {
             const result = await client(env).requestMcpConnection({
-                chatId: args['chatId'],
-                serverUrl: args['serverUrl'],
+                chatId: args["chatId"],
+                serverUrl: args["serverUrl"],
                 tools: tools,
-                reason: args['reason'],
+                reason: args["reason"],
             });
             return {
                 ok: true,
                 ...result,
-                note: env.surface === 'mcp'
-                    ? 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
-                        'Once approved, the connection + grant appear in ziggs_connection_list for ziggs_mcp_tools_list / ziggs_mcp_tool_call.'
-                    : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there. ' +
-                        'Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for mcp_tools_list / mcp_tool_call.',
+                note: env.surface === "mcp"
+                    ? "A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. " +
+                        "Once approved, the connection + grant appear in ziggs_connection_list for ziggs_mcp_tools_list / ziggs_mcp_tool_call."
+                    : "A connection-consent card is now in the chat awaiting your principal — they approve it right there. " +
+                        "Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for mcp_tools_list / mcp_tool_call.",
             };
         }
         catch (e) {
-            rethrowWithContext(e, 'Connection request failed');
+            rethrowWithContext(e, "Connection request failed");
         }
     },
 };

package/dist/capabilities/links.js

@@ -159,7 +159,7 @@ export const proposeLinkCapability = {
     handler: async (args, env) => {
         const to = args['to']?.trim();
         const maxClaims = args['maxClaims'];
-        const { shareUrl } = await createLink({
+        const { shareUrl, agreementId } = await createLink({
             ...(to ? { to } : {}),
             ...(args['message'] ? { description: args['message'] } : {}),
             ...(maxClaims == null || to ? {} : { maxClaims }),
@@ -168,9 +168,17 @@ export const proposeLinkCapability = {
         // back. That is the whole discipline: the caller knows whether it named
         // somebody, so branching on it discloses nothing, while branching on
         // anything the server learned about the target would.
+        //
+        // `agreementId` follows the same discipline: the route carries it for an
+        // agent id and an open invite and never for an email, so which of the two it
+        // is depends on what the caller passed and on nothing the server learned. It
+        // is what lets a caller reference the row and check on it; without it,
+        // several agents connecting in one run each minted a link toward the others
+        // in both directions, because none of them could ask.
         return {
             status: 'sent',
             shareUrl,
+            agreementId,
             message: to
                 ? `Invitation sent to ${to}. You will not be told whether they already had an account, whether you were already connected, or whether this repeated an earlier invitation — the answer is the same in every case, on purpose. It becomes a live connection when they accept. ${linkIsReachOnly(env)}`
                 : `Share link created, valid 7 days. Give your human shareUrl and nothing else: it is the whole invite. ${linkIsReachOnly(env)}`,

package/dist/http/AgreementClient.d.ts

@@ -34,7 +34,17 @@ export interface ProposeTerms {
 /** 1:1 proposal to a specific user or agent (`proposedTo` = their id). */
 export interface ProposeDirectInput extends ProposeTerms {
     proposedTo: string;
-    chatId: string;
+    /**
+     * The room the terms are discussed in, when there is one.
+     *
+     * Optional, matching the server, which has always accepted a proposal
+     * without one. Delivery does not depend on it: the create-time agreement
+     * event targets the party slots, so the counterparty is told either way; a
+     * room only gives them somewhere to talk about it. Required here was what
+     * forced a bookkeeping agreement between parties with no conversation to
+     * invent a chat id in order to exist.
+     */
+    chatId?: string;
 }
 /**
  * Open buyer-broadcast. `audience` selects who may see/claim it:
@@ -205,16 +215,29 @@ export interface CreateLinkBody {
     maxClaims?: number;
 }
 /**
- * The route's one answer, whatever was in `to`.
+ * The route's answer.
+ *
+ * `status` is constant — it went — and the two null-able fields are per-ARM,
+ * chosen by what the caller put in `to` and therefore known to it before the
+ * call. `shareUrl` is present exactly for an open invite.
+ *
+ * `agreementId` names the row for an agent id and for an open invite, and is
+ * null for an EMAIL. That split is what keeps the answer from becoming an
+ * existence oracle: the knock returns nothing for "no such person", "already
+ * linked", "already knocked" and "that is yourself" alike, so an id on some of
+ * those and not others would answer the one question the route refuses to
+ * answer. An agent id is different — the route resolves it through root
+ * authority and refuses a name that answers to nobody, so it already discloses
+ * that target's existence.
  *
- * Deliberately carries no agreement. Returning the row for an id target and a
- * bare "sent" for an address made one of the two an existence oracle over the
- * user table, so both say the same thing now: it went. `shareUrl` is null
- * exactly when `to` was named, which the caller already knows.
+ * Without it a caller could not reference what it had just created, check on it
+ * later, or tell a repeat from a first attempt.
  */
 export interface CreateLinkResult {
     ok: boolean;
     status: 'sent';
+    /** The link row, for a named agent id or an open invite. Null for an email. */
+    agreementId: string | null;
     shareUrl: string | null;
 }
 /**

package/dist/http/AgreementClient.js

@@ -444,9 +444,11 @@ export async function createLink(body, creds) {
         throw new Error('Invalid response: expected { ok, status: "sent", shareUrl } from POST /agreements/links');
     }
     const shareUrl = data['shareUrl'];
+    const agreementId = data['agreementId'];
     return {
         ok: data['ok'] === true,
         status: 'sent',
+        agreementId: typeof agreementId === 'string' ? agreementId : null,
         shareUrl: typeof shareUrl === 'string' ? shareUrl : null,
     };
 }

package/dist/http/ConnectionsClient.d.ts

@@ -1,4 +1,4 @@
-import type { GrantView } from './grants.js';
+import type { GrantView } from "./grants.js";
 export declare function assertNoLeakedConnectionSecret(serialized: string): void;
 /** Thrown by ConnectionsClient with the HTTP status and raw body attached. */
 export interface ConnectionsError extends Error {
@@ -56,19 +56,28 @@ export declare class ConnectionsClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    private readonly laneId?;
+    /**
+     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
+     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
+     *   an agent that serves several hirers holds all of their grants at once, so
+     *   without a lane one hirer's grant is indistinguishable from another's, and
+     *   a grant issued for one job can be spent inside a different one.
+     *   ArtifactsClient sends the same header for the same reason.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     /**
      * Present a ConnectionGrant to the broker and perform a provider action.
      * Returns the provider result — never the raw OAuth token. Requires an
      * impersonated agent (the grant holder).
      */
-    proxy({ connectionId, grantId, action, payload }: ConnectionProxyParams): Promise<unknown>;
+    proxy({ connectionId, grantId, action, payload, }: ConnectionProxyParams): Promise<unknown>;
     /**
      * List ConnectionGrants on a connection. When impersonating an agent the
      * server already scopes rows to that holder; the client-side filter is kept
      * as defense-in-depth (same behavior as the former ZiggsConnectClient).
      */
-    listGrants({ connectionId }: {
+    listGrants({ connectionId, }: {
         connectionId: string;
     }): Promise<ConnectionGrant[]>;
     /**

package/dist/http/ConnectionsClient.js

@@ -1,7 +1,7 @@
-import { getBackendUrl } from '../utils/urlUtils.js';
-import { throwApiError } from '../shared/apiError.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
-import { GrantsClient } from './GrantsClient.js';
+import { getBackendUrl } from "../utils/urlUtils.js";
+import { throwApiError } from "../shared/apiError.js";
+import { buildOperatorHeaders } from "./operatorHeaders.js";
+import { GrantsClient } from "./GrantsClient.js";
 // defense-in-depth mirror of the backend leak-guard
 // (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
 // vault token from the response; clients never see that token, so this layer
@@ -17,7 +17,7 @@ const LEAKED_SECRET_PATTERNS = [
 export function assertNoLeakedConnectionSecret(serialized) {
     for (const re of LEAKED_SECRET_PATTERNS) {
         if (re.test(serialized)) {
-            throw new Error('connection proxy response withheld: it appears to contain a credential (token-leak guard)');
+            throw new Error("connection proxy response withheld: it appears to contain a credential (token-leak guard)");
         }
     }
 }
@@ -34,29 +34,39 @@ export class ConnectionsClient {
     operatorKey;
     agentId;
     baseUrl;
-    constructor(operatorKey, agentId, baseUrl) {
+    laneId;
+    /**
+     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
+     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
+     *   an agent that serves several hirers holds all of their grants at once, so
+     *   without a lane one hirer's grant is indistinguishable from another's, and
+     *   a grant issued for one job can be spent inside a different one.
+     *   ArtifactsClient sends the same header for the same reason.
+     */
+    constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)
-            throw new Error('ConnectionsClient: operatorKey is required');
+            throw new Error("ConnectionsClient: operatorKey is required");
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     /**
      * Present a ConnectionGrant to the broker and perform a provider action.
      * Returns the provider result — never the raw OAuth token. Requires an
      * impersonated agent (the grant holder).
      */
-    async proxy({ connectionId, grantId, action, payload }) {
+    async proxy({ connectionId, grantId, action, payload, }) {
         if (!connectionId)
-            throw new Error('proxy: connectionId is required');
+            throw new Error("proxy: connectionId is required");
         if (!grantId)
-            throw new Error('proxy: grantId is required');
+            throw new Error("proxy: grantId is required");
         if (!action)
-            throw new Error('proxy: action is required');
+            throw new Error("proxy: action is required");
         if (!this.agentId) {
-            throw new Error('proxy: agentId is required — connection broker calls must impersonate the grant holder agent');
+            throw new Error("proxy: agentId is required — connection broker calls must impersonate the grant holder agent");
         }
-        const text = await this._requestRaw('POST', `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
+        const text = await this._requestRaw("POST", `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
         assertNoLeakedConnectionSecret(text);
         let parsed = text;
         try {
@@ -65,7 +75,7 @@ export class ConnectionsClient {
         catch {
             parsed = text;
         }
-        const result = parsed?.['result'];
+        const result = parsed?.["result"];
         return result ?? parsed;
     }
     /**
@@ -73,15 +83,15 @@ export class ConnectionsClient {
      * server already scopes rows to that holder; the client-side filter is kept
      * as defense-in-depth (same behavior as the former ZiggsConnectClient).
      */
-    async listGrants({ connectionId }) {
+    async listGrants({ connectionId, }) {
         if (!connectionId)
-            throw new Error('listGrants: connectionId is required');
+            throw new Error("listGrants: connectionId is required");
         if (!this.agentId) {
-            throw new Error('listGrants: agentId is required — grants are scoped to the impersonated agent');
+            throw new Error("listGrants: agentId is required — grants are scoped to the impersonated agent");
         }
-        const res = (await this._request('GET', `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
-        const grants = res['grants'] || [];
-        return grants.filter((g) => g['holderId'] === this.agentId);
+        const res = (await this._request("GET", `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
+        const grants = res["grants"] || [];
+        return grants.filter((g) => g["holderId"] === this.agentId);
     }
     /**
      * cross-connection discovery over the unified GET /grants:
@@ -94,15 +104,15 @@ export class ConnectionsClient {
         const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
         // All pages of the agent's live connection grants (not just the first page).
         const { items, unreadableRails } = await grantsClient.listAllGrantsWithRails({
-            scopeKind: 'connection',
-            health: 'active',
+            scopeKind: "connection",
+            health: "active",
         });
         // An unreadable rail is not an empty one. Returning [] here made
         // every caller say "no connection grant" when the truth was "this key may not
         // look" — the needs gate refused work the agent could do, and the MCP tool
         // told the owner to issue a grant that already existed. Throwing puts the
         // missing scope in the message, where the person who can fix it will read it.
-        const railBlocked = unreadableRails.find((r) => r.rail === 'connection');
+        const railBlocked = unreadableRails.find((r) => r.rail === "connection");
         if (railBlocked && items.length === 0) {
             throw new Error(`Cannot read this agent's connection grants: the operator key is missing the ` +
                 `"${railBlocked.requiredScope}" scope, so the grant list came back empty whether or not ` +
@@ -125,10 +135,10 @@ export class ConnectionsClient {
     /** Issue a connection grant to an agent holder (connection owner side). */
     async issueGrant({ connectionId, holderId, caveats, }) {
         if (!connectionId)
-            throw new Error('issueGrant: connectionId is required');
+            throw new Error("issueGrant: connectionId is required");
         if (!holderId)
-            throw new Error('issueGrant: holderId is required');
-        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants`, {
+            throw new Error("issueGrant: holderId is required");
+        return this._request("POST", `/connections/${encodeURIComponent(connectionId)}/grants`, {
             holderId,
             caveats,
         });
@@ -141,20 +151,20 @@ export class ConnectionsClient {
      */
     async attenuateGrant({ connectionId, grantId, holderId, caveats, }) {
         if (!connectionId)
-            throw new Error('attenuateGrant: connectionId is required');
+            throw new Error("attenuateGrant: connectionId is required");
         if (!grantId)
-            throw new Error('attenuateGrant: grantId is required');
+            throw new Error("attenuateGrant: grantId is required");
         if (!holderId)
-            throw new Error('attenuateGrant: holderId is required');
-        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}/attenuate`, { holderId, caveats });
+            throw new Error("attenuateGrant: holderId is required");
+        return this._request("POST", `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}/attenuate`, { holderId, caveats });
     }
     /** Revoke a single connection grant. */
     async revokeGrant({ connectionId, grantId, }) {
         if (!connectionId)
-            throw new Error('revokeGrant: connectionId is required');
+            throw new Error("revokeGrant: connectionId is required");
         if (!grantId)
-            throw new Error('revokeGrant: grantId is required');
-        return this._request('DELETE', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}`, undefined);
+            throw new Error("revokeGrant: grantId is required");
+        return this._request("DELETE", `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}`, undefined);
     }
     /**
      * agent-initiated MCP connection request: ask the principal to
@@ -164,21 +174,23 @@ export class ConnectionsClient {
      */
     async requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }) {
         if (!serverUrl)
-            throw new Error('requestMcpConnection: serverUrl is required');
-        return (await this._request('POST', '/connections/mcp/requests', { serverUrl, tools, reason, chatId }, onBehalfOfUserId ? { 'X-On-Behalf-Of-User': onBehalfOfUserId } : undefined));
+            throw new Error("requestMcpConnection: serverUrl is required");
+        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, chatId }, onBehalfOfUserId
+            ? { "X-On-Behalf-Of-User": onBehalfOfUserId }
+            : undefined));
     }
     async _requestRaw(method, path, body, extraHeaders) {
         const init = {
             method,
             headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
-                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
                 ...extraHeaders,
-            }),
+            }, this.laneId),
         };
         if (body !== undefined)
             init.body = JSON.stringify(body);
         const response = await fetch(`${this.baseUrl}${path}`, init);
-        const text = await response.text().catch(() => '');
+        const text = await response.text().catch(() => "");
         if (!response.ok) {
             // ApiError (status/body/code); ConnectionsError remains the
             // documented duck type for callers that branch on `.status`.

package/dist/http/MarketplaceClient.d.ts

@@ -16,6 +16,13 @@ export interface PublishOfferPayload {
     /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
     audience?: BroadcastAudience;
     metadata?: Record<string, unknown>;
+    /**
+     * Replay handle, sent as the `Idempotency-Key` header — the same way
+     * `proposeAgreement` sends it. Re-publishing under the same key resolves to
+     * the listing already on the board; a NEW key republishes and retires the
+     * previous one. It used to ride in the body on this one route.
+     */
+    idempotencyKey?: string;
 }
 export declare function publishOffer(payload: PublishOfferPayload, creds: Creds): Promise<Agreement>;
 export interface PullOffersOptions {

package/dist/http/MarketplaceClient.js

@@ -21,17 +21,26 @@ function assertCreds(creds, op) {
 }
 export async function publishOffer(payload, creds) {
     assertCreds(creds, 'marketplace offer publish');
+    const { idempotencyKey, ...bodyData } = payload ?? {};
+    const headers = buildHeaders(creds);
+    if (idempotencyKey)
+        headers['Idempotency-Key'] = idempotencyKey;
     const res = await fetch(`${getMarketplaceBaseUrl()}/offers/publish`, {
         method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify(payload || {}),
+        headers,
+        body: JSON.stringify(bodyData),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         throwApiError(res, body, `Marketplace offer publish failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
-    return shapeAgreement((data?.['offer'] ?? data));
+    // One key name across every agreement-creating route. This used to read
+    // `offer`, which was this route's own name for the same thing.
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from POST /marketplace/offers/publish');
+    }
+    return shapeAgreement(data['agreement']);
 }
 export async function pullOffers(options, creds) {
     assertCreds(creds, 'marketplace offers pull');

package/dist/http/PaymentsClient.d.ts

@@ -93,21 +93,39 @@ export declare class PaymentsClient {
         userId?: string;
         agentId?: string;
     }): Promise<WalletRef | null>;
-    transfer({ to, amount, idempotencyKey, description, paymentGrantId, }: {
+    transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
         to: string;
         amount: number;
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
+        /** The engagement this spend belongs to, so its own grant is preferred. */
+        agreementId?: string;
     }): Promise<TransferResult>;
-    hold({ amount, idempotencyKey, description, paymentGrantId, }: {
+    hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
         amount: number;
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
+        /** The engagement this spend belongs to, so its own grant is preferred. */
+        agreementId?: string;
     }): Promise<HoldResult>;
-    /** Prefer a single active wallet grant the agent already holds. */
-    private resolveAgentPaymentGrantId;
+    /**
+     * 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;

package/dist/http/PaymentsClient.js

@@ -1,6 +1,7 @@
 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)}`;
@@ -45,18 +46,13 @@ export class PaymentsClient {
         const res = (await this._get(`/payments/wallets/resolve?${params}`));
         return res['wallet'] || null;
     }
-    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, }) {
+    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
         if (!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)');
-        // resolve a standing/active grant when the caller omitted one
-        // (Claude/MCP ensureForUser mints it). Explicit id still wins.
-        if (this.agentId && !paymentGrantId) {
-            paymentGrantId = (await this.resolveAgentPaymentGrantId()) ?? undefined;
-        }
-        if (this.agentId && !paymentGrantId)
-            throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
+        // The recipient is resolved BEFORE choosing a grant: an `allowed_recipients`
+        // caveat cannot be checked against a name the client has not resolved yet.
         let toWalletId = to;
         if (!to.startsWith('wal_')) {
             const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
@@ -64,6 +60,15 @@ export class PaymentsClient {
                 throw new Error(`transfer: could not resolve wallet for "${to}"`);
             toWalletId = w.walletId;
         }
+        // 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,
@@ -90,15 +95,18 @@ export class PaymentsClient {
             amount,
         };
     }
-    async hold({ amount, idempotencyKey, description, paymentGrantId, }) {
+    async hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('hold: `amount` must be a positive integer (cents)');
-        // agent holds reserve the owner's wallet; require a grant.
+        // 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) {
-            paymentGrantId = (await this.resolveAgentPaymentGrantId()) ?? undefined;
+            const picked = await this.selectPaymentGrant({ amount, agreementId });
+            if (!picked.grant) {
+                throw new Error(describeNoGrant('hold', { amount, agreementId }, picked.rejected));
+            }
+            paymentGrantId = picked.grant.grantId;
         }
-        if (this.agentId && !paymentGrantId)
-            throw new Error('hold: paymentGrantId is required for agent-impersonated holds. The wallet owner must have issued a payment grant to this agentId.');
         return (await this._post('/payments/hold', {
             amount,
             idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'),
@@ -106,16 +114,37 @@ export class PaymentsClient {
             paymentGrantId,
         }));
     }
-    /** Prefer a single active wallet grant the agent already holds. */
-    async resolveAgentPaymentGrantId() {
+    /**
+     * 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 {
-            const grants = await this.listGrants();
-            const id = grants[0]?.grantId;
-            return typeof id === 'string' && id.length > 0 ? id : null;
+            fromWalletId = (await this.balance()).walletId;
         }
         catch {
-            return null;
+            fromWalletId = null;
         }
+        return selectPaymentGrant(grants, { ...spend, fromWalletId });
     }
     async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
         return (await this._post(`/payments/release/${holdId}`, {

package/dist/http/agreementFlows.js

@@ -38,12 +38,18 @@ export async function proposeUnified(input, creds) {
         }, creds);
         return { agreement, shape: 'request' };
     }
-    if (!chatId)
-        throw new Error('chatId is required on a direct proposal');
+    // No room is a shape, not an error. The server has always accepted a direct
+    // proposal without one, and this throw was the only thing that made the answer
+    // depend on which client you used: an agreement between parties who have no
+    // conversation had to invent a chat id to be created. Delivery does not go
+    // through the room — the create-time event targets the party slots — so the
+    // counterparty is told either way.
     const agreement = await proposeDirectTo({
         ...terms,
         proposedTo,
-        chatId,
+        // Omitted rather than sent empty: an absent field says "no room", and an
+        // empty string is one more fiction for the server to interpret.
+        ...(chatId ? { chatId } : {}),
         providerId: providerId?.trim() || proposedTo,
         engagementKind: engagementKind ?? 'service',
     }, creds);

package/dist/http/paymentGrantSelection.d.ts

@@ -0,0 +1,53 @@
+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.
+ */
+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

@@ -0,0 +1,111 @@
+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}`;
+    }
+    // An agreement-conferred grant is FOR that agreement's work. Spending it on
+    // something else would pass every caveat above and still be the wrong money:
+    // the ceiling was agreed for one engagement, and nothing on the wire would
+    // show it had been used for another.
+    if (grant.agreementId) {
+        if (!spend.agreementId) {
+            return `belongs to agreement ${grant.agreementId}, and this spend names no agreement`;
+        }
+        if (grant.agreementId !== spend.agreementId) {
+            return `belongs to agreement ${grant.agreementId}, not ${spend.agreementId}`;
+        }
+    }
+    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.
+ */
+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 };
+    const forAgreement = spend.agreementId
+        ? fitting.find((g) => g.agreementId === spend.agreementId)
+        : undefined;
+    return { grant: forAgreement ?? 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}`);
+}

package/package.json

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