@ziggs-ai/api-client 0.17.0 → 0.17.1

package/README.md

@@ -90,6 +90,9 @@ await artifacts.write({
 });
 
 // Inbox loop: references since last ack (inbox → read → act → ack)
+// One host owns an agent's inbox. A long-lived process names itself; a rail
+// whose process is not its host passes its own identity as the 4th argument
+// (see src/instanceIdentity.ts for what each one sends).
 const inbox = new InboxClient(operatorKey, agentId);
 const env = await inbox.getInbox();
 await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);

package/dist/http/InboxClient.d.ts

@@ -8,11 +8,16 @@ export declare class InboxClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
+    private readonly instanceId;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param instanceId This host's stable identity, when the caller knows it
+     * better than the process does — see {@link hostIdentity}. A rail whose
+     * process is not its host (the CLI, one hosted-MCP connection among many)
+     * must pass its own; everything long-lived omits it.
      */
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, instanceId?: string);
     private headers;
     private inboxUrl;
     getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;

package/dist/http/InboxClient.js

@@ -1,6 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
-import { INBOX_HOST_CLAIMANT_HEADER, instanceIdentity, } from '../instanceIdentity.js';
+import { INBOX_HOST_CLAIMANT_HEADER, hostIdentity, } from '../instanceIdentity.js';
 /**
  * The doorbell, not the door: references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -10,24 +10,30 @@ export class InboxClient {
     operatorKey;
     agentId;
     baseUrl;
+    instanceId;
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
+     * @param instanceId This host's stable identity, when the caller knows it
+     * better than the process does — see {@link hostIdentity}. A rail whose
+     * process is not its host (the CLI, one hosted-MCP connection among many)
+     * must pass its own; everything long-lived omits it.
      */
