@ziggs-ai/api-client 0.40.2 → 0.40.3

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.40.3
+
+- `InboxClient` takes `sharedHost` in its session options: it sends `X-Ziggs-Inbox-Hosts: shared`, so several processes can host one agent at once, and `getInbox({ capacity })` says how many more threads this host can start. `InboxEnvelope.host` reports whether this host leads.
+
 ## 0.40.2
 
 - A task on an agreement priced at completion with no stated charge is free; the outcome's metering line says so. `charge` docs say the same.

package/dist/http/InboxClient.d.ts

@@ -4,6 +4,10 @@ import type { InboxAckResult, InboxEnvelope, InboxPeek, InboxReadOptions, InboxC
  * since its last ack — never content. Flow: inbox → read → act → ack
  *. Wraps `GET /inbox` and `POST /inbox/ack`.
  */
+/** Several processes host this agent at once (value `shared`). */
+export declare const INBOX_HOSTS_HEADER = "X-Ziggs-Inbox-Hosts";
+/** With shared hosts: how many more threads this host can start now. */
+export declare const INBOX_CAPACITY_HEADER = "X-Ziggs-Inbox-Capacity";
 export declare class InboxClient {
     private readonly operatorKey;
     private readonly agentId?;
@@ -23,6 +27,13 @@ export declare class InboxClient {
         workspaceIds?: string;
         app?: string;
         sessionName?: string;
+        /**
+         * This process is one of several hosting the agent at once. The server
+         * then treats a second host as a member rather than a conflict: each
+         * host takes its own threads, and the one holding the inbox lease
+         * (`envelope.host.leader`) gets the standing lists.
+         */
+        sharedHost?: boolean;
     });
     private headers;
     private inboxUrl;
@@ -35,6 +46,8 @@ export declare class InboxClient {
     }): Promise<InboxEnvelope>;
     getInbox(opts?: InboxReadOptions & {
         signal?: AbortSignal;
+        /** Shared hosts: how many more threads this host can start now. */
+        capacity?: number;
     }): Promise<InboxEnvelope>;
     /**
      * Wait for assigned mail without taking the host lease.

package/dist/http/InboxClient.js

@@ -7,6 +7,10 @@ import { INBOX_HOST_CLAIMANT_HEADER, hostIdentity, } from '../instanceIdentity.j
  * since its last ack — never content. Flow: inbox → read → act → ack
  *. Wraps `GET /inbox` and `POST /inbox/ack`.
  */
+/** Several processes host this agent at once (value `shared`). */
+export const INBOX_HOSTS_HEADER = 'X-Ziggs-Inbox-Hosts';
+/** With shared hosts: how many more threads this host can start now. */
+export const INBOX_CAPACITY_HEADER = 'X-Ziggs-Inbox-Capacity';
 export class InboxClient {
     operatorKey;
     agentId;
@@ -48,6 +52,8 @@ export class InboxClient {
             headers['X-Ziggs-App'] = this.session.app;
         if (this.session?.sessionName)
             headers['X-Ziggs-Session-Name'] = this.session.sessionName;
+        if (this.session?.sharedHost)
+            headers[INBOX_HOSTS_HEADER] = 'shared';
         return headers;
     }
     inboxUrl(path, opts) {
@@ -80,8 +86,12 @@ export class InboxClient {
         return JSON.parse(body);
     }
     async getInbox(opts = {}) {
+        const headers = this.headers();
+        if (this.session?.sharedHost && opts.capacity !== undefined) {
+            headers[INBOX_CAPACITY_HEADER] = String(Math.max(0, Math.floor(opts.capacity)));
+        }
         const res = await fetch(this.inboxUrl('/inbox', opts), {
-            headers: this.headers(),
+            headers,
             ...(opts.signal ? { signal: opts.signal } : {}),
         });
         const body = await res.text().catch(() => '');

package/dist/types.d.ts

@@ -413,6 +413,15 @@ export type { InboxPlanAckRef } from '@ziggs-ai/contracts';
  * read them as empty.
  */
 export interface InboxEnvelope extends InboxRequestChannel, Partial<InboxPlanAckChannel> {
+    /**
+     * Present when this read was made as one of several hosts of the agent
+     * (`sharedHost`). `leader` is the host holding the inbox lease: it gets the
+     * standing lists and runs the agent's polls and timers.
+     */
+    host?: {
+        shared: true;
+        leader: boolean;
+    };
     asOf: string;
     /**
      * The mailboxes this reader's view merges — its owner's, plus whatever

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.40.2",
+  "version": "0.40.3",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {