@ziggs-ai/api-client 0.4.0 → 0.6.0

package/dist/http/InboxClient.d.ts

@@ -1,28 +1,24 @@
 import 'dotenv/config';
-export type InboxScopeKind = 'chat' | 'agreement' | 'org';
 /**
- * ZIG-543: which chats a multi-chat scope's news is in. Lets a scope-granted
- * agent open the conversations behind the count (e.g. GET /chats/:chatId/messages).
+ * 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 InboxScopeChat {
-    chatId: string;
-    newMessages: number;
-    newArtifacts: number;
-    latestAt: string | null;
+export interface InboxDeliveryRef {
+    /** 'message' | 'artifact' | 'task-state' | 'agreement'. */
+    kind: string;
+    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;
 }
-export interface InboxScopeEntry {
-    scope: {
-        kind: InboxScopeKind;
-        id: string;
-    };
-    newMessages: number;
-    newArtifacts: number;
-    latestAt: string | null;
-    since: string;
-    /** Per-chat breakdown for org / agreement scopes (ZIG-543). Absent for a chat scope. */
-    chats?: InboxScopeChat[];
-    /** Chats with news beyond the per-scope cap, not listed in `chats`. */
-    truncatedChats?: number;
+/** 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;
@@ -35,54 +31,59 @@ 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' | 'mcp_server_requests_awaiting_me' | 'multiple';
+    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'multiple';
     proposalCount: number;
     truncatedProposals: number;
     connectionRequestCount: number;
     truncatedConnectionRequests: number;
-    mcpServerRequestCount: number;
-    truncatedMcpServerRequests: 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;
-    scopes: InboxScopeEntry[];
-    truncatedScopes: number;
-    countCap: number;
+    /**
+     * 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;
-    /** Agent requests to connect an MCP server awaiting the user (ZIG-686). */
-    mcpServerRequestsAwaitingMe: InboxMcpServerRequestRef[];
-    truncatedMcpServerRequests: number;
     humanAttention?: InboxHumanAttention;
 }
-export interface InboxAck {
-    kind: InboxScopeKind;
-    id: string;
-    upTo: string;
-}
 export interface InboxAckResult {
-    acked: Array<{
-        scope: {
-            kind: InboxScopeKind;
-            id: string;
-        };
-        ackedUpTo: string;
-    }>;
+    /** 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
@@ -93,27 +94,50 @@ export interface InboxAckResult {
  */
 export interface InboxReadOptions {
     waitSeconds?: number;
+    /**
+     * Operator read only (ZIG-965): restrict the sweep to this roster. The
+     * server intersects it with the agents the key owner runs — it narrows,
+     * never widens. A launcher hosting a subset should always pass the agents
+     * it actually registered, or it pays for a sweep of the owner's whole
+     * seeded fleet.
+     */
+    agents?: string[];
 }
-/** One agent's slice of the operator-level multiplexed read. */
+/**
+ * One agent's line in the operator sweep: enough to decide whether to start a
+ * host, and nothing more.
+ *
+ * Deliberately NOT that agent's envelope. The launcher only chooses who to
+ * run; the host it starts reads its own inbox on its own credentials a moment
+ * later, so building N envelopes here was work thrown away.
+ */
 export interface InboxOperatorAgentEntry {
     agentId: string;
-    /** That agent's own inbox — fenced to its grants, floored by its cursors. */
-    inbox: InboxEnvelope;
+    /** Newest delivery addressed to this agent, or null if it never had one. */
+    deliveredUpTo: string | null;
+    /** How far it has acked. Mail exists when `deliveredUpTo > ackedUpTo`. */
+    ackedUpTo: string | null;
+    /**
+     * True when this agent holds open assigned work. Independent of the
+     * watermark: a host that died mid-task already acked past the task's
+     * delivery, and the open task is the only durable trace it needs restarting.
+     */
+    hasOpenTasks: boolean;
 }
-/** GET /inbox/operator: one poll across every agent the key's owner runs. */
+/** GET /inbox/operator: which of the key owner's agents have mail or open work. */
 export interface InboxOperatorEnvelope {
     asOf: string;
-    /** Agents with actionable content only. */
+    /** Agents with mail or open work. */
     agents: InboxOperatorAgentEntry[];
-    /** Agents examined whose inboxes were empty. */
+    /** Agents examined that had neither. */
     idleAgents: number;
     /** Owned agents beyond the server's per-pass cap — not examined. */
     truncatedAgents: number;
 }
 /**
- * The doorbell, not the door (ZIG-434): references and counts since the
- * agent's last ack — never content. Flow: inbox → read → act → ack (ZIG-446).
- * Wraps `GET /inbox` and `POST /inbox/ack`.
+ * The doorbell, not the door (ZIG-434): references addressed to this agent
+ * since its last ack — never content. Flow: inbox → read → act → ack
+ * (ZIG-446). Wraps `GET /inbox` and `POST /inbox/ack`.
  */
 export declare class InboxClient {
     private readonly operatorKey;
@@ -128,11 +152,17 @@ export declare class InboxClient {
     private inboxUrl;
     getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;
     /**
-     * Operator-level multiplexed read: one poll for every agent this key's
-     * owner runs, each slice fenced to its own agent (an agent-scoped key
-     * collapses to its one agent). Ack stays per agent — use a per-agent
-     * client's `ack()` after acting on that agent's slice.
+     * Operator-level multiplexed read: which of this key owner's agents have
+     * mail or open work (an agent-scoped key collapses to its one agent).
+     *
+     * Returns who to start, never what they were sent — the host you start
+     * reads its own inbox on its own identity. Ack stays per agent.
      */
     getOperatorInbox(opts?: InboxReadOptions): Promise<InboxOperatorEnvelope>;
-    ack(scopes: InboxAck[]): Promise<InboxAckResult>;
+    /**
+     * Advance this agent's watermark — pass the envelope's `ackTo`. Monotonic
+     * server-side: an older value is a no-op, so a replayed ack can never
+     * redeliver handled work.
+     */
+    ack(upTo: string): Promise<InboxAckResult>;
 }

package/dist/http/InboxClient.js

@@ -1,9 +1,10 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { pollSurfaceError } from '../shared/rateLimit.js';
 /**
- * The doorbell, not the door (ZIG-434): references and counts since the
- * agent's last ack — never content. Flow: inbox → read → act → ack (ZIG-446).
- * Wraps `GET /inbox` and `POST /inbox/ack`.
+ * The doorbell, not the door (ZIG-434): references addressed to this agent
+ * since its last ack — never content. Flow: inbox → read → act → ack
+ * (ZIG-446). Wraps `GET /inbox` and `POST /inbox/ack`.
  */
 export class InboxClient {
     operatorKey;
@@ -34,6 +35,9 @@ export class InboxClient {
         if (opts.waitSeconds != null && opts.waitSeconds > 0) {
             url.searchParams.set('wait', String(opts.waitSeconds));
         }
+        if (opts.agents?.length) {
+            url.searchParams.set('agents', opts.agents.join(','));
+        }
         return url.toString();
     }
     async getInbox(opts = {}) {
@@ -42,37 +46,62 @@ export class InboxClient {
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.getInbox ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.getInbox', res, body);
         }
         return JSON.parse(body);
     }
     /**
-     * Operator-level multiplexed read: one poll for every agent this key's
-     * owner runs, each slice fenced to its own agent (an agent-scoped key
-     * collapses to its one agent). Ack stays per agent — use a per-agent
-     * client's `ack()` after acting on that agent's slice.
+     * Operator-level multiplexed read: which of this key owner's agents have
+     * mail or open work (an agent-scoped key collapses to its one agent).
+     *
+     * Returns who to start, never what they were sent — the host you start
+     * reads its own inbox on its own identity. Ack stays per agent.
      */
     async getOperatorInbox(opts = {}) {
-        const res = await fetch(this.inboxUrl('/inbox/operator', opts), {
-            headers: this.headers(),
-        });
+        // Bounded wait (ZIG-965): the server holds at most `waitSeconds` (+ sweep
+        // time); a poll that outlives that by a wide margin is a dead sweep, and
+        // without a timeout it blocked the launcher's whole poll loop — lazy wake
+        // simply stopped. Abort and let the caller's retry loop take over.
+        const timeoutMs = ((opts.waitSeconds ?? 0) + 30) * 1000;
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(this.inboxUrl('/inbox/operator', opts), {
+                headers: this.headers(),
+                signal: ac.signal,
+            });
+        }
+        catch (err) {
+            throw ac.signal.aborted
+                ? new Error(`InboxClient.getOperatorInbox timed out after ${timeoutMs}ms`)
+                : err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.getOperatorInbox ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.getOperatorInbox', res, body);
         }
         return JSON.parse(body);
     }
-    async ack(scopes) {
-        if (!scopes.length)
-            throw new Error('InboxClient.ack: scopes are required');
+    /**
+     * Advance this agent's watermark — pass the envelope's `ackTo`. Monotonic
+     * server-side: an older value is a no-op, so a replayed ack can never
+     * redeliver handled work.
+     */
+    async ack(upTo) {
+        if (!upTo)
+            throw new Error('InboxClient.ack: upTo is required');
         const res = await fetch(`${this.baseUrl}/inbox/ack`, {
             method: 'POST',
             headers: this.headers(),
-            body: JSON.stringify({ scopes }),
+            body: JSON.stringify({ upTo }),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`InboxClient.ack ${res.status} ${body.slice(0, 200)}`);
+            throw pollSurfaceError('InboxClient.ack', res, body);
         }
         return JSON.parse(body);
     }

package/dist/http/MarketplaceClient.d.ts

@@ -8,6 +8,12 @@ export interface PublishOfferPayload {
     maxExecutions?: number;
     /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
     engagementKind?: 'hire' | 'service';
+    /**
+     * How `price` reads. `total` (default) is one price for the whole engagement,
+     * escrowed on claim and paid at fulfillment; `per_task` is a RATE settled as
+     * each task completes (open/standing only; the default for a hire).
+     */
+    billing?: 'total' | 'per_task';
     /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
     audience?: BroadcastAudience;
     metadata?: Record<string, unknown>;
@@ -20,6 +26,8 @@ export interface PullOffersOptions {
 export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare function claimOffer(agreementId: string, creds: Creds): Promise<Agreement>;
 export interface PublishQuestPayload {
+    /** See PublishOfferPayload.billing. */
+    billing?: 'total' | 'per_task';
     description: string;
     chatId?: string;
     payerId?: string;

package/dist/http/agreementFlows.d.ts

@@ -0,0 +1,34 @@
+import { type ProposeTerms } from './AgreementClient.js';
+import { type Agreement, type Creds, type EngagementKind } from '../types.js';
+/**
+ * ZIG-1022 — one propose grammar. Direct, broadcast (quest and standing
+ * offer), and link proposals all flow through here; the surfaces expose a
+ * single propose tool instead of dedicated publish/request tools.
+ *
+ * Routing:
+ * - engagementKind 'link'                    → POST /agreements (link proposal / open invite)
+ * - proposedTo 'everyone' | 'org', providerId = self  → seller-broadcast standing offer
+ * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast quest
+ * - anything else                            → direct proposal
+ */
+export interface UnifiedProposeInput extends ProposeTerms {
+    proposedTo: string;
+    /** Required on direct proposals; optional on broadcasts/links. */
+    chatId?: string;
+    engagementKind?: EngagementKind;
+}
+export type ProposeShape = 'direct' | 'quest' | 'offer' | 'link';
+export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds): Promise<{
+    agreement: Agreement;
+    shape: ProposeShape;
+}>;
+export type ClaimedKind = 'link' | 'offer' | 'quest';
+/**
+ * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
+ * route: link invites and quests claim through POST /agreements/:id/claim;
+ * standing offers (open payer side) through POST /marketplace/offers/claim.
+ */
+export declare function claimOpenAgreement(agreementId: string, creds: Creds): Promise<{
+    agreement: Agreement;
+    kind: ClaimedKind;
+}>;

package/dist/http/agreementFlows.js

@@ -0,0 +1,80 @@
+import { createAgreement, claimAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { claimOffer, publishOffer } from './MarketplaceClient.js';
+import { isBroadcastTarget, } from '../types.js';
+export async function proposeUnified(input, creds) {
+    const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
+    if (!proposedTo)
+        throw new Error('proposedTo is required (a user/agent id, or "everyone"/"org" to broadcast)');
+    if (engagementKind === 'link') {
+        // A link is an agreement, proposed to one agent (providerId) or opened as
+        // an invite (proposedTo 'everyone'); no chat, no money.
+        const target = isBroadcastTarget(proposedTo) ? undefined : proposedTo;
+        const { agreement } = await createAgreement({
+            engagementKind: 'link',
+            ...(target ? { providerId: target } : {}),
+            ...(terms.description ? { description: terms.description } : {}),
+        }, creds);
+        return { agreement, shape: 'link' };
+    }
+    if (isBroadcastTarget(proposedTo)) {
+        const audience = proposedTo;
+        if (providerId && creds.agentId && providerId === creds.agentId) {
+            // Seller-broadcast: you work, the claimer pays — a standing offer.
+            const agreement = await publishOffer({
+                description: terms.description ?? '',
+                price: terms.price,
+                lifecycle: terms.lifecycle,
+                expiresAt: terms.expiresAt,
+                maxExecutions: terms.maxExecutions,
+                engagementKind: engagementKind,
+                billing: terms.billing,
+                audience,
+            }, creds);
+            return { agreement, shape: 'offer' };
+        }
+        if (providerId) {
+            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a quest: the claimer works, you pay). A third-party providerId is not broadcastable.');
+        }
+        // Buyer-broadcast: the claimer works, your side pays — an open quest.
+        const agreement = await proposeBroadcast({
+            ...terms,
+            chatId: chatId ?? '',
+            engagementKind: engagementKind ?? 'service',
+            audience,
+        }, creds);
+        return { agreement, shape: 'quest' };
+    }
+    if (!chatId)
+        throw new Error('chatId is required on a direct proposal');
+    const agreement = await proposeDirectTo({
+        ...terms,
+        proposedTo,
+        chatId,
+        providerId: providerId?.trim() || proposedTo,
+        engagementKind: engagementKind ?? 'service',
+    }, creds);
+    return { agreement, shape: 'direct' };
+}
+/**
+ * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
+ * route: link invites and quests claim through POST /agreements/:id/claim;
+ * standing offers (open payer side) through POST /marketplace/offers/claim.
+ */
+export async function claimOpenAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required');
+    const existing = await getAgreement(agreementId, creds);
+    if (!existing)
+        throw new Error(`Agreement not found: ${agreementId}`);
+    if (existing.engagementKind === 'link') {
+        const { agreement } = await claimAgreement(agreementId, creds);
+        return { agreement, kind: 'link' };
+    }
+    if (isBroadcastTarget(existing.parties?.payer)) {
+        // Seller-broadcast standing offer: the open side is the payer — you buy.
+        const agreement = await claimOffer(agreementId, creds);
+        return { agreement, kind: 'offer' };
+    }
+    const { agreement } = await claimAgreement(agreementId, creds);
+    return { agreement, kind: 'quest' };
+}

package/dist/http/index.d.ts

@@ -1,6 +1,7 @@
 export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
+export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
@@ -25,4 +26,4 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxMcpServerRequestRef, InboxHumanAttention, InboxEnvelope, InboxAck, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';
+export type { InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';

package/dist/http/index.js

@@ -1,6 +1,7 @@
 export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
+export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient } from './ArtifactsClient.js';

package/dist/index.d.ts

@@ -2,8 +2,10 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
+export type { StartAgentOptions } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -5,3 +5,5 @@ export { ConnectionManager } from './ConnectionManager.js';
 export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
+// ZIG-1019: retry loops need the server's own wait, not a guess.
+export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';

package/dist/shared/rateLimit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
+ * deadline attached.
+ *
+ * The poll surface (`/inbox`, `/context/read`) is capped per actor, and every
+ * refused call still counts against that cap. A caller that retries on the
+ * usual exponential ladder (1s, 2s, 4s…) therefore spends its way deeper into
+ * the hole: observed live as an agent that could not read the conversation it
+ * had just been woken for, because its own retries kept the bucket empty.
+ *
+ * The server already says exactly how long to wait — `Retry-After`, or
+ * `RateLimit-Reset` from the standard headers. These helpers carry that number
+ * to whoever is doing the backing off.
+ */
+/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
+export declare class RateLimitedError extends Error {
+    readonly status = 429;
+    /** How long the server said to wait. Null when it said nothing. */
+    readonly retryAfterMs: number | null;
+    constructor(message: string, retryAfterMs: number | null);
+}
+/** True for the error above — survives structured clones and re-wraps. */
+export declare function isRateLimited(err: unknown): err is {
+    retryAfterMs: number | null;
+};
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ */
+export declare function parseRetryAfterMs(headers: {
+    get(name: string): string | null;
+}): number | null;
+/**
+ * Build the error for a failed poll-surface response: 429s carry the server's
+ * wait, everything else stays an ordinary Error so existing handling is
+ * unchanged.
+ */
+export declare function pollSurfaceError(label: string, res: {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}, body: string): Error;

package/dist/shared/rateLimit.js

@@ -0,0 +1,73 @@
+/**
+ * ZIG-1019 — a 429 is not a generic failure, it is an instruction with a
+ * deadline attached.
+ *
+ * The poll surface (`/inbox`, `/context/read`) is capped per actor, and every
+ * refused call still counts against that cap. A caller that retries on the
+ * usual exponential ladder (1s, 2s, 4s…) therefore spends its way deeper into
+ * the hole: observed live as an agent that could not read the conversation it
+ * had just been woken for, because its own retries kept the bucket empty.
+ *
+ * The server already says exactly how long to wait — `Retry-After`, or
+ * `RateLimit-Reset` from the standard headers. These helpers carry that number
+ * to whoever is doing the backing off.
+ */
+/** Thrown for HTTP 429 so a retry loop can wait the server's number, not its own. */
+export class RateLimitedError extends Error {
+    status = 429;
+    /** How long the server said to wait. Null when it said nothing. */
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = 'RateLimitedError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** True for the error above — survives structured clones and re-wraps. */
+export function isRateLimited(err) {
+    return (!!err &&
+        typeof err === 'object' &&
+        err.status === 429);
+}
+const MAX_RETRY_AFTER_MS = 120_000;
+/**
+ * Read the wait out of a 429 response. `Retry-After` wins (it is the explicit
+ * one) and is accepted in both forms — delta-seconds or an HTTP date;
+ * `RateLimit-Reset` is the standard-headers fallback, in seconds. Capped so a
+ * bad header cannot park a loop for an hour, floored at a second so a `0` does
+ * not reproduce the hot-retry it is meant to stop.
+ */
+export function parseRetryAfterMs(headers) {
+    const explicit = headers.get('retry-after');
+    if (explicit) {
+        const seconds = Number(explicit);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+        const at = Date.parse(explicit);
+        if (!Number.isNaN(at))
+            return clampRetryMs(at - Date.now());
+    }
+    const reset = headers.get('ratelimit-reset');
+    if (reset) {
+        const seconds = Number(reset);
+        if (Number.isFinite(seconds))
+            return clampRetryMs(seconds * 1000);
+    }
+    return null;
+}
+function clampRetryMs(ms) {
+    if (!Number.isFinite(ms))
+        return 1_000;
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, Math.round(ms)));
+}
+/**
+ * Build the error for a failed poll-surface response: 429s carry the server's
+ * wait, everything else stays an ordinary Error so existing handling is
+ * unchanged.
+ */
+export function pollSurfaceError(label, res, body) {
+    const message = `${label} ${res.status} ${body.slice(0, 200)}`;
+    if (res.status !== 429)
+        return new Error(message);
+    return new RateLimitedError(message, parseRetryAfterMs(res.headers));
+}

package/dist/types.d.ts

@@ -102,6 +102,17 @@ export interface Agreement {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /**
+     * Seat bookkeeping when this agreement is an open link invite. Each claim
+     * takes a seat and mints its own child link, so one shared link produces N
+     * separate connections rather than a group.
+     */
+    linkInvite?: {
+        maxClaims?: number;
+        claimsUsed?: number;
+    } | null;
+    /** Set on a link that was formed by claiming the invite with this id. */
+    linkInviteTemplateId?: string | null;
     metadata?: Record<string, unknown>;
     createdAt?: string;
     updatedAt?: string;
@@ -165,7 +176,7 @@ export interface MessageMetadata {
      * `task.notify.chat` / `agreement.notify.direct` traffic. The agent SDK's
      * `normalizeIncomingEvent` reads `metadata.task` to upgrade structured
      * task notifications into `task_result` events (so executors see
-     * `task-assigned` outcomes when the orchestrator calls `task_spawn`),
+     * `task-assigned` outcomes when the orchestrator calls `task_create`),
      * and maps explicit wire `operation` + `agreementId` lifecycle fields
      * into `agreement_lifecycle` events for proposal approve/reject.
      */

package/package.json

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