@ziggs-ai/api-client 0.16.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/AgreementClient.js

@@ -2,22 +2,15 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 // Lazy: read at call time so a `configureApiClient` call that lands after this
 // module is imported still takes effect. Baking it at module-load time would
 // freeze the URL before the host has configured one.
 function getAgreementBaseUrl() {
     return `${getBackendUrl()}/agreements`;
 }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/ChatClient.js

@@ -1,16 +1,9 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+import { buildCredsHeaders } from './operatorHeaders.js';
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/ContextReadClient.js

@@ -1,5 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export const CONTEXT_READ_TYPES = [
     'messages',
     'artifacts',
@@ -92,13 +93,7 @@ export class ContextReadClient {
         if (query.contextGrantId) {
             url.searchParams.set('contextGrantId', query.contextGrantId);
         }
-        const headers = {
-            Authorization: `Bearer ${this.operatorKey}`,
-        };
-        if (this.agentId)
-            headers['X-Agent-Id'] = this.agentId;
-        if (this.laneId)
-            headers['X-Ziggs-Lane'] = this.laneId;
+        const headers = buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId);
         if (query.contextGrantId) {
             headers['X-Context-Grant-Id'] = query.contextGrantId;
         }
@@ -131,13 +126,7 @@ export class ContextReadClient {
         if (opts.contextGrantId) {
             url.searchParams.set('contextGrantId', opts.contextGrantId);
         }
-        const headers = {
-            Authorization: `Bearer ${this.operatorKey}`,
-        };
-        if (this.agentId)
-            headers['X-Agent-Id'] = this.agentId;
-        if (this.laneId)
-            headers['X-Ziggs-Lane'] = this.laneId;
+        const headers = buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId);
         if (opts.contextGrantId) {
             headers['X-Context-Grant-Id'] = opts.contextGrantId;
         }

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/http/MarketplaceClient.js

@@ -2,17 +2,10 @@
 import { shapeAgreement } from './AgreementClient.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 function getMarketplaceBaseUrl() { return `${getBackendUrl()}/marketplace`; }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/TaskClient.js

@@ -1,17 +1,10 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { partyActorIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/index.d.ts

@@ -28,3 +28,4 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';

package/dist/http/index.js

@@ -19,3 +19,7 @@ export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentA
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
+// The lane header, built in one place — see operatorHeaders.ts. Exported
+// because the MCP transports in agent-sdk and ziggs-mcp send it too, and a
+// copy of a header nobody notices missing goes stale unseen.
+export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';

package/dist/http/operatorHeaders.d.ts

@@ -1,8 +1,21 @@
 /**
- * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
- * an agentId is present — agent-scoped keys identify the agent themselves;
- * fleet keys must pass one.
+ * Auth headers for operator-key HTTP clients.
+ *
+ * ONE place builds them, because the lane is the header a caller cannot be
+ * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
+ * the wake to the agent's own org instead, so a door that forgets it answers
+ * short lists and refuses grants the agent's customer gave it — silently, and
+ * only for the agents that serve someone other than their owner. A header
+ * whose absence is indistinguishable from a legitimate answer has to be built
+ * in one place, not copied into each caller.
  */
+/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
+export declare const WAKE_LANE_HEADER = "X-Ziggs-Lane";
+/**
+ * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
+ * for a task with no origin chat.
+ */
+export declare function laneHeader(laneId?: string): Record<string, string>;
 export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 
 /**
  * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
@@ -10,3 +23,9 @@ export declare function buildOperatorHeaders(operatorKey: string, agentId?: stri
  * narrows to the agent's own org, so it can never widen reach.
  */
 laneId?: string): Record<string, string>;
+/** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
+export declare function buildCredsHeaders(creds: {
+    operatorKey: string;
+    agentId: string;
+    laneId?: string;
+}): Record<string, string>;

package/dist/http/operatorHeaders.js

@@ -1,8 +1,23 @@
 /**
- * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
- * an agentId is present — agent-scoped keys identify the agent themselves;
- * fleet keys must pass one.
+ * Auth headers for operator-key HTTP clients.
+ *
+ * ONE place builds them, because the lane is the header a caller cannot be
+ * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
+ * the wake to the agent's own org instead, so a door that forgets it answers
+ * short lists and refuses grants the agent's customer gave it — silently, and
+ * only for the agents that serve someone other than their owner. A header
+ * whose absence is indistinguishable from a legitimate answer has to be built
+ * in one place, not copied into each caller.
  */
+/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
+export const WAKE_LANE_HEADER = 'X-Ziggs-Lane';
+/**
+ * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
+ * for a task with no origin chat.
+ */
+export function laneHeader(laneId) {
+    return laneId ? { [WAKE_LANE_HEADER]: laneId } : {};
+}
 export function buildOperatorHeaders(operatorKey, agentId, extra, 
 /**
  * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
@@ -12,8 +27,17 @@ export function buildOperatorHeaders(operatorKey, agentId, extra,
 laneId) {
     return {
         Authorization: `Bearer ${operatorKey}`,
+        // `X-Agent-Id` is only sent when an agentId is present — agent-scoped keys
+        // identify the agent themselves; fleet keys must pass one.
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),
-        ...(laneId ? { 'X-Ziggs-Lane': laneId } : {}),
+        ...laneHeader(laneId),
         ...extra,
     };
 }
+/** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
+export function buildCredsHeaders(creds) {
+    return {
+        'content-type': 'application/json',
+        ...buildOperatorHeaders(creds.operatorKey, creds.agentId, undefined, creds.laneId),
+    };
+}

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.16.0",
+  "version": "0.17.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",