@ziggs-ai/api-client 0.40.2 → 0.40.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.40.4
+
+- `InboxEnvelope.bellAt`: the latest delivery a read answered. `getInbox({ seen })` passes it back so a held read answers only mail delivered after it.
+
+## 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) {
@@ -55,6 +61,8 @@ export class InboxClient {
         if (opts.waitSeconds != null && opts.waitSeconds > 0) {
             url.searchParams.set('wait', String(opts.waitSeconds));
         }
+        if (opts.seen)
+            url.searchParams.set('seen', opts.seen);
         return url.toString();
     }
     /** At most 25 retained references per page. Keep cursor for subsequent waits;
@@ -80,8 +88,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,7 +413,18 @@ 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 latest delivery this read answered; pass it back as `seen`. */
+    bellAt?: string | null;
     /**
      * The mailboxes this reader's view merges — its owner's, plus whatever
      * inbox grants add. Absent on older servers.
@@ -488,6 +499,10 @@ export interface InboxAckResult {
  */
 export interface InboxReadOptions {
     waitSeconds?: number;
+    /** The `bellAt` of the last envelope this host read. A held read then answers
+     * only mail delivered after it, so a host still working on those rows waits
+     * for new mail instead of being handed them again. */
+    seen?: string;
 }
 /** Count-only peek. Does not take the inbox host lease. */
 export interface InboxPeek {

package/package.json

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