-    constructor(operatorKey, agentId, baseUrl) {
+    constructor(operatorKey, agentId, baseUrl, instanceId) {
         if (!operatorKey)
             throw new Error('InboxClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.instanceId = hostIdentity(instanceId);
     }
     headers() {
         const headers = {
             Authorization: `Bearer ${this.operatorKey}`,
             'Content-Type': 'application/json',
-            // This process, not the API. Two fleets of the same agent share
+            // This host, not the API. Two fleets of the same agent share
             // one backend task; without this they both wake.
-            [INBOX_HOST_CLAIMANT_HEADER]: instanceIdentity(),
+            [INBOX_HOST_CLAIMANT_HEADER]: this.instanceId,
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, Agree
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
+export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdentity, hostIdentity, instanceIdentity, mcpConnectionIdentity, } from './instanceIdentity.js';
 export * from './utils/appUrls.js';

package/dist/index.js

@@ -15,4 +15,5 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 export { ApiError } from './types.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
+export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdentity, hostIdentity, instanceIdentity, mcpConnectionIdentity, } from './instanceIdentity.js';
 export * from './utils/appUrls.js';

package/dist/instanceIdentity.d.ts

@@ -1,14 +1,41 @@
-/**
- * Which process is calling GET /inbox.
- *
- * The exclusive-read claimant must be the *host* (this fleet task, a
- * laptop fleet, an MCP process), not the API process. Two fleets share
- * one backend task, so stamping the API's identity would let both wake.
- *
- * `ecs:<id>` on Fargate, `local:<host>:<pid>` otherwise. Env-derived
- * and memoized.
- */
+/** The backend refuses anything longer; it truncates nothing itself. */
+export declare const INSTANCE_IDENTITY_MAX_LENGTH = 64;
 export declare const INBOX_HOST_CLAIMANT_HEADER = "X-Ziggs-Instance";
+/** This process: `ZIGGS_INSTANCE_ID`, else `ecs:<id>`, else `local:<host>:<pid>`. */
 export declare function instanceIdentity(): string;
 /** Test seam: forget the memoized value so a case can set different env. */
 export declare function resetInstanceIdentityForTests(): void;
+/**
+ * The identity to send: a rail's own choice when it has one, this process
+ * otherwise. Every caller-supplied value goes through the same length rule, so
+ * no rail can put the header over the limit the backend enforces.
+ */
+export declare function hostIdentity(preferred?: string): string;
+/**
+ * `ziggs-cli`: one identity per machine and user.
+ *
+ * Every command is its own process, so pid would make `ziggs inbox --ack` a
+ * host that never read the inbox — refused, always — and a second
+ * `ziggs inbox` inside the lease window a second host. A person at one
+ * terminal is one host; consecutive commands share this.
+ */
+export declare function cliHostIdentity(): string;
+/**
+ * The hosted MCP server: one identity per CONNECTION, off the key it serves.
+ *
+ * Not the backend task's identity. That process serves every connected
+ * assistant at once, so its own identity makes them one host and changes under
+ * all of them on every deploy — a hosted read answering 409 for up to 330
+ * seconds after each restart, and replicas refusing each other's agents.
+ *
+ * The key survives both. A token refresh re-signs the same `keyId`, so an
+ * assistant keeps its inbox across a backend restart and across its own
+ * refresh, and two assistants holding different keys are two hosts, which is
+ * what the ownership law says they are.
+ *
+ * Undefined when the credential carries no `keyId`. Every operator token the
+ * backend mints has one, so this is the shape of a credential that cannot name
+ * a stable host at all; the caller falls back to the process default rather
+ * than send one value every such connection would share.
+ */
+export declare function mcpConnectionIdentity(operatorKey: string): string | undefined;

package/dist/instanceIdentity.js

@@ -1,27 +1,97 @@
+import { decodeOperatorKeyClaims } from './shared/operatorKey.js';
 /**
- * Which process is calling GET /inbox.
+ * Which HOST is calling `GET /inbox` and `POST /inbox/ack`.
  *
- * The exclusive-read claimant must be the *host* (this fleet task, a
- * laptop fleet, an MCP process), not the API process. Two fleets share
- * one backend task, so stamping the API's identity would let both wake.
+ * `X-Ziggs-Instance` decides inbox ownership: the first host to read acquires
+ * an agent's whole inbox, a second host is refused with
+ * `409 INBOX_HOST_CONFLICT` until the owner has stopped renewing for 330
+ * seconds, and an ack renews an owner but never acquires. A missing or
+ * overlong value is `400 INBOX_HOST_REQUIRED`.
  *
- * `ecs:<id>` on Fargate, `local:<host>:<pid>` otherwise. Env-derived
- * and memoized.
+ * So the value has to be stable for as long as a rail is one logical host, and
+ * distinct between rails that are not. What each rail sends:
+ *
+ * | rail                                   | identity              |
+ * | -------------------------------------- | --------------------- |
+ * | fleet task on Fargate                  | `ecs:<task id>`       |
+ * | any other long-lived process, stdio MCP included | `local:<host>:<pid>` |
+ * | `ziggs-cli`                            | `cli:<host>:<user>`   |
+ * | the hosted MCP server, per connection  | `mcp:<keyId>`         |
+ * | anything a scheduler pins              | `ZIGGS_INSTANCE_ID`   |
+ *
+ * A process identity is right for a host that outlives its inbox reads and
+ * wrong for one that does not. `ziggs-cli` is a new process per command, so
+ * pid would refuse its own `--ack`; a cron that respawns
+ * `npx @ziggs-ai/ziggs-mcp` every minute is a new host every minute, which is
+ * what `ZIGGS_INSTANCE_ID` is for.
+ *
+ * `ZIGGS_INSTANCE_ID` beats the process default wherever it is read. It is NOT
+ * read on the hosted rail: that one process serves every connected assistant,
+ * and a single env var would collapse them back into the one host this exists
+ * to separate.
  */
 let cached = null;
-const MAX_LENGTH = 64;
+/** The backend refuses anything longer; it truncates nothing itself. */
+export const INSTANCE_IDENTITY_MAX_LENGTH = 64;
 export const INBOX_HOST_CLAIMANT_HEADER = 'X-Ziggs-Instance';
+/** This process: `ZIGGS_INSTANCE_ID`, else `ecs:<id>`, else `local:<host>:<pid>`. */
 export function instanceIdentity() {
     if (cached)
         return cached;
-    cached = resolve().slice(0, MAX_LENGTH);
+    cached = fit(resolve());
     return cached;
 }
 /** Test seam: forget the memoized value so a case can set different env. */
 export function resetInstanceIdentityForTests() {
     cached = null;
 }
+/**
+ * The identity to send: a rail's own choice when it has one, this process
+ * otherwise. Every caller-supplied value goes through the same length rule, so
+ * no rail can put the header over the limit the backend enforces.
+ */
+export function hostIdentity(preferred) {
+    const chosen = preferred?.trim();
+    return chosen ? fit(chosen) : instanceIdentity();
+}
+/**
+ * `ziggs-cli`: one identity per machine and user.
+ *
+ * Every command is its own process, so pid would make `ziggs inbox --ack` a
+ * host that never read the inbox — refused, always — and a second
+ * `ziggs inbox` inside the lease window a second host. A person at one
+ * terminal is one host; consecutive commands share this.
+ */
+export function cliHostIdentity() {
+    const pinned = process.env.ZIGGS_INSTANCE_ID?.trim();
+    return fit(pinned || `cli:${hostLabel()}:${safeUsername()}`);
+}
+/**
+ * The hosted MCP server: one identity per CONNECTION, off the key it serves.
+ *
+ * Not the backend task's identity. That process serves every connected
+ * assistant at once, so its own identity makes them one host and changes under
+ * all of them on every deploy — a hosted read answering 409 for up to 330
+ * seconds after each restart, and replicas refusing each other's agents.
+ *
+ * The key survives both. A token refresh re-signs the same `keyId`, so an
+ * assistant keeps its inbox across a backend restart and across its own
+ * refresh, and two assistants holding different keys are two hosts, which is
+ * what the ownership law says they are.
+ *
+ * Undefined when the credential carries no `keyId`. Every operator token the
+ * backend mints has one, so this is the shape of a credential that cannot name
+ * a stable host at all; the caller falls back to the process default rather
+ * than send one value every such connection would share.
+ */
+export function mcpConnectionIdentity(operatorKey) {
+    const keyId = decodeOperatorKeyClaims(operatorKey)?.keyId?.trim();
+    return keyId ? fit(`mcp:${keyId}`) : undefined;
+}
 function resolve() {
+    const pinned = process.env.ZIGGS_INSTANCE_ID?.trim();
+    if (pinned)
+        return pinned;
     const metadataUri = process.env.ECS_CONTAINER_METADATA_URI_V4 ??
         process.env.ECS_CONTAINER_METADATA_URI;
     if (metadataUri) {
@@ -30,26 +100,62 @@ function resolve() {
         if (short.length >= 8)
             return `ecs:${short}`;
     }
-    const host = process.env.HOSTNAME || safeHostname();
-    return `local:${host}:${process.pid}`;
+    return `local:${hostLabel()}:${process.pid}`;
+}
+/**
+ * Keep an overlong identity unique.
+ *
+ * Plain truncation is what the backend stopped doing on purpose: two long
+ * values cut to one is exactly the collision the header exists to prevent. A
+ * readable head plus a hash of the whole stays inside the limit and stays
+ * distinct.
+ */
+function fit(value) {
+    if (value.length <= INSTANCE_IDENTITY_MAX_LENGTH)
+        return value;
+    const head = value.slice(0, INSTANCE_IDENTITY_MAX_LENGTH - 9);
+    return `${head}:${fnv1a(value)}`;
+}
+/** FNV-1a/32 in hex. Distinguishes hosts; it is not a checksum for anything. */
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+function hostLabel() {
+    return process.env.HOSTNAME || safeHostname();
 }
 function safeHostname() {
+    return builtinOs()?.hostname?.() || 'unknown-host';
+}
+function safeUsername() {
+    const fromEnv = process.env.USER || process.env.USERNAME;
+    if (fromEnv)
+        return fromEnv;
+    return (builtinOs()?.userInfo?.()
+        ?.username || 'unknown-user');
+}
+/**
+ * Reached for at call time, not imported at the top of the file. A static
+ * `node:os` specifier makes this module — and through the inbox client, the
+ * package entry — unresolvable to a bundler with no node builtins, which is
+ * every mobile bundler. Nothing here needs the host name in order to load.
+ *
+ * `getBuiltinModule` arrived in Node 20.16 / 22.3. On anything older the
+ * labels fall back to their `unknown-` forms, which costs a readable name on a
+ * dev machine and nothing in a deployed task: those resolve through the
+ * container metadata path above.
+ */
+function builtinOs() {
     try {
-        // Reached for at call time, not imported at the top of the file. A static
-        // `node:os` specifier makes this module — and through the inbox client,
-        // the package entry — unresolvable to a bundler with no node builtins,
-        // which is every mobile bundler. Nothing here needs the host name in order
-        // to load.
-        //
-        // `getBuiltinModule` arrived in Node 20.16 / 22.3. On anything older the
-        // name falls back below, which costs a host label on a dev machine and
-        // nothing in a deployed task: those resolve through the container
-        // metadata path above.
-        const load = process.getBuiltinModule;
-        const os = load?.('node:os');
-        return os?.hostname?.() || 'unknown-host';
+        const load = process
+            .getBuiltinModule;
+        return load?.('node:os');
     }
     catch {
-        return 'unknown-host';
+        return undefined;
     }
 }

package/dist/types.d.ts

@@ -37,6 +37,14 @@ export interface Creds {
      * agent is not in.
      */
     laneId?: string;
+    /**
+     * This host's stable identity, sent as `X-Ziggs-Instance` on inbox reads and
+     * acks. Set it only on a rail whose PROCESS is not its host — the CLI, one
+     * hosted-MCP connection among the many a backend task serves. Everything
+     * long-lived leaves it unset and the process names itself. See
+     * `src/instanceIdentity.ts` for what each rail sends.
+     */
+    instanceId?: string;
 }
 export type TaskState = 'active' | 'proposal' | 'completed' | 'failed' | 'cancelled' | 'ledger_open';
 export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';

package/package.json

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