@ziggs-ai/api-client 0.9.1 → 0.9.3

package/dist/ConnectionManager.d.ts

@@ -40,8 +40,8 @@ export declare class ConnectionManager {
      */
     connectAll(): Promise<void>;
     startAgent(id: string): Promise<unknown>;
-    sleep(id: string): Promise<void>;
-    sleepAll(): Promise<void>;
+    stopAgent(id: string): Promise<void>;
+    stopAll(): Promise<void>;
     list(): string[];
     listActive(): string[];
     get size(): number;

package/dist/ConnectionManager.js

@@ -73,7 +73,7 @@ export class ConnectionManager {
         this._starting.set(id, startPromise);
         return startPromise;
     }
-    async sleep(id) {
+    async stopAgent(id) {
         if (!this._active.has(id))
             return;
         const handle = this._active.get(id);
@@ -82,8 +82,8 @@ export class ConnectionManager {
         if (reg)
             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)));
     }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }

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/grants.js

@@ -38,16 +38,25 @@ export const listGrantsCapability = {
     key: 'grant_list',
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     descriptions: {
-        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. To answer "what can I reach?" instead, use context_expand_reach to enumerate a scope, or context_read to read through a grant.',
-        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. To answer "what can I reach?" instead, use ziggs_context_expand_reach to enumerate a scope, or pass a grantId to ziggs_context_read to pin a specific grant.',
+        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
     },
     annotation: 'read-only',
     params: {
+        role: {
+            type: 'string',
+            enum: ['holder', 'issuer'],
+            description: 'holder (default): grants you hold. issuer: grants you caused — author-shares you made and delegate children you minted (not your human owner\'s full issuer view).',
+        },
         scopeKind: {
             type: 'array',
             items: { type: 'string', enum: SCOPE_KINDS },
             description: 'Rail filter (repeatable): chat | agreement | org | artifact (context) | connection | wallet. Omit for every rail you can read.',
         },
+        scopeId: {
+            type: 'string',
+            description: 'Narrow to one resource id (e.g. one artifactId) within the rails above.',
+        },
         health: {
             type: 'string',
             enum: HEALTHS,
@@ -64,8 +73,14 @@ export const listGrantsCapability = {
         if (healthArg !== undefined && !HEALTHS.includes(healthArg)) {
             throw new Error(`health must be one of ${HEALTHS.join(', ')}`);
         }
+        const roleArg = args['role'];
+        if (roleArg !== undefined && roleArg !== 'holder' && roleArg !== 'issuer') {
+            throw new Error('role must be holder or issuer');
+        }
         const { items, nextCursor, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).listGrants({
             scopeKind,
+            scopeId: typeof args['scopeId'] === 'string' ? args['scopeId'] : undefined,
+            role: roleArg,
             // Reach = live grants only by default; pass health to see expired/revoked.
             health: healthArg ?? 'active',
             cursor: args['cursor'],

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/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';

package/dist/http/AgreementClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.

package/dist/http/AgreementClient.js

@@ -1,11 +1,10 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
-// Lazy: read at call time so dotenv loaded after this module is imported
-// still takes effect. Baking it at module-load time would freeze the URL
-// before the caller's dotenv.config() runs.
+// Lazy: read at call time so a `configureApiClient` call that lands after this
+// module is imported still takes effect. Baking it at module-load time would
+// freeze the URL before the host has configured one.
 function getAgreementBaseUrl() {
     return `${getBackendUrl()}/agreements`;
 }

package/dist/http/ArtifactsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export type ArtifactVisibility = 'chat' | 'agent-private';
 export interface ListArtifactsOptions {
     after?: string;

package/dist/http/ArtifactsClient.js

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

package/dist/http/ChatClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds } from '../types.js';
 /** Shape of GET /chats/mine items — the backend's ChatReadDto (ZIG-665). */
 export interface ChatSummary {
@@ -10,7 +9,9 @@ export interface ChatSummary {
     orgId: string | null;
     isOrgChat: boolean;
 }
-export declare function openConversation(participantId: string, creds: Creds): Promise<{
+export declare function openConversation(participantId: string, creds: Creds, { newChat }?: {
+    newChat?: boolean;
+}): Promise<{
     chatId: string;
 }>;
 export interface SendChatMessageInput {
@@ -75,7 +76,9 @@ export declare class ChatClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string);
-    open(participantId: string): Promise<{
+    open(participantId: string, opts?: {
+        newChat?: boolean;
+    }): Promise<{
         chatId: string;
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;

package/dist/http/ChatClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
@@ -18,14 +17,16 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-export async function openConversation(participantId, creds) {
+export async function openConversation(participantId, creds, { newChat = false } = {}) {
     if (!participantId)
         throw new Error('participantId is required for openConversation');
     assertCreds(creds, 'open conversation');
     const res = await fetch(`${getBackendUrl()}/chats`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ participantId }),
+        // Only sent when asked for: an older backend ignores the field, so a
+        // caller that never wants a separate room behaves identically either way.
+        body: JSON.stringify({ participantId, ...(newChat ? { newChat: true } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -137,7 +138,7 @@ export class ChatClient {
         // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
-    open(participantId) { return openConversation(participantId, this.creds); }
+    open(participantId, opts) { return openConversation(participantId, this.creds, opts); }
     addMember(input) { return addChatMember(input, this.creds); }
     sendMessage(input) { return sendChatMessage(input, this.creds); }
     listMine() { return listMyChats(this.creds); }

package/dist/http/ConnectionsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView } from './grants.js';
 export declare function assertNoLeakedConnectionSecret(serialized: string): void;
 /** Thrown by ConnectionsClient with the HTTP status and raw body attached. */

package/dist/http/ConnectionsClient.js

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

package/dist/http/ContextDiscoveryClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 /**
  * Labels-only pointer to context the agent could request access to (P4).
  * ZIG-927: covers chats, agreements, and connections; connection labels are the

package/dist/http/ContextDiscoveryClient.js

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

package/dist/http/ContextGrantsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView } from './grants.js';
 /**
  * ZIG-1037 added `artifact` — the narrowest context scope: one specific artifact,

package/dist/http/ContextGrantsClient.js

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

package/dist/http/ContextReadClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export declare const CONTEXT_READ_TYPES: readonly ["messages", "artifacts", "agreements", "tasks"];
 export type ContextReadType = (typeof CONTEXT_READ_TYPES)[number];
 /**

package/dist/http/ContextReadClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 export const CONTEXT_READ_TYPES = [

package/dist/http/GrantsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView, GrantScopeKind, GrantHealth } from './grants.js';
 export interface ListGrantsQuery {
     /**
@@ -11,6 +10,15 @@ export interface ListGrantsQuery {
      * kinds: chat, agreement, org). Absent = every rail.
      */
     scopeKind?: GrantScopeKind | GrantScopeKind[];
+    /**
+     * Narrow to one resource id (e.g. one artifact). Server-side page filter.
+     */
+    scopeId?: string;
+    /**
+     * `'holder'` (default) = grants you hold. `'issuer'` = grants you caused
+     * (ZIG-1217 for agents: author-shares + delegate children).
+     */
+    role?: 'holder' | 'issuer';
     /** Filter to grants of one health. */
     health?: GrantHealth;
     cursor?: string;

package/dist/http/GrantsClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
@@ -31,6 +30,10 @@ export class GrantsClient {
             for (const k of kinds)
                 url.searchParams.append('scopeKind', k);
         }
+        if (query.scopeId)
+            url.searchParams.set('scopeId', query.scopeId);
+        if (query.role)
+            url.searchParams.set('role', query.role);
         if (query.health)
             url.searchParams.set('health', query.health);
         if (query.cursor)

package/dist/http/InboxClient.d.ts

@@ -1,133 +1,4 @@
-import 'dotenv/config';
-/**
- * What a delivery can be about. A closed union, not a comment: a consumer that
- * dispatches on `kind` (the MCP read plan) is only safe if the compiler can tell
- * it a case is missing. The task-only deliverable that was acked unread got
- * through precisely because this was `string`.
- *
- * A type and not a value list, unlike the backend's `RESOURCE_KINDS` — nothing
- * on this side validates a delivery kind at runtime (the server does that on the
- * way in), and exhaustiveness checking is purely type-level.
- */
-export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement';
-/**
- * One thing addressed to this agent. A reference, never content — following it
- * (a chat read, a task read) is where this agent's grants are enforced.
- */
-export interface InboxDeliveryRef {
-    kind: InboxDeliveryKind;
-    resourceId: string;
-    chatId: string | null;
-    agreementId: string | null;
-    taskId: string | null;
-    /** Who wrote it. Never this agent — you are not woken by your own writes. */
-    actorId: string | null;
-    ts: string;
-}
-/** Message/artifact deliveries folded by chat, so you can open chats directly. */
-export interface InboxChatNews {
-    chatId: string;
-    count: number;
-    latestAt: string;
-}
-export interface InboxProposalRef {
-    agreementId: string;
-    title: string;
-    proposedAt: string | null;
-    /**
-     * ZIG-1087 — party ids still owing a decision, and the named responder slot.
-     * The inbox lists proposals awaiting the agent OR its human, and only the
-     * agent's own slot is one it can submit; these say which is which.
-     *
-     * Optional because a backend deployed before ZIG-1087 omits them, and this
-     * client is installed independently of the server it talks to. Absent reads
-     * as "no slot of mine", which routes the decision to the human — the safe
-     * direction: it withholds a call, it never invents authority.
-     */
-    pendingApprovalPartyIds?: string[];
-    proposedTo?: string | null;
-}
-export interface InboxConnectionRequestRef {
-    requestId: string;
-    /**
-     * Non-addressable persona reference for the requester (`psn_*`).
-     * Never use as an account id for lookup / wake / pay (ZIG-1137).
-     */
-    requesterRef: string;
-    /** ZIG-1039 — human-readable name for consent cards. */
-    requesterDisplayName?: string | null;
-    /** ZIG-1039 — org label for consent cards. */
-    requesterOrgName?: string | null;
-    message: string | null;
-    requestedAt: string | null;
-    /** ZIG-1087 — see InboxProposalRef; a link request uses the same gate. */
-    pendingApprovalPartyIds?: string[];
-    proposedTo?: string | null;
-}
-/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482 / ZIG-481). */
-export interface InboxHumanAttention {
-    required: true;
-    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'multiple';
-    proposalCount: number;
-    truncatedProposals: number;
-    connectionRequestCount: number;
-    truncatedConnectionRequests: number;
-    promptUser: string;
-}
-/**
- * An open task assigned to this agent (ZIG-973). References only — read the
- * task for its description/plan/inputs.
- *
- * Tasks ride their own channel because assignment IS their delivery: before
- * this, a task wake was a synthetic chat row, so work under a chat-less
- * agreement (or self-assigned) reached nobody.
- */
-export interface InboxTaskRef {
-    taskId: string;
-    agreementId: string | null;
-    title: string;
-    state: string;
-    updatedAt: string | null;
-}
-export interface InboxEnvelope {
-    asOf: string;
-    /**
-     * Unacked deliveries addressed to this agent, newest first. This IS the
-     * inbox — read straight out of the delivery log, not derived from grants.
-     */
-    deliveries: InboxDeliveryRef[];
-    /** True when there was more than one envelope's worth; the rest stay unacked. */
-    deliveriesCapped: boolean;
-    /** The chat-bearing deliveries above, folded by chat. */
-    chats: InboxChatNews[];
-    /**
-     * Pass to `ack()` after acting. Null when there is nothing to ack. Ack after
-     * acting, not after reading: a crash in between redelivers.
-     */
-    ackTo: string | null;
-    /** Open tasks assigned to this agent — the work channel (ZIG-973). */
-    tasksAwaitingMe: InboxTaskRef[];
-    truncatedTasks: number;
-    proposalsAwaitingMe: InboxProposalRef[];
-    truncatedProposals: number;
-    connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
-    truncatedConnectionRequests: number;
-    humanAttention?: InboxHumanAttention;
-}
-export interface InboxAckResult {
-    /** Where the watermark now sits. Monotonic — a rewind is a no-op, not an error. */
-    ackedUpTo: string | null;
-}
-/**
- * Long-poll option shared by the inbox reads. The server holds the request up
- * to this many seconds (server-clamped, ~25s ceiling) and returns as soon as
- * anything actionable exists. Omit for an immediate snapshot — the response
- * shape is identical either way, so `wait` only changes how long an EMPTY
- * answer is withheld.
- */
-export interface InboxReadOptions {
-    waitSeconds?: number;
-}
+import type { InboxAckResult, InboxEnvelope, InboxReadOptions } from '../types.js';
 /**
  * The doorbell, not the door (ZIG-434): references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack

package/dist/http/InboxClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 /**

package/dist/http/MarketplaceClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds, type Agreement, type BroadcastAudience } from '../types.js';
 export interface PublishOfferPayload {
     description: string;

package/dist/http/MarketplaceClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 // ZIG-1111: one shaping rule for every agreement this package parses.
 import { shapeAgreement } from './AgreementClient.js';
 import { getBackendUrl } from '../utils/urlUtils.js';

package/dist/http/MessagesClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export interface ListMessagesOptions {
     /** ISO timestamp; only entries with `timestamp > after` are returned. */
     after?: string;

package/dist/http/MessagesClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
 /**

package/dist/http/OrgsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { Creds } from '../types.js';
 export interface MyOrg {
     orgId: string;

package/dist/http/OrgsClient.js

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

package/dist/http/PaymentsClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import type { GrantView } from './grants.js';
 /** Thrown by PaymentsClient with the HTTP status and raw body attached. */
 export interface PaymentsError extends Error {
@@ -101,11 +100,14 @@ export declare class PaymentsClient {
         description?: string;
         paymentGrantId?: string;
     }): Promise<TransferResult>;
-    hold({ amount, idempotencyKey, description, }: {
+    hold({ amount, idempotencyKey, description, paymentGrantId, }: {
         amount: number;
         idempotencyKey?: string;
         description?: string;
+        paymentGrantId?: string;
     }): Promise<HoldResult>;
+    /** Prefer a single active wallet grant the agent already holds (ZIG-1182). */
+    private resolveAgentPaymentGrantId;
     release({ holdId, action, toWalletId, idempotencyKey, }: {
         holdId: string;
         action?: string;

package/dist/http/PaymentsClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
@@ -51,6 +50,11 @@ export class PaymentsClient {
             throw new Error('transfer: `to` is required');
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('transfer: `amount` must be a positive integer (cents)');
+        // ZIG-1182 — 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.');
         let toWalletId = to;
@@ -86,15 +90,33 @@ export class PaymentsClient {
             amount,
         };
     }
-    async hold({ amount, idempotencyKey, description, }) {
+    async hold({ amount, idempotencyKey, description, paymentGrantId, }) {
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('hold: `amount` must be a positive integer (cents)');
+        // ZIG-1182 — agent holds reserve the owner's wallet; require a grant.
+        if (this.agentId && !paymentGrantId) {
+            paymentGrantId = (await this.resolveAgentPaymentGrantId()) ?? undefined;
+        }
+        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'),
             description,
+            paymentGrantId,
         }));
     }
+    /** Prefer a single active wallet grant the agent already holds (ZIG-1182). */
+    async resolveAgentPaymentGrantId() {
+        try {
+            const grants = await this.listGrants();
+            const id = grants[0]?.grantId;
+            return typeof id === 'string' && id.length > 0 ? id : null;
+        }
+        catch {
+            return null;
+        }
+    }
     async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
         return (await this._post(`/payments/release/${holdId}`, {
             idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'),

package/dist/http/TaskClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { type Creds, type Task, type TaskState } from '../types.js';
 /**
  * When the buyer reviews a task's plan. Task-rail only — an agreement has no

package/dist/http/TaskClient.js

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }

package/dist/http/TelemetryClient.d.ts

@@ -1,4 +1,3 @@
-import 'dotenv/config';
 export declare class TelemetryClient {
     private readonly operatorKey;
     private readonly agentId?;

package/dist/http/TelemetryClient.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';

package/dist/http/index.d.ts

@@ -26,4 +26,3 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, } from './InboxClient.js';

package/dist/index.d.ts

@@ -5,9 +5,11 @@ export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export type { PrincipalPresentation } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+export { configureApiClient, apiClientConfig } from './config.js';
+export type { ApiClientConfig, ApiClientLogLevel } from './config.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, } from './types.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxQuestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -4,6 +4,8 @@ export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
+// ZIG-652: the host injects the environment; this package never reads it.
+export { configureApiClient, apiClientConfig } from './config.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 // ZIG-1019 / ZIG-1124: one ApiError shape; 429s carry the server's wait.
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';

package/dist/shared/runtimeLog.d.ts

@@ -1,9 +1,3 @@
-/**
- * Same semantics as `@ziggs-ai/agent-sdk` `shared/runtimeLog.ts` (duplicated
- * here so this package stays dependency-free).
- *
- * @see agent-sdk/src/shared/runtimeLog.ts
- */
 export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
 export declare function resetRuntimeLogLevelCache(): void;
 export declare const runtimeLog: {

package/dist/shared/runtimeLog.js

@@ -4,6 +4,7 @@
  *
  * @see agent-sdk/src/shared/runtimeLog.ts
  */
+import { apiClientConfig, apiClientConfigVersion } from '../config.js';
 const SEVERITY = {
     debug: 0,
     info: 1,
@@ -11,12 +12,7 @@ const SEVERITY = {
     error: 3,
 };
 function parseThreshold() {
-    if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
-        return SEVERITY.debug;
-    }
-    const raw = (process.env.LOG_LEVEL ||
-        process.env.AGENTPLUS_LOG_LEVEL ||
-        'info').toLowerCase();
+    const raw = (apiClientConfig().logLevel || 'info').toLowerCase();
     if (raw === 'silent' || raw === 'none')
         return SEVERITY.error;
     if (raw === 'debug' || raw === 'trace')
@@ -28,13 +24,20 @@ function parseThreshold() {
     return SEVERITY.info;
 }
 let cachedThreshold = null;
+let cachedVersion = -1;
 function threshold() {
-    if (cachedThreshold === null)
+    // Recompute when the host reconfigures, so a `configureApiClient` call after
+    // the first log line still takes effect.
+    const v = apiClientConfigVersion();
+    if (cachedThreshold === null || cachedVersion !== v) {
         cachedThreshold = parseThreshold();
+        cachedVersion = v;
+    }
     return cachedThreshold;
 }
 export function resetRuntimeLogLevelCache() {
     cachedThreshold = null;
+    cachedVersion = -1;
 }
 function shouldEmit(level) {
     return SEVERITY[level] >= threshold();

package/dist/types.d.ts

@@ -269,3 +269,155 @@ export interface MessageMetadata {
     sentTimestamp?: string;
 }
 export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;
+/**
+ * What a delivery can be about. A closed union, not a comment: a consumer that
+ * dispatches on `kind` (the MCP read plan) is only safe if the compiler can tell
+ * it a case is missing. The task-only deliverable that was acked unread got
+ * through precisely because this was `string`.
+ *
+ * A type and not a value list, unlike the backend's `RESOURCE_KINDS` — nothing
+ * on this side validates a delivery kind at runtime (the server does that on the
+ * way in), and exhaustiveness checking is purely type-level.
+ */
+export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'quest';
+/**
+ * One thing addressed to this agent. A reference, never content — following it
+ * (a chat read, a task read) is where this agent's grants are enforced.
+ */
+export interface InboxDeliveryRef {
+    kind: InboxDeliveryKind;
+    resourceId: string;
+    chatId: string | null;
+    agreementId: string | null;
+    taskId: string | null;
+    /** Who wrote it. Never this agent — you are not woken by your own writes. */
+    actorId: string | null;
+    ts: string;
+    /**
+     * ZIG-703 — lifecycle hint when the server includes one (e.g.
+     * `connection_request_fulfilled`). Absent on ordinary doorbells / older servers.
+     */
+    reason?: string | null;
+    /** ZIG-703 — MCP connection after a fulfilled first-hop request. */
+    connectionId?: string | null;
+    /** ZIG-703 — grant minted for this agent on fulfill. */
+    grantId?: string | null;
+}
+/** Message/artifact deliveries folded by chat, so you can open chats directly. */
+export interface InboxChatNews {
+    chatId: string;
+    count: number;
+    latestAt: string;
+}
+export interface InboxProposalRef {
+    agreementId: string;
+    title: string;
+    proposedAt: string | null;
+    /**
+     * ZIG-1087 — party ids still owing a decision, and the named responder slot.
+     * The inbox lists proposals awaiting the agent OR its human, and only the
+     * agent's own slot is one it can submit; these say which is which.
+     *
+     * Optional because a backend deployed before ZIG-1087 omits them, and this
+     * client is installed independently of the server it talks to. Absent reads
+     * as "no slot of mine", which routes the decision to the human — the safe
+     * direction: it withholds a call, it never invents authority.
+     */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
+}
+export interface InboxConnectionRequestRef {
+    requestId: string;
+    /**
+     * Non-addressable persona reference for the requester (`psn_*`).
+     * Never use as an account id for lookup / wake / pay (ZIG-1137).
+     */
+    requesterRef: string;
+    /** ZIG-1039 — human-readable name for consent cards. */
+    requesterDisplayName?: string | null;
+    /** ZIG-1039 — org label for consent cards. */
+    requesterOrgName?: string | null;
+    message: string | null;
+    requestedAt: string | null;
+    /** ZIG-1087 — see InboxProposalRef; a link request uses the same gate. */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
+}
+/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482 / ZIG-481). */
+export interface InboxHumanAttention {
+    required: true;
+    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'multiple';
+    proposalCount: number;
+    truncatedProposals: number;
+    connectionRequestCount: number;
+    truncatedConnectionRequests: number;
+    promptUser: string;
+}
+/**
+ * An open task assigned to this agent (ZIG-973). References only — read the
+ * task for its description/plan/inputs.
+ *
+ * Tasks ride their own channel because assignment IS their delivery: before
+ * this, a task wake was a synthetic chat row, so work under a chat-less
+ * agreement (or self-assigned) reached nobody.
+ */
+export interface InboxTaskRef {
+    taskId: string;
+    agreementId: string | null;
+    title: string;
+    state: string;
+    updatedAt: string | null;
+}
+/**
+ * A marketplace quest doorbell (ZIG-1185). Own channel so the host can
+ * exact-match triage with zero LLM tokens before any wake.
+ */
+export interface InboxQuestRef {
+    agreementId: string;
+    /** Exact-match string from the publisher — compare to the agent's tags. */
+    match: string;
+    title: string;
+    ts: string;
+}
+export interface InboxEnvelope {
+    asOf: string;
+    /**
+     * Unacked deliveries addressed to this agent, newest first. This IS the
+     * inbox — read straight out of the delivery log, not derived from grants.
+     */
+    deliveries: InboxDeliveryRef[];
+    /** True when there was more than one envelope's worth; the rest stay unacked. */
+    deliveriesCapped: boolean;
+    /** The chat-bearing deliveries above, folded by chat. */
+    chats: InboxChatNews[];
+    /**
+     * Pass to `ack()` after acting. Null when there is nothing to ack. Ack after
+     * acting, not after reading: a crash in between redelivers.
+     */
+    ackTo: string | null;
+    /** Open tasks assigned to this agent — the work channel (ZIG-973). */
+    tasksAwaitingMe: InboxTaskRef[];
+    truncatedTasks: number;
+    /** Unacked quest deliveries (ZIG-1185) — triaged before any LLM wake. */
+    questsAwaitingMe?: InboxQuestRef[];
+    truncatedQuests?: number;
+    proposalsAwaitingMe: InboxProposalRef[];
+    truncatedProposals: number;
+    connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
+    truncatedConnectionRequests: number;
+    humanAttention?: InboxHumanAttention;
+}
+export interface InboxAckResult {
+    /** Where the watermark now sits. Monotonic — a rewind is a no-op, not an error. */
+    ackedUpTo: string | null;
+}
+/**
+ * Long-poll option shared by the inbox reads. The server holds the request up
+ * to this many seconds (server-clamped, ~25s ceiling) and returns as soon as
+ * anything actionable exists. Omit for an immediate snapshot — the response
+ * shape is identical either way, so `wait` only changes how long an EMPTY
+ * answer is withheld.
+ */
+export interface InboxReadOptions {
+    waitSeconds?: number;
+}

package/dist/utils/urlUtils.js

@@ -1,8 +1,9 @@
+import { apiClientConfig } from '../config.js';
 export function getBackendUrl() {
-    const url = process.env.HTTP_URL || 'https://api.ziggsai.com';
+    const url = apiClientConfig().httpUrl || 'https://api.ziggsai.com';
     return url.startsWith('http') ? url : `https://${url}`;
 }
 export function getWebSocketUrl() {
-    const wsUrl = process.env.WS_URL || 'wss://api.ziggsai.com';
+    const wsUrl = apiClientConfig().wsUrl || 'wss://api.ziggsai.com';
     return wsUrl.startsWith('ws') ? wsUrl : `wss://${wsUrl}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,6 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "dotenv": "^17.2.3",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [