@ziggs-ai/api-client 0.1.19 → 0.1.21

package/dist/http/AgentSearchClient.d.ts

@@ -34,9 +34,13 @@ export interface AgentProfile {
 }
 export declare class AgentSearchClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     searchAgents(query: string, options?: AgentSearchOptions): Promise<AgentSearchResult>;
     getAgentById(agentId: string): Promise<AgentSearchResult & Partial<AgentProfile>>;
     private _buildHeaders;

package/dist/http/AgentSearchClient.js

@@ -1,15 +1,18 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export class AgentSearchClient {
     operatorKey;
     agentId;
     baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('AgentSearchClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('AgentSearchClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = getBackendUrl();
@@ -63,10 +66,8 @@ export class AgentSearchClient {
         }
     }
     _buildHeaders() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/AgreementClient.d.ts

@@ -176,7 +176,11 @@ export declare function linkUserToAgreement(agreementId: string, userId: string,
 export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare class AgreementClient {
     private creds;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     propose(data: ProposeDirectInput): Promise<Agreement>;
     proposeDirect(data: ProposeDirectInput): Promise<Agreement>;
     proposeBroadcast(data: ProposeBroadcastInput): Promise<Agreement>;

package/dist/http/AgreementClient.js

@@ -551,11 +551,15 @@ export async function getUsersForAgreement(agreementId, creds) {
 }
 export class AgreementClient {
     creds;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('AgreementClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('AgreementClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     propose(data) { return proposeAgreement(data, this.creds); }

package/dist/http/ArtifactsClient.d.ts

@@ -31,8 +31,12 @@ export interface WriteArtifactInput {
  */
 export declare class ArtifactsClient {
     private readonly operatorKey;
-    private readonly agentId;
-    constructor(operatorKey: string, agentId: string);
+    private readonly agentId?;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the

package/dist/http/ArtifactsClient.js

@@ -1,6 +1,7 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
@@ -9,11 +10,13 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 export class ArtifactsClient {
     operatorKey;
     agentId;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('ArtifactsClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ArtifactsClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
     }
@@ -81,10 +84,8 @@ export class ArtifactsClient {
         }
     }
     _headers() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'content-type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/ChatClient.d.ts

@@ -70,7 +70,11 @@ export declare function sendChatMessage(input: SendChatMessageInput, creds: Cred
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;
 export declare class ChatClient {
     private creds;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @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<{
         chatId: string;
     }>;

package/dist/http/ChatClient.js

@@ -132,11 +132,15 @@ export async function listMyChats(creds) {
 }
 export class ChatClient {
     creds;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('ChatClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ChatClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     open(participantId) { return openConversation(participantId, this.creds); }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -16,8 +16,12 @@ export interface ContextReachDescriptor {
  */
 export declare class ContextDiscoveryClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId: string, baseUrl?: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     discover(): Promise<ContextReachDescriptor[]>;
 }

package/dist/http/ContextDiscoveryClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * ZIG-412 discovery — scope descriptors only, no content.
  */
@@ -7,23 +8,21 @@ export class ContextDiscoveryClient {
     operatorKey;
     agentId;
     baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId, baseUrl) {
         if (!operatorKey) {
             throw new Error('ContextDiscoveryClient: operatorKey is required');
         }
-        if (!agentId) {
-            throw new Error('ContextDiscoveryClient: agentId is required (operator-token impersonation)');
-        }
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
     async discover() {
         const res = await fetch(`${this.baseUrl}/context/discovery`, {
-            headers: {
-                Authorization: `Bearer ${this.operatorKey}`,
-                'X-Agent-Id': this.agentId,
-            },
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {

package/dist/http/ContextGrantsClient.d.ts

@@ -36,9 +36,13 @@ export interface DelegateContextGrantInput {
  */
 export declare class ContextGrantsClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId: string, baseUrl?: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     issueGrant(input: IssueContextGrantInput): Promise<ContextGrantRecord>;
     delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<ContextGrantRecord>;
     revokeGrant(grantId: string): Promise<{

package/dist/http/ContextGrantsClient.js

@@ -1,19 +1,7 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { ApiError } from '../types.js';
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-    };
-}
-function assertCreds(creds, op) {
-    if (!creds?.operatorKey)
-        throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
-        throw new Error(`agentId is required for ${op}`);
-}
+import { buildOperatorHeaders } from './operatorHeaders.js';
 function throwApiError(response, responseBody, defaultMessage) {
     let message = defaultMessage;
     if (responseBody) {
@@ -38,24 +26,23 @@ export class ContextGrantsClient {
     operatorKey;
     agentId;
     baseUrl;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId, baseUrl) {
         if (!operatorKey) {
             throw new Error('ContextGrantsClient: operatorKey is required');
         }
-        if (!agentId) {
-            throw new Error('ContextGrantsClient: agentId is required (operator-token impersonation)');
-        }
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
     async issueGrant(input) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'issueGrant');
         const res = await fetch(`${this.baseUrl}/context/grants`, {
             method: 'POST',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
             body: JSON.stringify({
                 holderId: input.holderId,
@@ -75,12 +62,10 @@ export class ContextGrantsClient {
         return parsed.grant;
     }
     async delegateGrant(parentGrantId, input) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'delegateGrant');
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(parentGrantId)}/delegate`, {
             method: 'POST',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
             body: JSON.stringify(input),
         });
@@ -95,12 +80,10 @@ export class ContextGrantsClient {
         return parsed.grant;
     }
     async revokeGrant(grantId) {
-        assertCreds({ operatorKey: this.operatorKey, agentId: this.agentId }, 'revokeGrant');
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {
             method: 'DELETE',
-            headers: buildHeaders({
-                operatorKey: this.operatorKey,
-                agentId: this.agentId,
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
             }),
         });
         const body = await res.text().catch(() => '');

package/dist/http/InboxClient.d.ts

@@ -35,14 +35,25 @@ export interface InboxConnectionRequestRef {
     message: string | null;
     requestedAt: string | null;
 }
+/** Agent asking its principal to connect an MCP server + grant tools (ZIG-686). */
+export interface InboxMcpServerRequestRef {
+    requestId: string;
+    requesterAgentId: string;
+    serverUrl: string;
+    tools: string[];
+    reason: string | null;
+    requestedAt: 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';
+    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'mcp_server_requests_awaiting_me' | 'multiple';
     proposalCount: number;
     truncatedProposals: number;
     connectionRequestCount: number;
     truncatedConnectionRequests: number;
+    mcpServerRequestCount: number;
+    truncatedMcpServerRequests: number;
     promptUser: string;
 }
 export interface InboxEnvelope {
@@ -54,6 +65,9 @@ export interface InboxEnvelope {
     truncatedProposals: number;
     connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
     truncatedConnectionRequests: number;
+    /** Agent requests to connect an MCP server awaiting the user (ZIG-686). */
+    mcpServerRequestsAwaitingMe: InboxMcpServerRequestRef[];
+    truncatedMcpServerRequests: number;
     humanAttention?: InboxHumanAttention;
 }
 export interface InboxAck {

package/dist/http/MarketplaceClient.d.ts

@@ -40,7 +40,11 @@ export interface PullQuestsOptions {
 export declare function pullQuests(options: PullQuestsOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare class MarketplaceClient {
     private creds;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
     claimOffer(agreementId: string): Promise<Agreement>;

package/dist/http/MarketplaceClient.js

@@ -112,11 +112,15 @@ export async function pullQuests(options, creds) {
 }
 export class MarketplaceClient {
     creds;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('MarketplaceClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('MarketplaceClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     publishOffer(payload) { return publishOffer(payload, this.creds); }

package/dist/http/ScopeClient.d.ts

@@ -26,8 +26,12 @@ export interface ScopeResult {
  */
 export declare class ScopeClient {
     private readonly operatorKey;
-    private readonly agentId;
-    constructor(operatorKey: string, agentId: string);
+    private readonly agentId?;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     get(kind: ScopeKind, id: string): Promise<ScopeResult>;
     private _headers;
 }

package/dist/http/ScopeClient.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * Client for `GET /scope?via=<kind>:<id>`. Returns the access graph reachable
  * from an entry point for the impersonated agent. Used by `runTurn` to
@@ -9,11 +10,13 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 export class ScopeClient {
     operatorKey;
     agentId;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('ScopeClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('ScopeClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
     }
@@ -30,10 +33,8 @@ export class ScopeClient {
         return (await res.json());
     }
     _headers() {
-        return {
+        return buildOperatorHeaders(this.operatorKey, this.agentId, {
             'content-type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
-        };
+        });
     }
 }

package/dist/http/TaskClient.d.ts

@@ -50,7 +50,11 @@ export interface CountTasksFilters {
 export declare function countTasks(filters: CountTasksFilters | undefined, creds: Creds): Promise<number>;
 export declare class TaskClient {
     private creds;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     createTask(data: CreateTaskData): Promise<Task>;
     getTask(taskId: string): Promise<Task>;
     updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<Task>;

package/dist/http/TaskClient.js

@@ -303,11 +303,15 @@ export async function countTasks(filters = {}, creds) {
 // ---------------------------------------------------------------------------
 export class TaskClient {
     creds;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('TaskClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('TaskClient: agentId is required');
+        // agentId may be absent for agent-scoped keys (ZIG-642); the Creds-based
+        // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
     createTask(data) { return createTask(data, this.creds); }

package/dist/http/TelemetryClient.d.ts

@@ -1,10 +1,14 @@
 import 'dotenv/config';
 export declare class TelemetryClient {
     private readonly operatorKey;
-    private readonly agentId;
+    private readonly agentId?;
     private _queue;
     private _flushing;
-    constructor(operatorKey: string, agentId: string);
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
+    constructor(operatorKey: string, agentId?: string);
     send(payload: unknown): Promise<void>;
     private _flush;
     private _post;

package/dist/http/TelemetryClient.js

@@ -1,16 +1,19 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export class TelemetryClient {
     operatorKey;
     agentId;
     _queue;
     _flushing;
+    /**
+     * @param operatorKey Agent-scoped or fleet operator key.
+     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     */
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('TelemetryClient: operatorKey is required');
-        if (!agentId)
-            throw new Error('TelemetryClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this._queue = [];
@@ -34,11 +37,9 @@ export class TelemetryClient {
         try {
             const res = await fetch(url, {
                 method: 'POST',
-                headers: {
+                headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
                     'content-type': 'application/json',
-                    Authorization: `Bearer ${this.operatorKey}`,
-                    'X-Agent-Id': this.agentId,
-                },
+                }),
                 body: JSON.stringify({ payload }),
             });
             if (!res.ok) {

package/dist/http/index.d.ts

@@ -17,4 +17,4 @@ export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, Cont
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';
+export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxMcpServerRequestRef, InboxHumanAttention, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
+ * an agentId is present — agent-scoped keys identify the agent themselves;
+ * fleet keys must pass one (ZIG-642).
+ */
+export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>): Record<string, string>;

package/dist/http/operatorHeaders.js

@@ -0,0 +1,12 @@
+/**
+ * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
+ * an agentId is present — agent-scoped keys identify the agent themselves;
+ * fleet keys must pass one (ZIG-642).
+ */
+export function buildOperatorHeaders(operatorKey, agentId, extra) {
+    return {
+        Authorization: `Bearer ${operatorKey}`,
+        ...(agentId ? { 'X-Agent-Id': agentId } : {}),
+        ...extra,
+    };
+}

package/package.json

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