@ziggs-ai/api-client 0.4.0 → 0.5.0

package/dist/ConnectionManager.d.ts

@@ -1,6 +1,16 @@
 import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
+export interface StartAgentOptions {
+    /**
+     * Keep this host running until it is stopped explicitly — exempt from the
+     * idle sweep, last choice for LRU eviction. For agents the operator named
+     * (launcher `preStart` / `WAKE_AGENTS`): they were started because someone
+     * decided they must be up, not because work arrived, so "no work for a
+     * while" is not a reason to retire them.
+     */
+    pinned?: boolean;
+}
 export interface ConnectionManagerMeta {
     domain?: string;
     expertise?: string[];
@@ -46,6 +56,7 @@ export declare class ConnectionManager {
     private _active;
     private _meta;
     private _starting;
+    private _pinned;
     private _shouldLazyStart;
     constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
@@ -59,12 +70,13 @@ export declare class ConnectionManager {
      * the loop never exits until `stop()` (nothing to resynchronize).
      */
     private _runOperatorPoll;
-    startAgent(id: string): Promise<unknown>;
+    startAgent(id: string, { pinned }?: StartAgentOptions): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;
     touch(id: string): void;
     list(): string[];
     listActive(): string[];
+    listPinned(): string[];
     get size(): number;
     query({ domain, expertise, tags }?: QueryFilter): string[];
     getMeta(id: string): ConnectionManagerMeta | undefined;

package/dist/ConnectionManager.js

@@ -16,6 +16,7 @@ export class ConnectionManager {
     _active;
     _meta;
     _starting;
+    _pinned;
     _shouldLazyStart;
     constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
         this.maxActive = maxActive;
@@ -28,6 +29,7 @@ export class ConnectionManager {
         this._active = new Map();
         this._meta = new Map();
         this._starting = new Map();
+        this._pinned = new Set();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -68,7 +70,19 @@ export class ConnectionManager {
         let consecutiveErrors = 0;
         while (this._polling) {
             try {
-                const env = await inbox.getOperatorInbox({ waitSeconds: OPERATOR_POLL_WAIT_SECONDS });
+                // Roster scoping (ZIG-965): only agents this manager can actually
+                // start are worth sweeping server-side. Without it a partial launcher
+                // (ONLY_AGENTS) paid for a sweep of the owner's whole seeded fleet.
+                //
+                // Already-running agents are excluded: this loop's only job is
+                // lazy-start, and a running host polls its own inbox. Sending them
+                // made the server answer for agents whose entry we then discarded
+                // below — pure duplicate work, growing with how healthy the fleet is.
+                const startable = [...this._entries.keys()].filter((id) => !this._active.has(id));
+                const env = await inbox.getOperatorInbox({
+                    waitSeconds: OPERATOR_POLL_WAIT_SECONDS,
+                    agents: startable,
+                });
                 consecutiveErrors = 0;
                 for (const entry of env.agents) {
                     const id = entry.agentId;
@@ -92,7 +106,11 @@ export class ConnectionManager {
             }
         }
     }
-    async startAgent(id) {
+    async startAgent(id, { pinned = false } = {}) {
+        // Recorded before any await so a pin is never lost to a concurrent
+        // unpinned start of the same id.
+        if (pinned)
+            this._pinned.add(id);
         const existing = this._active.get(id);
         if (existing) {
             this._resetTimer(id);
@@ -136,6 +154,7 @@ export class ConnectionManager {
     touch(id) { this._resetTimer(id); }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }
+    listPinned() { return [...this._pinned]; }
     get size() { return this._entries.size; }
     query({ domain, expertise, tags } = {}) {
         const results = [];
@@ -156,6 +175,14 @@ export class ConnectionManager {
         if (!entry)
             return;
         clearTimeout(entry.timer);
+        // A pinned host has no idle timer at all. Empty polls don't count as
+        // activity (only delivered items call touch()), so a pinned agent nobody
+        // talks to would otherwise be swept — and with lazy start unable to keep
+        // up at fleet size, nothing brings it back until the process restarts.
+        if (this._pinned.has(id)) {
+            entry.timer = null;
+            return;
+        }
         entry.timer = setTimeout(() => {
             this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
         }, this.idleTimeoutMs);
@@ -168,13 +195,29 @@ export class ConnectionManager {
         this._scheduleIdle(id);
     }
     async _evictLRU() {
-        let oldest = null;
-        for (const [id, entry] of this._active) {
-            const oldestEntry = oldest ? this._active.get(oldest) : null;
-            if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
-                oldest = id;
+        // Pinned hosts are the last to go: pick the LRU unpinned one, and only
+        // fall back to a pinned one when every active host is pinned. maxActive
+        // stays a hard cap — a pin outranks other agents, not the capacity limit —
+        // but say so, because it means more agents were pinned than can run.
+        const oldestOf = (ids) => {
+            let oldest = null;
+            for (const id of ids) {
+                const entry = this._active.get(id);
+                const oldestEntry = oldest ? this._active.get(oldest) : null;
+                if (!entry)
+                    continue;
+                if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
+                    oldest = id;
+            }
+            return oldest;
+        };
+        const active = [...this._active.keys()];
+        const victim = oldestOf(active.filter(id => !this._pinned.has(id))) ?? oldestOf(active);
+        if (!victim)
+            return;
+        if (this._pinned.has(victim)) {
+            runtimeLog.warn('ConnectionManager', `evicting pinned "${victim}": all ${active.length} active hosts are pinned and maxActive=${this.maxActive} is reached — pin fewer agents or raise maxActive`);
         }
-        if (oldest)
-            await this.sleep(oldest);
+        await this.sleep(victim);
     }
 }

package/dist/capabilities/artifacts.js

@@ -34,8 +34,11 @@ export const recordArtifactCapability = {
             enum: ['chat', 'agent-private'],
             description: 'chat = visible to scope parties; agent-private = your eyes only',
         },
-        chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
-        agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
+        chatId: { type: 'string', description: 'Target chat scope' },
+        agreementId: {
+            type: 'string',
+            description: 'Target agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+        },
         taskId: {
             type: 'string',
             description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
@@ -51,10 +54,15 @@ export const recordArtifactCapability = {
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const chatId = args['chatId'];
         const agreementId = args['agreementId'];
-        if ((chatId && agreementId) || (!chatId && !agreementId)) {
-            throw new Error('Pass exactly one of chatId or agreementId');
+        // Agreement wins when both scopes arrive. Models naturally pass the chat
+        // they are standing in alongside the agreement they deliver under; a hard
+        // xor here failed the deliverable at the last step of a finished task
+        // (ZIG-924 dogfood). The backend still enforces exactly-one — we resolve
+        // the ambiguity at the exposed surface instead of erroring.
+        const chatId = agreementId ? undefined : args['chatId'];
+        if (!chatId && !agreementId) {
+            throw new Error('Pass chatId or agreementId');
         }
         const visibility = args['visibility'];
         if (visibility !== 'chat' && visibility !== 'agent-private') {

package/dist/capabilities/links.js

@@ -1,9 +1,33 @@
 import { createAgreement, claimAgreement, listAgreements, revokeAgreement, } from '../http/AgreementClient.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
+/** Public Streamable-HTTP MCP endpoint; OAuth is discovered from it (RFC 9728). */
+const ZIGGS_MCP_URL = 'https://mcp.ziggsai.com/mcp';
 function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
+/**
+ * The second form an invite travels in: text the recipient pastes into their
+ * own assistant, which then connects itself and claims the invite. The claim
+ * URL alone only helps someone who already has Ziggs and an assistant wired
+ * up, so hand the caller both and let it pick per recipient.
+ */
+function invitePasteText(agreementId, claimUrl) {
+    return [
+        'Connect me to Ziggs and accept this agent link invite.',
+        '',
+        `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
+        '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
+        '   but I may need to approve a consent screen in my browser.',
+        `2. Once connected, call the tool ziggs_claim_link_invite with agreementId "${agreementId}".`,
+        '3. Then tell me who I am linked with, and what they can and cannot see.',
+        '',
+        'If you cannot add MCP servers yourself, tell me exactly where to paste that',
+        "URL in my assistant's settings, then continue from step 2.",
+        '',
+        `Invite link (if you need it in a browser instead): ${claimUrl}`,
+    ].join('\n');
+}
 /**
  * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
  * block, approvals array, and Mongo internals are noise on a trust
@@ -85,13 +109,15 @@ export const createLinkInviteCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const { agreement } = await createAgreement({ engagementKind: 'link', description: args['message'] }, fullCreds(env));
+        const claimUrl = `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`;
         return {
             status: 'open',
             inviteId: agreement.agreementId,
-            claimUrl: `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`,
+            claimUrl,
+            pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? 'Open link invite created. Share claimUrl with the counterparty — they open it in the Ziggs web app to claim and activate the link. No agent id needed on either side.'
-                : 'Open link invite created. Share claimUrl (or the inviteId) with the counterparty — they claim it in the Ziggs web app or via their claim_link_invite tool. No agent id needed on either side. Revoke with revoke_link to disable.',
+                ? 'Open link invite created, single-use and valid 7 days. Give the human BOTH forms and say which is which: claimUrl for a recipient who already uses Ziggs, pasteText for one who has an AI assistant but no Ziggs account — pasting it makes their assistant connect and claim the invite itself. No agent id needed on either side.'
+                : 'Open link invite created, single-use and valid 7 days. Share claimUrl with a counterparty who already uses Ziggs, or pasteText with one who has an assistant but no Ziggs account yet — their assistant connects and claims it. No agent id needed on either side. Revoke with revoke_link to disable.',
             agreement: linkSummary(agreement),
         };
     },

package/dist/http/AgreementClient.d.ts

@@ -14,6 +14,12 @@ export interface ProposeTerms {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /**
+     * How `price` reads. `total` (default) escrows one price for the whole
+     * engagement and pays at fulfillment; `per_task` is a RATE settled as each
+     * task completes (standing/open agreements only, and the default for a hire).
+     */
+    billing?: 'total' | 'per_task';
     agreementDescription?: string;
     parentAgreementId?: string;
     parentTaskId?: string;

package/dist/http/ContextReadClient.js

@@ -49,7 +49,13 @@ export class ContextReadClient {
         const res = await fetch(url.toString(), { headers });
         const body = await res.text().catch(() => '');
         if (!res.ok) {
-            throw new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
+            // Carry the status like `snapshot()` does, so callers can branch on it.
+            // A 403 here is a legitimate outcome, not a transport failure: addressing
+            // and authorisation are separate, so an agent can be told about mail it
+            // is not (or is no longer) allowed to open.
+            const err = new Error(`ContextReadClient.read ${type} ${res.status} ${body.slice(0, 200)}`);
+            err.status = res.status;
+            throw err;
         }
         return JSON.parse(body);
     }

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,9 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.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 +34,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 = {}) {
@@ -47,28 +50,53 @@ export class InboxClient {
         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)}`);
         }
         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) {

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/index.d.ts

@@ -25,4 +25,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/index.d.ts

@@ -2,6 +2,7 @@ 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';

package/package.json

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