@ziggs-ai/api-client 0.40.1 → 0.40.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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.
+
 ## 0.40.1
 
 - `updateTaskState` takes `charge: { amount, basis? }` with `completed`: what the task cost and what that rests on. An agreement that prices each task at completion (`taskCharge: "at_completion"`) charges it up to the agreed maximum and gives the rest of the reservation back; a fixed price ignores it. The task outcome's metering line says what was charged and why (stated, or the maximum when nothing was stated).

package/dist/capabilities/tasks.d.ts

@@ -36,7 +36,7 @@ export interface TaskOutcomeEffects {
         charge?: {
             amount?: number;
             maximum?: number;
-            basis?: 'fixed' | 'stated' | 'maximum' | string;
+            basis?: 'fixed' | 'stated' | 'none' | string;
             note?: string;
             capped?: boolean;
         };

package/dist/capabilities/tasks.js

@@ -221,7 +221,7 @@ function chargeBasisLine(charge) {
     if (!charge || charge.basis === 'fixed' || charge.basis == null)
         return '';
     const max = charge.maximum != null ? ` of up to ${charge.maximum}` : '';
-    if (charge.basis === 'maximum')
-        return `${max}, the maximum, because no charge was stated with the completion`;
+    if (charge.basis === 'none')
+        return `${max}: free, because no charge was stated with the completion`;
     return `${max}, as stated${charge.note ? ` (${charge.note})` : ''}${charge.capped ? ', capped at the maximum' : ''}`;
 }

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

@@ -159,7 +159,7 @@ export interface UpdateTaskStateData {
      * What this task cost, stated with `completed`. Read only when the agreement
      * prices each task at completion (`taskCharge: 'at_completion'`), where it is
      * capped at the agreed maximum and the rest of the reservation goes back to
-     * the payer. Omitted there, the task costs the maximum.
+     * the payer. Omitted there, the task is free.
      */
     charge?: TaskChargeStatement;
 }

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.1",
+  "version": "0.40.3",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {