@ziggs-ai/api-client 0.9.0 → 0.9.2

package/dist/ConnectionManager.d.ts

@@ -1,87 +1,51 @@
-import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
-export interface StartAgentOptions {
-    /**
-     * Keep this host running until it is stopped explicitly — exempt from the
-     * idle sweep, last choice for LRU eviction. For agents the operator named
-     * (launcher `preStart` / `WAKE_AGENTS`): they were started because someone
-     * decided they must be up, not because work arrived, so "no work for a
-     * while" is not a reason to retire them.
-     */
-    pinned?: boolean;
-}
 export interface ConnectionManagerMeta {
     domain?: string;
     expertise?: string[];
     tags?: string[];
     [key: string]: unknown;
 }
-export interface ConnectionManagerOptions {
-    maxActive?: number;
-    idleTimeoutMs?: number;
-    /**
-     * Fleet control (delivery law, phase 4): the operator key whose owned agents
-     * this manager lazily starts. `start()` long-polls `GET /inbox/operator` with
-     * this key; when an agent's slice shows actionable content, it starts that
-     * agent's host (which then consumes via its own per-agent inbox loop). No
-     * socket, no push notification — lazy process management driven by the poll. `wsUrl`
-     * is accepted for back-compat but unused (the poll is HTTP).
-     */
-    control?: {
-        wsUrl?: string;
-        operatorKey?: string;
-    };
-    /**
-     * Gate on the operator-poll lazy start (ZIG-910). Called for each agent
-     * slice with actionable content before its host is started; return false to
-     * leave the host down this pass. The slice stays in later envelopes (reading
-     * never acks), so the gate is consulted again on every poll. Explicit
-     * `startAgent()` calls are not gated. Default: everything actionable starts.
-     */
-    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
-}
 export interface QueryFilter {
     domain?: string;
     expertise?: string[];
     tags?: string[];
 }
+/**
+ * ConnectionManager — the set of agent hosts this process runs.
+ *
+ * Every registered agent is connected and stays connected (ZIG-1108). There is
+ * no subset, no cap, no idle sweep and no lifecycle policy: an agent is alive
+ * because its launcher registered it, and the only thing that takes it down is
+ * the process exiting. Whether work has arrived recently is not a fact about
+ * whether an agent should exist.
+ *
+ * What this replaced: an operator long-poll that asked the backend which agents
+ * had mail, an LRU that evicted hosts past `maxActive`, an idle timer that slept
+ * quiet hosts, and a `pinned` flag to exempt the ones an operator had named.
+ * Together they made liveness depend on someone remembering to edit a Terraform
+ * string, and cost a fleet-wide sweep per poll to find out nothing had changed.
+ */
 export declare class ConnectionManager {
-    private maxActive;
-    private idleTimeoutMs;
-    private _operatorKey;
-    private _polling;
-    private _pollDone;
     private _entries;
     private _active;
     private _meta;
     private _starting;
-    private _pinned;
-    private _shouldLazyStart;
-    constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
+    constructor();
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
-    start(operatorKey?: string): void;
-    stop(): Promise<void>;
     /**
-     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
-     * owned agent whose slice is actionable and not already running. The started
-     * host consumes + acks via its own per-agent inbox loop, so this loop never
-     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
-     * the loop never exits until `stop()` (nothing to resynchronize).
+     * Connect every registered agent. One host's failure to come up is reported
+     * and does not hold back the rest — its own transport retries, and a fleet
+     * where 28 of 29 are live is not a launch worth aborting.
      */
-    private _runOperatorPoll;
-    startAgent(id: string, { pinned }?: StartAgentOptions): Promise<unknown>;
-    sleep(id: string): Promise<void>;
-    sleepAll(): Promise<void>;
-    touch(id: string): void;
+    connectAll(): Promise<void>;
+    startAgent(id: string): Promise<unknown>;
+    stopAgent(id: string): Promise<void>;
+    stopAll(): Promise<void>;
     list(): string[];
     listActive(): string[];
-    listPinned(): string[];
     get size(): number;
     query({ domain, expertise, tags }?: QueryFilter): string[];
     getMeta(id: string): ConnectionManagerMeta | undefined;
-    private _scheduleIdle;
-    private _resetTimer;
-    private _evictLRU;
 }
 export {};

package/dist/ConnectionManager.js

@@ -1,36 +1,29 @@
-import { InboxClient } from './http/InboxClient.js';
 import { runtimeLog } from './shared/runtimeLog.js';
-import { isRateLimited } from './shared/rateLimit.js';
-const OPERATOR_POLL_WAIT_SECONDS = 25;
-const POLL_BACKOFF_BASE_MS = 1_000;
-const POLL_BACKOFF_MAX_MS = 30_000;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+/**
+ * ConnectionManager — the set of agent hosts this process runs.
+ *
+ * Every registered agent is connected and stays connected (ZIG-1108). There is
+ * no subset, no cap, no idle sweep and no lifecycle policy: an agent is alive
+ * because its launcher registered it, and the only thing that takes it down is
+ * the process exiting. Whether work has arrived recently is not a fact about
+ * whether an agent should exist.
+ *
+ * What this replaced: an operator long-poll that asked the backend which agents
+ * had mail, an LRU that evicted hosts past `maxActive`, an idle timer that slept
+ * quiet hosts, and a `pinned` flag to exempt the ones an operator had named.
+ * Together they made liveness depend on someone remembering to edit a Terraform
+ * string, and cost a fleet-wide sweep per poll to find out nothing had changed.
+ */
 export class ConnectionManager {
-    maxActive;
-    idleTimeoutMs;
-    _operatorKey;
-    _polling;
-    _pollDone;
     _entries;
     _active;
     _meta;
     _starting;
-    _pinned;
-    _shouldLazyStart;
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
-        this.maxActive = maxActive;
-        this.idleTimeoutMs = idleTimeoutMs;
-        this._shouldLazyStart = shouldLazyStart ?? null;
-        this._operatorKey = control?.operatorKey ?? null;
-        this._polling = false;
-        this._pollDone = null;
+    constructor() {
         this._entries = new Map();
         this._active = new Map();
         this._meta = new Map();
         this._starting = new Map();
-        this._pinned = new Set();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -43,103 +36,34 @@ export class ConnectionManager {
         if (meta)
             this._meta.set(id, meta);
     }
-    start(operatorKey) {
-        if (operatorKey)
-            this._operatorKey = operatorKey;
-        if (this._polling || !this._operatorKey)
-            return;
-        this._polling = true;
-        this._pollDone = this._runOperatorPoll(this._operatorKey);
-    }
-    async stop() {
-        this._polling = false;
-        if (this._pollDone)
-            await this._pollDone.catch(() => { });
-        this._pollDone = null;
-        await this.sleepAll();
-    }
     /**
-     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
-     * owned agent whose slice is actionable and not already running. The started
-     * host consumes + acks via its own per-agent inbox loop, so this loop never
-     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
-     * the loop never exits until `stop()` (nothing to resynchronize).
+     * Connect every registered agent. One host's failure to come up is reported
+     * and does not hold back the rest — its own transport retries, and a fleet
+     * where 28 of 29 are live is not a launch worth aborting.
      */
-    async _runOperatorPoll(operatorKey) {
-        // No agentId → operator-level multiplex read (transport auth only).
-        const inbox = new InboxClient(operatorKey);
-        let consecutiveErrors = 0;
-        while (this._polling) {
-            try {
-                // Roster scoping (ZIG-965): only agents this manager can actually
-                // start are worth sweeping server-side. Without it a partial launcher
-                // (ONLY_AGENTS) paid for a sweep of the owner's whole seeded fleet.
-                //
-                // Already-running agents are excluded: this loop's only job is
-                // lazy-start, and a running host polls its own inbox. Sending them
-                // made the server answer for agents whose entry we then discarded
-                // below — pure duplicate work, growing with how healthy the fleet is.
-                const startable = [...this._entries.keys()].filter((id) => !this._active.has(id));
-                const env = await inbox.getOperatorInbox({
-                    waitSeconds: OPERATOR_POLL_WAIT_SECONDS,
-                    agents: startable,
-                });
-                consecutiveErrors = 0;
-                for (const entry of env.agents) {
-                    const id = entry.agentId;
-                    // Only slices with actionable content are listed; start the host if
-                    // it isn't already running and we know how to open it.
-                    if (!id || this._active.has(id) || !this._entries.has(id))
-                        continue;
-                    if (this._shouldLazyStart && !this._shouldLazyStart(entry))
-                        continue;
-                    this.startAgent(id).catch((err) => runtimeLog.warn('ConnectionManager', `lazy-start("${id}") failed: ${err.message}`));
-                }
-            }
-            catch (err) {
-                if (!this._polling)
-                    break;
-                consecutiveErrors++;
-                // ZIG-1019: same rule as the per-agent loop — when the server throttles
-                // us it also says for how long, and retrying sooner just spends more of
-                // the budget we were told we are out of.
-                const throttleMs = isRateLimited(err) ? (err.retryAfterMs ?? 30_000) : null;
-                if (throttleMs !== null) {
-                    consecutiveErrors = 0;
-                    runtimeLog.warn('ConnectionManager', `operator poll throttled: ${err.message} — waiting ${Math.round(throttleMs)}ms as instructed`);
-                    await sleep(throttleMs);
-                    continue;
-                }
-                const backoff = Math.min(POLL_BACKOFF_MAX_MS, POLL_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
-                const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14);
-                runtimeLog.warn('ConnectionManager', `operator poll failed (#${consecutiveErrors}): ${err.message} — retrying in ~${Math.round(jitter)}ms`);
-                await sleep(jitter);
-            }
-        }
+    async connectAll() {
+        const ids = [...this._entries.keys()];
+        // The count is the cost: every registered agent is one WS connection plus
+        // one inbox long-poll, held for the life of the process. There is no cap,
+        // so a registration list that balloons shows up here first — loudly, with
+        // the number, before the sockets open.
+        runtimeLog.info('ConnectionManager', `connecting all ${ids.length} registered agent(s) — one connection + inbox long-poll each, for the life of the process`);
+        await Promise.all(ids.map((id) => this.startAgent(id).catch((err) => runtimeLog.warn('ConnectionManager', `start("${id}") failed: ${err.message}`))));
     }
-    async startAgent(id, { pinned = false } = {}) {
-        // Recorded before any await so a pin is never lost to a concurrent
-        // unpinned start of the same id.
-        if (pinned)
-            this._pinned.add(id);
+    async startAgent(id) {
         const existing = this._active.get(id);
-        if (existing) {
-            this._resetTimer(id);
-            return existing.handle;
-        }
+        if (existing)
+            return existing;
         const pending = this._starting.get(id);
         if (pending)
             return pending;
         const entry = this._entries.get(id);
         if (!entry)
             throw new Error(`[ConnectionManager] unknown id: "${id}"`);
-        if (this._active.size >= this.maxActive)
-            await this._evictLRU();
         const startPromise = (async () => {
             try {
                 const handle = await entry.openFn();
-                this._active.set(id, { handle, timer: null, lastActive: Date.now() });
-                this._scheduleIdle(id);
+                this._active.set(id, handle);
                 return handle;
             }
             finally {
@@ -149,23 +73,20 @@ export class ConnectionManager {
         this._starting.set(id, startPromise);
         return startPromise;
     }
-    async sleep(id) {
-        const entry = this._active.get(id);
-        if (!entry)
+    async stopAgent(id) {
+        if (!this._active.has(id))
             return;
-        clearTimeout(entry.timer);
+        const handle = this._active.get(id);
         this._active.delete(id);
         const reg = this._entries.get(id);
         if (reg)
-            await reg.closeFn(entry.handle);
+            await reg.closeFn(handle);
     }
-    async sleepAll() {
-        await Promise.all([...this._active.keys()].map(id => this.sleep(id)));
+    async stopAll() {
+        await Promise.all([...this._active.keys()].map(id => this.stopAgent(id)));
     }
-    touch(id) { this._resetTimer(id); }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }
-    listPinned() { return [...this._pinned]; }
     get size() { return this._entries.size; }
     query({ domain, expertise, tags } = {}) {
         const results = [];
@@ -181,54 +102,4 @@ export class ConnectionManager {
         return results;
     }
     getMeta(id) { return this._meta.get(id); }
-    _scheduleIdle(id) {
-        const entry = this._active.get(id);
-        if (!entry)
-            return;
-        clearTimeout(entry.timer);
-        // A pinned host has no idle timer at all. Empty polls don't count as
-        // activity (only delivered items call touch()), so a pinned agent nobody
-        // talks to would otherwise be swept — and with lazy start unable to keep
-        // up at fleet size, nothing brings it back until the process restarts.
-        if (this._pinned.has(id)) {
-            entry.timer = null;
-            return;
-        }
-        entry.timer = setTimeout(() => {
-            this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
-        }, this.idleTimeoutMs);
-    }
-    _resetTimer(id) {
-        const entry = this._active.get(id);
-        if (!entry)
-            return;
-        entry.lastActive = Date.now();
-        this._scheduleIdle(id);
-    }
-    async _evictLRU() {
-        // Pinned hosts are the last to go: pick the LRU unpinned one, and only
-        // fall back to a pinned one when every active host is pinned. maxActive
-        // stays a hard cap — a pin outranks other agents, not the capacity limit —
-        // but say so, because it means more agents were pinned than can run.
-        const oldestOf = (ids) => {
-            let oldest = null;
-            for (const id of ids) {
-                const entry = this._active.get(id);
-                const oldestEntry = oldest ? this._active.get(oldest) : null;
-                if (!entry)
-                    continue;
-                if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
-                    oldest = id;
-            }
-            return oldest;
-        };
-        const active = [...this._active.keys()];
-        const victim = oldestOf(active.filter(id => !this._pinned.has(id))) ?? oldestOf(active);
-        if (!victim)
-            return;
-        if (this._pinned.has(victim)) {
-            runtimeLog.warn('ConnectionManager', `evicting pinned "${victim}": all ${active.length} active hosts are pinned and maxActive=${this.maxActive} is reached — pin fewer agents or raise maxActive`);
-        }
-        await this.sleep(victim);
-    }
 }

package/dist/capabilities/agreements.js

@@ -1,5 +1,5 @@
 import { claimOpenAgreement } from '../http/agreementFlows.js';
-import { linkIsReachOnly, linkSummary } from './links.js';
+import { linkIsReachOnly } from './links.js';
 import { fullCreds } from './types.js';
 /**
  * ZIG-1021 — the one claim verb. Quests, standing offers, and link invites
@@ -29,7 +29,7 @@ export const agreementClaimCapability = {
                 status: 'linked',
                 kind,
                 message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
-                agreement: linkSummary(agreement),
+                agreement,
             };
         }
         return {

package/dist/capabilities/chat.js

@@ -12,8 +12,8 @@ export const openConversationCapability = {
     key: 'chat_open',
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — agreement_propose with engagementKind "link" (if you have its agent id) or link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use grant_list scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — ziggs_agreement_propose with engagementKind "link" (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, establish a link first — agreement_propose with engagementKind "link" (if you have its agent id) or link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use grant_list scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — ziggs_agreement_propose with engagementKind "link" (if you have its agent id) or ziggs_link_create_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
     },
     annotation: 'write',
     params: {
@@ -22,12 +22,22 @@ export const openConversationCapability = {
             required: true,
             description: 'User or agent id to converse with (from agent search — do not guess ids)',
         },
+        newChat: {
+            type: 'boolean',
+            description: 'Open a separate chat even though one is already open with this participant. ' +
+                'For when the conversation is genuinely its own subject and would confuse an ' +
+                'existing thread. The separate chat does not become the main one, so a later ' +
+                'call without this still returns the original. Leave unset to continue where ' +
+                'you left off.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         if (!args['participantId'])
             throw new Error('participantId is required');
-        const { chatId } = await openConversation(args['participantId'], fullCreds(env));
+        const { chatId } = await openConversation(args['participantId'], fullCreds(env), {
+            newChat: args['newChat'] === true,
+        });
         const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
         return {
             chatId,

package/dist/capabilities/connections.js

@@ -97,7 +97,7 @@ export const requestConnectionCapability = {
                 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_connection_proxy.'
-                    : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
+                    : '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 connection_proxy.',
             };
         }

package/dist/capabilities/index.d.ts

@@ -1,6 +1,6 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/index.js

@@ -1,6 +1,6 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/links.d.ts

@@ -1,12 +1,4 @@
-import type { Agreement } from '../types.js';
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
-/**
- * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
- * block, approvals array, and Mongo internals are noise on a trust
- * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
- * return it too (they used to leak the raw agreement doc).
- */
-export declare function linkSummary(a: Agreement): Record<string, unknown>;
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *

package/dist/capabilities/links.js

@@ -18,27 +18,6 @@ function webAppOrigin(env) {
 function inviteShareUrl(env, agreementId) {
     return `${webAppOrigin(env)}/connect/${agreementId}`;
 }
-/**
- * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
- * block, approvals array, and Mongo internals are noise on a trust
- * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
- * return it too (they used to leak the raw agreement doc).
- */
-export function linkSummary(a) {
-    return {
-        agreementId: a.agreementId,
-        status: a.status,
-        proposalStatus: a.proposalStatus,
-        parties: {
-            creatorAgent: a.parties?.creatorAgent ?? null,
-            providerAgent: a.parties?.providerAgent ?? null,
-            creator: a.parties?.creator ?? null,
-            proposedTo: a.parties?.proposedTo ?? null,
-        },
-        ...(a.description ? { description: a.description } : {}),
-        createdAt: a.createdAt,
-    };
-}
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *
@@ -106,7 +85,7 @@ export const createLinkInviteCapability = {
             message: env.surface === 'mcp'
                 ? `Open link invite created, ${seatNote}. Give the human shareUrl and nothing else — it is the whole invite. A recipient with no Ziggs account signs up straight from that page, no beta code needed, and accepting the link is part of the same step; a recipient who would rather their own assistant do the wiring can hand it the same URL, because the page carries the MCP server address and the claim instructions in its markup. Either way the recipient needs their own assistant connected before the link carries anything.`
                 : `Open link invite created, ${seatNote}. shareUrl is the whole invite: a recipient with no Ziggs account signs up straight from that page and accepts the link in the same step, and an assistant handed the same URL reads the connect instructions off it. They still need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
-            agreement: linkSummary(agreement),
+            agreement,
         };
     },
     sdkOptions: { isAgreementCreation: true },
@@ -136,12 +115,11 @@ export const listLinksCapability = {
             engagementKind: 'link',
             ...(status === 'all' ? {} : { status }),
         }, fullCreds(env));
-        const summaries = links.map(linkSummary);
         const hasActive = links.some((a) => a.status === 'active');
         return {
-            count: summaries.length,
+            count: links.length,
             status,
-            links: summaries,
+            links,
             ...(hasActive ? { nextSteps: linkIsReachOnly(env) } : {}),
         };
     },

package/dist/capabilities/payments.js

@@ -216,6 +216,10 @@ export const paymentHoldCapability = {
         amount: { type: 'number', required: true, description: 'Amount in integer cents, > 0' },
         description: { type: 'string', description: 'Human-readable hold memo' },
         idempotencyKey: { type: 'string', description: 'Client-supplied retry-safety key' },
+        paymentGrantId: {
+            type: 'string',
+            description: 'Payment grant authorizing this hold (required for agent actors; auto-picks an active wallet grant when omitted)',
+        },
     },
     handler: async (args, env) => {
         const amount = args['amount'];
@@ -226,6 +230,7 @@ export const paymentHoldCapability = {
                 amount: Math.round(amount),
                 description: args['description'] || 'Agent escrow hold',
                 idempotencyKey: args['idempotencyKey'],
+                paymentGrantId: args['paymentGrantId'],
             });
             return {
                 status: 'held',

package/dist/capabilities/types.js

@@ -21,6 +21,9 @@ export function rethrowWithContext(error, prefix) {
         wrapped.status = e.status;
     if (e.body !== undefined)
         wrapped.body = e.body;
+    // ZIG-1124 — keep the machine code so toolError can classify without prose.
+    if (typeof e.code === 'string' && e.code)
+        wrapped.code = e.code;
     wrapped['cause'] = error;
     throw wrapped;
 }

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Runtime configuration for this package, injected by whoever owns the process.
+ *
+ * This package used to read `process.env` directly, which is why every http
+ * client began with `import 'dotenv/config'`. Metro (React Native's bundler)
+ * cannot resolve dotenv, so a mobile consumer could not import api-client at
+ * all. The environment is now read by the host — `env-init.ts` in this repo,
+ * the MCP server's config loader, a mobile app's bootstrap — and handed here.
+ *
+ * Configure before constructing clients: `getBackendUrl()` is called in their
+ * constructors, so a client built first keeps the URL that was current then.
+ */
+/** Threshold names accepted by {@link ApiClientConfig.logLevel}. */
+export type ApiClientLogLevel = 'debug' | 'trace' | 'info' | 'warn' | 'error' | 'silent' | 'none';
+export interface ApiClientConfig {
+    /** Backend base URL. Falls back to production when nothing sets it. */
+    httpUrl?: string;
+    /** WebSocket base URL. Falls back to production when nothing sets it. */
+    wsUrl?: string;
+    /** `runtimeLog` threshold. Falls back to `info`. */
+    logLevel?: ApiClientLogLevel;
+}
+/**
+ * Merge settings into the package config. Partial: passing only `logLevel`
+ * leaves a previously configured `httpUrl` alone. Explicit `undefined` is
+ * ignored rather than treated as a clear, so a host can spread a half-filled
+ * options object without wiping what it already set.
+ */
+export declare function configureApiClient(next: ApiClientConfig): void;
+/** Current config. Read-only — mutate through {@link configureApiClient}. */
+export declare function apiClientConfig(): Readonly<ApiClientConfig>;
+/** Generation counter for cache invalidation. */
+export declare function apiClientConfigVersion(): number;

package/dist/config.js

@@ -0,0 +1,42 @@
+/**
+ * Runtime configuration for this package, injected by whoever owns the process.
+ *
+ * This package used to read `process.env` directly, which is why every http
+ * client began with `import 'dotenv/config'`. Metro (React Native's bundler)
+ * cannot resolve dotenv, so a mobile consumer could not import api-client at
+ * all. The environment is now read by the host — `env-init.ts` in this repo,
+ * the MCP server's config loader, a mobile app's bootstrap — and handed here.
+ *
+ * Configure before constructing clients: `getBackendUrl()` is called in their
+ * constructors, so a client built first keeps the URL that was current then.
+ */
+const config = {};
+/**
+ * Bumped on every configure so derived caches (the log threshold) know to
+ * recompute. A version counter rather than a reset callback because
+ * `runtimeLog` reads config — a callback the other way would be a cycle.
+ */
+let version = 0;
+/**
+ * Merge settings into the package config. Partial: passing only `logLevel`
+ * leaves a previously configured `httpUrl` alone. Explicit `undefined` is
+ * ignored rather than treated as a clear, so a host can spread a half-filled
+ * options object without wiping what it already set.
+ */
+export function configureApiClient(next) {
+    if (next.httpUrl !== undefined)
+        config.httpUrl = next.httpUrl;
+    if (next.wsUrl !== undefined)
+        config.wsUrl = next.wsUrl;
+    if (next.logLevel !== undefined)
+        config.logLevel = next.logLevel;
+    version += 1;
+}
+/** Current config. Read-only — mutate through {@link configureApiClient}. */
+export function apiClientConfig() {
+    return config;
+}
+/** Generation counter for cache invalidation. */
+export function apiClientConfigVersion() {
+    return version;
+}

package/dist/http/AgentSearchClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export interface AgentSearchOptions {
     limit?: number;
     minScore?: number;

package/dist/http/AgentSearchClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';