@ziggs-ai/api-client 0.17.0 → 0.18.0

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/capabilities/chat.js

@@ -12,8 +12,8 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Open a chat',
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and the refusal names the levers. To list chats you can already read, use grant_list scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and names the levers.',
+        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and the refusal names the levers. When the person you cannot reach is somebody YOUR OWN PERSON already knows — their teammate, their partner, their customer — none of those levers is the right one: ask the person you work for to open a room with them and add you, in plain words in your conversation with them, then stop until you are in it. Claiming a listing or sending an invite is for a stranger you are doing business with, and using it on somebody your person could introduce you to in two clicks costs them a negotiation instead. To list chats you can already read, use grant_list scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and names the levers. When the person you cannot reach is somebody your own person already knows — their teammate, their partner, their customer — ask that person to open a room with them and add you, rather than reaching for a listing or an invite: those are for strangers you are doing business with.',
     },
     annotation: 'write',
     params: {

package/dist/http/AgreementClient.d.ts

@@ -88,6 +88,23 @@ export declare function linkSummary(a: Agreement): Record<string, unknown>;
  * Agreement field, so this narrows a document rather than returning a different
  * shape.
  */
+/**
+ * Lift the fields the wire nests, then summarise a link.
+ *
+ * `Agreement` offers `description`, `proposalStatus`, `lifecycle`,
+ * `expiresAt`, `maxExecutions` and `linkInvite` at the top level. The wire
+ * does not: it sends them under `terms` and `proposal`, and calls the seats
+ * `claimSeats`. This function is the only thing between the two and it used
+ * to map NONE of them, so every one of those reads answered `undefined` —
+ * silently, because the hand-written type promised they would be there.
+ *
+ * Filled here rather than by changing the type, because ~78 call sites across
+ * the SDK, ziggs-mcp and the agents read them at the top level. They keep
+ * reading them; they now get the value.
+ *
+ * The nested fields stay where the server put them. This adds a view, it does
+ * not move anything.
+ */
 export declare function shapeAgreement(a: Agreement): Agreement;
 /** @deprecated Alias for {@link ProposeDirectInput}. */
 export type ProposeAgreementData = ProposeDirectInput;

package/dist/http/AgreementClient.js

@@ -73,8 +73,56 @@ export function linkSummary(a) {
  * Agreement field, so this narrows a document rather than returning a different
  * shape.
  */
+/**
+ * Lift the fields the wire nests, then summarise a link.
+ *
+ * `Agreement` offers `description`, `proposalStatus`, `lifecycle`,
+ * `expiresAt`, `maxExecutions` and `linkInvite` at the top level. The wire
+ * does not: it sends them under `terms` and `proposal`, and calls the seats
+ * `claimSeats`. This function is the only thing between the two and it used
+ * to map NONE of them, so every one of those reads answered `undefined` —
+ * silently, because the hand-written type promised they would be there.
+ *
+ * Filled here rather than by changing the type, because ~78 call sites across
+ * the SDK, ziggs-mcp and the agents read them at the top level. They keep
+ * reading them; they now get the value.
+ *
+ * The nested fields stay where the server put them. This adds a view, it does
+ * not move anything.
+ */
 export function shapeAgreement(a) {
-    return a.engagementKind === 'link' ? linkSummary(a) : a;
+    const wire = a;
+    const lifted = {
+        ...a,
+        ...(wire.terms?.description != null
+            ? { description: wire.terms.description }
+            : {}),
+        ...(wire.terms?.lifecycle != null
+            ? { lifecycle: wire.terms.lifecycle }
+            : {}),
+        ...(wire.terms?.expiresAt != null
+            ? { expiresAt: wire.terms.expiresAt }
+            : {}),
+        ...(wire.terms?.maxExecutions != null
+            ? { maxExecutions: wire.terms.maxExecutions }
+            : {}),
+        ...(wire.proposal?.status != null
+            ? { proposalStatus: wire.proposal.status }
+            : {}),
+        ...(wire.claimSeats
+            ? {
+                linkInvite: {
+                    ...(wire.claimSeats.maxClaims != null
+                        ? { maxClaims: wire.claimSeats.maxClaims }
+                        : {}),
+                    claimsUsed: wire.claimSeats.claimsUsed,
+                },
+            }
+            : {}),
+    };
+    return lifted.engagementKind === 'link'
+        ? linkSummary(lifted)
+        : lifted;
 }
 export async function proposeAgreement(proposalData, creds) {
     if (!proposalData)

package/dist/http/ArtifactsClient.d.ts

@@ -1,3 +1,4 @@
+import type { ListReachableArtifactsResult } from '@ziggs-ai/contracts';
 /**
  * Inline `POST /artifacts` body cap (matches backend
  * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
@@ -22,10 +23,16 @@ export interface ListArtifactsQuery {
      */
     authoredBy?: 'me';
 }
-export interface ListArtifactsResult {
-    artifacts: unknown[];
-    latestSequence: string | null;
-}
+/**
+ * The reachable-artifact listing, as the server sends it.
+ *
+ * `truncated` was missing here, and it is the field that says the answer is
+ * incomplete — a caller typed against the old shape could not see that some
+ * sources were dropped, which is the same "short list read as a whole one"
+ * failure the grants rail names `unreadableRails` for. `artifacts` is also
+ * typed now, where it was `unknown[]`.
+ */
+export type ListArtifactsResult = ListReachableArtifactsResult;
 export interface WriteArtifactInput {
     text: string;
     /** Short list name. An upload defaults to filename when omitted. */

package/dist/http/ChatClient.d.ts

@@ -1,15 +1,18 @@
+import type { ChatReadDto } from '@ziggs-ai/contracts';
 import type { SendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
-/** Shape of GET /chats/mine items — the backend's ChatReadDto. */
-export interface ChatSummary {
-    chatId: string;
-    members: Array<{
-        principalId: string;
-        agentId: string | null;
-    }>;
-    orgId: string | null;
-    isOrgChat: boolean;
-}
+/**
+ * One room from `GET /chats/mine`, as the server sends it.
+ *
+ * The backend answers `toChatReadDto(...)`, so this is that type rather than
+ * a restatement of it. The restatement had drifted both ways: it declared
+ * `orgId` and `isOrgChat`, neither of which the wire carries — a caller
+ * branching on `isOrgChat` was branching on `undefined` — and it omitted
+ * seven fields the wire does send, including `name`, `updatedAt` and
+ * `lastMessage`, which are the ones this list exists to let an agent triage
+ * with without a second call.
+ */
+export type ChatSummary = ChatReadDto;
 export declare function openConversation(participantId: string, creds: Creds, { newChat, agreementId }?: {
     newChat?: boolean;
     agreementId?: string;
@@ -95,5 +98,5 @@ export declare class ChatClient {
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;
-    listMine(): Promise<ChatSummary[]>;
+    listMine(): Promise<ChatReadDto[]>;
 }

package/dist/http/GrantsClient.d.ts

@@ -31,20 +31,20 @@ export interface ListGrantsQuery {
  * presenting a short list as if it were complete). Replaces the client-side
  * mirror of the backend scope table + JWT decode (the retired grantRails.ts).
  */
-export interface UnreadableRail {
-    rail: 'context' | 'connection' | 'wallet';
-    requiredScope: string;
-}
-export interface ListGrantsResult {
-    items: GrantView[];
-    nextCursor: string | null;
-    hasMore: boolean;
-    /**
-     * Rails the caller can't read, per the backend. Absent when the backend
-     * predates or every requested rail was readable.
-     */
-    unreadableRails?: UnreadableRail[];
-}
+/**
+ * The wire's list, not this client's guess at it.
+ *
+ * This named three rails where the server has five, so a refusal on the
+ * `consent` or `inbox` rail did not typecheck as one — and the whole point of
+ * this field is that a short list must not read as an empty one.
+ */
+import type { UnreadableRail, ListGrantsResult } from '@ziggs-ai/contracts';
+export type { UnreadableRail };
+/**
+ * The unified grant listing. `unreadableRails` names the rails the caller
+ * could not read, so a short list is never mistaken for an empty one.
+ */
+export type { ListGrantsResult };
 /**
  * unified grant listing across every rail. `GET /grants` returns the
  * canonical GrantView for each grant the caller holds (or, admin-gated, a named

package/dist/http/InboxClient.d.ts

@@ -1,4 +1,4 @@
-import type { InboxAckResult, InboxEnvelope, InboxReadOptions } from '../types.js';
+import type { InboxAckResult, InboxEnvelope, InboxPeek, InboxReadOptions } from '../types.js';
 /**
  * The doorbell, not the door: references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -8,14 +8,24 @@ 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>;
+    /**
+     * Wait for assigned mail without taking the host lease.
+     * Still sends X-Ziggs-Instance; the server ignores it on this route.
+     */
+    peek(opts?: InboxReadOptions): Promise<InboxPeek>;
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
      * `resourceId` handled in `(priorAck, upTo]`. Monotonic

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;
@@ -50,6 +56,20 @@ export class InboxClient {
         }
         return JSON.parse(body);
     }
+    /**
+     * Wait for assigned mail without taking the host lease.
+     * Still sends X-Ziggs-Instance; the server ignores it on this route.
+     */
+    async peek(opts = {}) {
+        const res = await fetch(this.inboxUrl('/inbox/peek', opts), {
+            headers: this.headers(),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw pollSurfaceError('InboxClient.peek', res, body);
+        }
+        return JSON.parse(body);
+    }
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
      * `resourceId` handled in `(priorAck, upTo]`. Monotonic

package/dist/http/PaymentsClient.d.ts

@@ -14,14 +14,16 @@ export interface PaymentTransactionView {
     transactionId?: string;
     [key: string]: unknown;
 }
-/** A resolved wallet reference (GET /payments/wallets/resolve). */
-export interface WalletRef {
-    walletId?: string;
-    ownerId?: string;
-    currency?: string;
-    status?: string;
-    [key: string]: unknown;
-}
+/**
+ * A resolved wallet reference (GET /payments/wallets/resolve).
+ *
+ * The wire's shape, not a guess at it. This was all-optional with no `orgId`,
+ * so a caller could not tell a wallet that has no org from one whose org the
+ * client forgot to declare — and every field being optional meant TypeScript
+ * agreed with any misreading of the response.
+ */
+import type { WalletRef } from '@ziggs-ai/contracts';
+export type { WalletRef };
 export type TransferResult = {
     status: 'approval_required';
     approvalId: string | null;
@@ -43,10 +45,18 @@ export interface ReleaseResult {
     transaction?: PaymentTransactionView;
     [key: string]: unknown;
 }
+/**
+ * A payment grant as this rail answers it.
+ *
+ * `parentGrantId` is `string | null`, which is what the wire sends — it was
+ * `string | undefined` here, so a root grant's explicit `null` did not match
+ * the declared type and `parentGrantId === undefined` was a test for "is this
+ * a root grant" that never passed.
+ */
 export interface PaymentGrantView {
     grantId?: string;
     holderId?: string;
-    parentGrantId?: string;
+    parentGrantId?: string | null;
     caveats?: unknown[];
     expiresAt?: string | null;
     [key: string]: unknown;
@@ -75,6 +85,17 @@ export type WaitForApprovalResult = {
     status: 'rejected' | 'expired' | 'timeout';
     approval: PaymentApproval;
 };
+/**
+ * Who to pay on a transfer. Kind is declared by the caller — never inferred
+ * from id shape. A bare string is only a wallet id (`wal_…`).
+ */
+export type TransferPayee = string | {
+    walletId: string;
+} | {
+    agentId: string;
+} | {
+    userId: string;
+};
 /**
  * the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
@@ -107,8 +128,13 @@ export declare class PaymentsClient {
         userId?: string;
         agentId?: string;
     }): Promise<WalletRef | null>;
+    /**
+     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
+     * user payees must name their kind.
+     */
+    private resolvePayeeWalletId;
     transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
-        to: string;
+        to: TransferPayee;
         amount: number;
         idempotencyKey?: string;
         description?: string;

package/dist/http/PaymentsClient.js

@@ -61,20 +61,46 @@ export class PaymentsClient {
         const res = (await this._get(`/payments/wallets/resolve?${params}`));
         return res['wallet'] || null;
     }
+    /**
+     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
+     * user payees must name their kind.
+     */
+    async resolvePayeeWalletId(to) {
+        if (typeof to === 'string') {
+            const id = to.trim();
+            if (!id)
+                throw new Error('transfer: `to` is required');
+            if (id.startsWith('wal_'))
+                return id;
+            throw new Error('transfer: string `to` must be a wallet id (wal_…); pass { agentId } or { userId } for a principal');
+        }
+        if ('walletId' in to && typeof to.walletId === 'string' && to.walletId.trim()) {
+            return to.walletId.trim();
+        }
+        if ('agentId' in to && typeof to.agentId === 'string' && to.agentId.trim()) {
+            const w = await this.resolve({ agentId: to.agentId.trim() });
+            if (!w?.walletId) {
+                throw new Error(`transfer: could not resolve wallet for agent "${to.agentId}"`);
+            }
+            return w.walletId;
+        }
+        if ('userId' in to && typeof to.userId === 'string' && to.userId.trim()) {
+            const w = await this.resolve({ userId: to.userId.trim() });
+            if (!w?.walletId) {
+                throw new Error(`transfer: could not resolve wallet for user "${to.userId}"`);
+            }
+            return w.walletId;
+        }
+        throw new Error('transfer: `to` must be a wallet id (wal_…) or { walletId | agentId | userId }');
+    }
     async transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
-        if (!to)
+        if (to == null || to === '')
             throw new Error('transfer: `to` is required');
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('transfer: `amount` must be a positive integer (cents)');
         // The recipient is resolved BEFORE choosing a grant: an `allowed_recipients`
         // caveat cannot be checked against a name the client has not resolved yet.
-        let toWalletId = to;
-        if (!to.startsWith('wal_')) {
-            const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
-            if (!w?.walletId)
-                throw new Error(`transfer: could not resolve wallet for "${to}"`);
-            toWalletId = w.walletId;
-        }
+        const toWalletId = await this.resolvePayeeWalletId(to);
         // Choose the grant that covers this spend when the caller omitted one.
         // An explicit id still wins — a caller who names a grant means it.
         if (this.agentId && !paymentGrantId) {

package/dist/http/TaskClient.d.ts

@@ -72,6 +72,27 @@ export interface CreateTaskData {
     waitsOn?: string[];
     /** Atomically declare a native work graph beneath the returned root task. */
     graph?: CreateTaskGraphData;
+    /**
+     * When the answer stops being useful, ISO 8601. At the deadline
+     * the holder posts what it has and where it is stuck, and stops. A deadline
+     * already past is refused server-side.
+     */
+    dueAt?: string;
+    /**
+     * Reminder cadence and budget for work somebody has to be chased about
+     * Both halves are required together: a cadence with no budget is
+     * an open-ended wake loop, and one reminder is one wake, so the server
+     * refuses a half-filled rule rather than defaulting the missing half. Omit
+     * the whole object for a task nobody needs reminding about.
+     */
+    checkBack?: CreateTaskCheckBackData;
+}
+/** See {@link CreateTaskData.checkBack}. */
+export interface CreateTaskCheckBackData {
+    /** Minimum minutes between two reminders to the same person. */
+    everyMinutes: number;
+    /** Total reminders allowed per person asked, after the first ask. */
+    maxReminders: number;
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;

package/dist/http/grants.d.ts

@@ -46,45 +46,22 @@ export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "
  */
 export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "connection", "wallet", "consent", "inbox"];
 export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
-export interface GrantScopeView {
-    kind: GrantScopeKind;
-    id: string;
-    /**
-     * Human-readable name for the scoped resource, populated only by the unified
-     * list read (GET /grants / GrantsClient); the per-rail issue/delegate
-     * responses omit it. Optional so the one shape stays additive.
-     */
-    label?: string;
-}
-export interface GrantCaveatView {
-    type: string;
-    value: unknown;
-}
-export interface GrantView {
-    grantId: string;
-    issuerId: string;
-    holderId: string;
-    parentGrantId: string | null;
-    agreementId: string | null;
-    scope: GrantScopeView;
-    caveats: GrantCaveatView[];
-    revoked: boolean;
-    /** ISO-8601, or null for no expiry. */
-    expiresAt: string | null;
-    /** ISO-8601. */
-    createdAt: string;
-    health: GrantHealth;
-    /**
-     * What the holder is, what the grant lets them do, and which consent object
-     * authorized it. Present on rails that record them (context grants do);
-     * absent means the rail does not say, not that there is nothing.
-     */
-    holderKind?: GrantHolderKind;
-    access?: GrantAccessKind;
-    basis?: {
-        kind: GrantBasisKind;
-        id: string | null;
-    };
-}
+/**
+ * The scope a grant is over, and one caveat on it — the wire's shapes.
+ *
+ * `label` is populated only by the unified list read; the per-rail
+ * issue/delegate responses omit it, which is why the contract has it optional.
+ */
+export type { GrantScopeView, GrantCaveatView };
+/**
+ * A grant row, exactly as the server sends it.
+ *
+ * Generated from the OpenAPI spec rather than restated here. Three copies of
+ * this shape lived in this package — this one, a looser one on
+ * `PaymentsClient`, and a third on `ConnectionsClient` — and each rail's
+ * client believed a different subset of the row.
+ */
+import type { GrantView, GrantScopeView, GrantCaveatView } from '@ziggs-ai/contracts';
+export type { GrantView };
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export declare function grantCaveat(grant: GrantView, type: string): unknown | undefined;

package/dist/http/index.d.ts

@@ -20,7 +20,7 @@ export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, Cont
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, GrantHolderKind, GrantAccessKind, GrantBasisKind, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
-export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
+export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferPayee, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
 export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, } from './OrgsClient.js';

package/dist/index.d.ts

@@ -10,8 +10,9 @@ export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxPeek, InboxReadOptions, } from './types.js';
 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/shared/operatorKey.d.ts

@@ -1,3 +1,4 @@
+import { OPERATOR_KEY_ISSUED_VIA } from '@ziggs-ai/contracts';
 /** JWT payload fields we read client-side (signature not verified — identity hint only). */
 export interface OperatorKeyClaims {
     type?: string;
@@ -14,10 +15,20 @@ export interface OperatorKeyClaims {
 /** Decode operator JWT payload without verifying signature (boundAgentId). */
 export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
 export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export declare const ISSUED_VIA_MCP_OAUTH = "mcp_oauth";
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export declare const ISSUED_VIA_DEVICE_CODE = "device_code";
+/**
+ * The stamps the two consent rails put on the tokens they mint.
+ *
+ * Re-exported from the contract rather than restated here. This file used to
+ * declare the two strings it cared about while the server's list had six, so
+ * a rail added there was invisible here until somebody remembered — and the
+ * predicate below decides which tool surface a connected assistant gets, so
+ * forgetting would have served the whole catalogue to the new rail's
+ * credentials.
+ */
+export declare const ISSUED_VIA_MCP_OAUTH: "mcp_oauth";
+export declare const ISSUED_VIA_DEVICE_CODE: "device_code";
+export { OPERATOR_KEY_ISSUED_VIA };
+export type { OperatorKeyIssuedVia } from '@ziggs-ai/contracts';
 /**
  * Did a person board this credential through the connector directory?
  *

package/dist/shared/operatorKey.js

@@ -1,3 +1,4 @@
+import { OPERATOR_KEY_ISSUED_VIA, isDirectoryBoardedIssuedVia, } from '@ziggs-ai/contracts';
 /** Decode operator JWT payload without verifying signature (boundAgentId). */
 export function decodeOperatorKeyClaims(token) {
     const trimmed = token.trim();
@@ -26,10 +27,19 @@ export function isOperatorKeyExpired(claims) {
         return false;
     return claims.exp * 1000 <= Date.now();
 }
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export const ISSUED_VIA_MCP_OAUTH = 'mcp_oauth';
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export const ISSUED_VIA_DEVICE_CODE = 'device_code';
+/**
+ * The stamps the two consent rails put on the tokens they mint.
+ *
+ * Re-exported from the contract rather than restated here. This file used to
+ * declare the two strings it cared about while the server's list had six, so
+ * a rail added there was invisible here until somebody remembered — and the
+ * predicate below decides which tool surface a connected assistant gets, so
+ * forgetting would have served the whole catalogue to the new rail's
+ * credentials.
+ */
+export const ISSUED_VIA_MCP_OAUTH = OPERATOR_KEY_ISSUED_VIA.MCP_OAUTH;
+export const ISSUED_VIA_DEVICE_CODE = OPERATOR_KEY_ISSUED_VIA.DEVICE_CODE;
+export { OPERATOR_KEY_ISSUED_VIA };
 /**
  * Did a person board this credential through the connector directory?
  *
@@ -52,8 +62,9 @@ export const ISSUED_VIA_DEVICE_CODE = 'device_code';
  * is PERMITTED.
  */
 export function isDirectoryBoarded(claims) {
-    return (claims?.issuedVia === ISSUED_VIA_MCP_OAUTH ||
-        claims?.issuedVia === ISSUED_VIA_DEVICE_CODE);
+    // The set of boarding rails is the contract's, for the reason above: two
+    // copies of "which rails board an assistant" is how one of them goes stale.
+    return isDirectoryBoardedIssuedVia(claims?.issuedVia);
 }
 /** Routing hint only. Every request is still authenticated by the backend. */
 export function isMcpOAuthDelegateSession(creds) {

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementPartySide, AgreementParties, PrincipalPresentation, InboxDeliveryRef } from '@ziggs-ai/contracts';
 import type { InboxRequestChannel } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
@@ -37,6 +38,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';
@@ -94,6 +103,21 @@ export interface Task {
         steps?: PlanStep[];
     };
     planReview?: unknown;
+    /**
+     * When the answer stops being useful. At this point the holder
+     * posts what it has and where it is stuck, and stops. Absent or null on a
+     * task nobody has to chase.
+     */
+    dueAt?: string | null;
+    /**
+     * How often the holder may remind, and how many times at most.
+     * `everyMinutes` is a floor, not a schedule: remind later, never sooner.
+     * The budget is per person asked, after the first ask.
+     */
+    checkBack?: {
+        everyMinutes: number;
+        maxReminders: number;
+    } | null;
     history?: unknown[];
     creatorIsYou?: boolean;
     providerIsYou?: boolean;
@@ -111,30 +135,17 @@ export declare const AGREEMENT_ENGAGEMENT_KIND: {
 };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
 /**
- * One side of an agreement.
+ * One side of an agreement, as the wire carries it.
  *
- * An agent id occupies `actor` and nowhere else, so "is this agent on this
- * side?" is a structural read rather than a lookup against the Agent
- * collection. Asking `principal` about an agent id is always the wrong
- * question — it would match that agent's estate instead.
+ * `principal` is the accountable person or org — never an agent. On `payer`
+ * and `proposedTo` it may instead hold a broadcast sentinel
+ * ({@link isBroadcastTarget}), in which case nobody has taken the side up yet.
+ * `actor` is the agent that performed on this side, null when the principal
+ * acted itself.
  */
-export interface AgreementPartySide {
-    /**
-     * The accountable person or org — never an agent. On `payer` and `proposedTo`
-     * this may instead hold a broadcast sentinel ({@link isBroadcastTarget}), in
-     * which case nobody has taken the side up yet.
-     */
-    principal?: string | null;
-    /** The agent that performed on this side. Null when the principal acted itself. */
-    actor?: string | null;
-}
+export type { AgreementPartySide };
 /** The four sides of an agreement, each {@link AgreementPartySide}. */
-export interface AgreementParties {
-    payer?: AgreementPartySide;
-    provider?: AgreementPartySide;
-    proposedTo?: AgreementPartySide;
-    creator?: AgreementPartySide;
-}
+export type { AgreementParties };
 /** Both ids on one side, principal first, absent ones dropped. */
 export declare function partySideIds(side: AgreementPartySide | null | undefined): string[];
 /**
@@ -164,6 +175,8 @@ export interface AgreementApprovalEntry {
 }
 export interface Agreement {
     agreementId: string;
+    parentAgreementId?: string | null;
+    rootAgreementId?: string | null;
     description?: string;
     status?: AgreementStatus;
     engagementKind?: EngagementKind;
@@ -262,22 +275,7 @@ export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
 export declare function isBroadcastTarget(id: string | null | undefined): boolean;
 export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';
 /** Display + entitlement face for a principal on the message/roster wire. */
-export interface PrincipalPresentation {
-    /** Public, non-addressable reference (`psn_*` or `rpb_*`). */
-    ref?: string;
-    persona: {
-        id: string;
-        name: string;
-        image?: string | null;
-        revision?: number;
-    };
-    mode: 'persona' | 'chain';
-    /** Present only when the viewer is entitled to resolve the subject. */
-    subject?: {
-        id: string;
-        type: 'user' | 'agent';
-    };
-}
+export type { PrincipalPresentation };
 export interface MessageMetadata {
     chatId: string;
     /** Stable id for dedup across push + inbox catch-up. */
@@ -347,42 +345,8 @@ export interface InboxSourceRef {
     partyId: string;
     partyKind: InboxPartyKind;
 }
-/**
- * One row in this reader's merged view. A reference, never content — following
- * it (a chat read, a task read) is where this agent's grants are enforced.
- *
- * "Mine to act on" is `assigneeId === my agent id`, nothing else. A row
- * without my stamp is context I may read, never a wake and never mine to ack
- * as handled.
- */
-export interface InboxDeliveryRef {
-    kind: InboxDeliveryKind;
-    resourceId: string;
-    /** One emit, one id — copies of the same event collapse on this. */
-    eventId: string;
-    /** The mailbox this copy lives in. */
-    partyId: string;
-    partyKind: InboxPartyKind;
-    /** The ONE agent stamped to act; null when nothing has to. */
-    assigneeId: string | null;
-    /** The owner's human should see this. */
-    needsHuman: boolean;
-    chatId: string | null;
-    agreementId: string | null;
-    taskId: string | null;
-    /** Who wrote it. Never this agent — you are not woken by your own writes. */
-    actorId: string | null;
-    ts: string;
-    /**
-     * lifecycle hint when the server includes one (e.g.
-     * `connection_request_fulfilled`). Absent on ordinary doorbells / older servers.
-     */
-    reason?: string | null;
-    /** MCP connection after a fulfilled first-hop request. */
-    connectionId?: string | null;
-    /** grant minted for this agent on fulfill. */
-    grantId?: string | null;
-}
+/** One delivery in a mailbox, as the wire carries it. */
+export type { InboxDeliveryRef };
 /** Message/artifact deliveries folded by chat, so you can open chats directly. */
 export interface InboxChatNews {
     chatId: string;
@@ -512,3 +476,8 @@ export interface InboxAckResult {
 export interface InboxReadOptions {
     waitSeconds?: number;
 }
+/** Count-only peek. Does not take the inbox host lease. */
+export interface InboxPeek {
+    asOf: string;
+    count: number;
+}

package/dist/types.js

@@ -47,6 +47,7 @@ export function partySideIds(side) {
  * so widening the match to `principal` would hit an unrelated estate.
  */
 export function partyActorIds(parties) {
+    // The wire always sends all four sides; a caller may still hand us nothing.
     const p = parties ?? {};
     return [
         ...new Set(AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => typeof id === 'string' && id.length > 0)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "socket.io-client": "^4.7.0",
-    "@ziggs-ai/contracts": "^0.6.0"
+    "@ziggs-ai/contracts": "^0.7.1"
   },
   "keywords": [
     "ziggs",