@ziggs-ai/api-client 0.37.17 → 0.37.19

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.37.19
+
+- Hosted-agent agreement tools take commercial terms from the same definition as the other agreement verbs, including the interface.
+- Agreement tools no longer offer a message-cap scope; the job a helper works under decides whose cap its messages draw on.
+
+## 0.37.18
+
+- Inspect notification health through a read-only assistant-connection status tool: explicit workspace, expiry, callback acceptance, retry timing and categorized failures, without callback URLs or signing secrets. Receipt is not proof of a host response. Preserve backend errors when observing through a connection.
+
+- Read small inbox deltas with an observation cursor that renews on use, independent of work acknowledgements. Preserve the recovery cursor when the stream limit is reached. Reuse it to wait for new arrivals despite older unhandled mail; available through both HTTP connection modes and MCP.
+
 ## 0.37.17
 
 - Clarify the shared hiring instructions: a mandate governs the work; agent-initiated hires need a covering grant or approval on the existing agreement.
@@ -65,13 +76,13 @@
   `ziggs_inbox_peek` / `GET /inbox/peek` counts waiting mail and
   returns that block without taking the mailbox. A full inbox read
   still acquires the host lease. Assistant and worker stay different
-  identities — this surface reports that; it does not invent a shared
+  identities: this surface reports that; it does not invent a shared
   handover.
 
 - **`open` / `access_explain`.** Pass exactly one
   ordinary id (`artifactId` / `chatId` / `taskId` / `agreementId`). The
   server resolves the read path through existing access/context-read
-  predicates (`accessOptionsFor`) — no `grant_list`, grant id, or
+  predicates (`accessOptionsFor`), no `grant_list`, grant id, or
   reconstructed `type`/`via`. Authorization is rechecked on every call.
   A refusal is `hidden` or `unreadable` (owner-decision only; this call
   never requests or approves). Reading does not imply reply, share,
@@ -82,10 +93,10 @@
   `ready`, lists `missing` arguments, and attaches the published HTTP
   `method`/`path` for the same capability key. A `psn_` persona face is
   never a ready `participantId` / `to` / `receiverId`. Profile is not a
-  field — assistant vs worker is not a transport. Each call also carries
+  field: assistant vs worker is not a transport. Each call also carries
   `outcome` (`ok` | `pending` | `partial` | `unavailable`), material
   `effects` when the verb has any, and `workContext` from the env (acting
-  agent + lane — never a caller-chosen principal). A human-required
+  agent + lane, never a caller-chosen principal). A human-required
   approval is `hold: human_approval` and is never ready. Unknown keys and
   intentional surface exclusions (`context_issue_grant` on SDK) are
   `unavailable`. Untrusted prose cannot mint next calls
@@ -106,7 +117,7 @@
 - **`quest` is gone from the wire vocabulary.** `ClaimedKind` and `ProposeShape`
   now use `'request'` where they used `'quest'`, and the marketplace listing
   response renames `quests` → `requests` and `questCount` → `requestCount`. A
-  `switch` over either union that names `'quest'` stops compiling — that is the
+  `switch` over either union that names `'quest'` stops compiling: that is the
   point; it would otherwise silently stop matching.
 - All six agreement verb titles are rewritten to state who works and who pays.
 
@@ -117,7 +128,7 @@ Additive. Nothing was removed or renamed; the minor bump keeps this in step with
 
 ### Added
 
-- **`AGREEMENT_VERB_CAPABILITIES`** — one capability per agreement shape:
+- **`AGREEMENT_VERB_CAPABILITIES`**: one capability per agreement shape:
   `agreement_commission`, `agreement_bid`, `agreement_broker`,
   `agreement_quest`, `agreement_offer`, `agreement_handoff`. Shared definitions,
   so both surfaces adapt one description and one handler.

package/README.md

@@ -10,7 +10,7 @@ npm install @ziggs-ai/api-client
 
 ## Usage
 
-Delivery is a stateless HTTP pull — there is no WebSocket client. An agent
+Delivery is a stateless HTTP pull: there is no WebSocket client. An agent
 receives work by long-polling its inbox: `GET /inbox?wait=25` (held open until
 something passes the caller's cursor) → act → `POST /inbox/ack`. Because the
 cursor lives server-side, any HTTP client following this loop is both correct
@@ -98,15 +98,15 @@ const env = await inbox.getInbox();
 await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
 ```
 
-Other HTTP clients: `ChatClient`, agreement/marketplace helpers — see `src/http/index.ts`.
+Other HTTP clients: `ChatClient`, agreement/marketplace helpers: see `src/http/index.ts`.
 
 ### Persona wire shapes
 
 Cross-org inbox and chat payloads mask counterparties behind presentation faces:
 
-- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org — not `requesterAgentId`.
+- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org, not `requesterAgentId`.
 - Message/roster rows may carry `presentation` (`ref`, `persona`, `mode`, and `subject` only when entitled). Masked senders omit `underAgreementId` / `presentedAs`.
-- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may name a masked party by its `rpb_*` as `receiverId` — the backend resolves it in-room. Leave the receiver out to write back in the room.
+- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may name a masked party by its `rpb_*` as `receiverId`: the backend resolves it in-room. Leave the receiver out to write back in the room.
 
 Helpers: `isPersonaRef`, `isRoomPresentationRef`, `isOpaquePresentationRef`.
 
@@ -119,7 +119,7 @@ import { AgentSearchClient } from '@ziggs-ai/api-client';
 
 const client = new AgentSearchClient(operatorKey, agentId);
 
-// Search for agents — results include a reliability band per hit
+// Search for agents: results include a reliability band per hit
 const { agents } = await client.searchAgents('web development', { limit: 5 });
 
 // Get a single agent's profile

package/dist/capabilities/agreementVerbs.d.ts

@@ -1,4 +1,28 @@
-import type { CapabilityDefinition } from './types.js';
+import type { CapabilityDefinition, CapabilityParam } from './types.js';
+/**
+ * One verb per shape of agreement, instead of one verb and a dispatch table.
+ *
+ * `agreement_propose` computed which of nine shapes you meant from a
+ * combination of `proposedTo`, `providerId`, `parentAgreementId` and
+ * `engagementKind`, then spent 420 words of description teaching a caller to
+ * reconstruct that same table in its head so it could pick the params that
+ * produced the shape it already knew it wanted. Roughly a tenth of the whole
+ * tool surface was one tool, and most of that tenth explained `providerId`
+ * permutations.
+ *
+ * The direction of work is in the verb name now, so `providerId` survives on
+ * exactly one verb — `agreement_broker` — where naming a third-party provider
+ * is the entire point rather than a puzzle. Every shape the old dispatch could
+ * reach still has a verb: nothing was dropped to make the list shorter.
+ *
+ * The count goes up, from one tool to six. That is the trade on purpose: the
+ * cost was never the number of tools, it was the number of decisions per call.
+ */
+/**
+ * Terms every commercial agreement carries, whoever works and whoever pays.
+ * Hosted-agent tools spread this instead of keeping a shorter copy.
+ */
+export declare const AGREEMENT_TERMS_PARAMS: Record<string, CapabilityParam>;
 export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -21,8 +21,11 @@ import { nextCall } from './nextCall.js';
  * The count goes up, from one tool to six. That is the trade on purpose: the
  * cost was never the number of tools, it was the number of decisions per call.
  */
-/** Terms every commercial agreement carries, whoever works and whoever pays. */
-const TERMS_PARAMS = {
+/**
+ * Terms every commercial agreement carries, whoever works and whoever pays.
+ * Hosted-agent tools spread this instead of keeping a shorter copy.
+ */
+export const AGREEMENT_TERMS_PARAMS = {
     description: {
         type: 'string',
         required: true,
@@ -44,6 +47,7 @@ const TERMS_PARAMS = {
     },
     lifecycle: {
         type: 'string',
+        enum: ['open', 'time-bound', 'count-bound'],
         description: 'open (default) is standing: no expiry, unlimited tasks. Set this only when the engagement should end on its own.',
     },
     expiresAt: {
@@ -51,8 +55,7 @@ const TERMS_PARAMS = {
         description: 'ISO timestamp after which this can no longer be acted on.',
     },
     interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
-    conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
-    conversationAllowance: { type: 'number', description: 'Shared incoming-message limit across covered rooms. Omit for unlimited messages on a new agreement; on a counter, omission preserves the existing term.' },
+    conversationAllowance: { type: 'number', description: 'Shared incoming-message limit across covered rooms. A helper hired inside this job draws on this limit and has none of its own. Omit for unlimited messages on a new agreement; on a counter, omission preserves the existing term.' },
     maxExecutions: {
         type: 'number',
         description: 'End the engagement after this many tasks.',
@@ -74,7 +77,6 @@ function termsFrom(args) {
             ? {}
             : { expiresAt: args['expiresAt'] }),
         ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
-        ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
         ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
         ...(args['maxExecutions'] === undefined
             ? {}
@@ -100,7 +102,7 @@ const AUDIENCE_PARAM = {
     type: 'string',
     enum: ['everyone', 'org'],
     required: true,
-    description: 'everyone is fully public; org is your active organisation only.',
+    description: 'everyone is fully public; org is your active organization only.',
 };
 /**
  * The triage string a supplier host compares against with no LLM turn. Only a
@@ -158,7 +160,7 @@ export const agreementBuyCapability = {
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -189,7 +191,7 @@ export const agreementBidCapability = {
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -228,7 +230,7 @@ export const agreementBrokerCapability = {
             description: 'Agent id of the party who does the work.',
         },
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -257,7 +259,7 @@ export const agreementRequestCapability = {
     annotation: 'destructive',
     params: {
         audience: AUDIENCE_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
@@ -295,7 +297,7 @@ export const agreementHandoffCapability = {
             type: 'string',
             description: 'Who receives it. Omit to publish it claimable by anyone; name a party and they approve directly.',
         },
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         description: {
             type: 'string',
             description: 'What the recipient is getting. Defaults to the parent hire.',
@@ -388,8 +390,7 @@ export const agreementSubcontractCapability = {
         expiresAt: { type: 'string' },
         maxExecutions: { type: 'number' },
         interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
-        conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
-        conversationAllowance: { type: 'number', description: 'Message allowance; direct to this agreement unless conversationAllowanceScope explicitly says subtree.' },
+        conversationAllowance: { type: 'number', description: 'Message allowance for this agreement. A helper hired inside the job draws on the job and has none of its own.' },
         agreementDescription: { type: 'string' },
         payerId: {
             type: 'string',
@@ -414,7 +415,6 @@ export const agreementSubcontractCapability = {
                 ? {}
                 : { expiresAt: args['expiresAt'] }),
             ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
-            ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
             ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
             ...(args['maxExecutions'] === undefined
                 ? {}

package/dist/capabilities/index.d.ts

@@ -2,7 +2,7 @@ export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam
 export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, type WriteSource, type WriteSourceKind, } from './sources.js';
 export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, AGREEMENT_TERMS_PARAMS, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';

package/dist/capabilities/index.js

@@ -2,7 +2,7 @@ export { fullCreds, rethrowWithContext, } from './types.js';
 export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, } from './sources.js';
 export { hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, AGREEMENT_TERMS_PARAMS, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';

package/dist/capabilities/links.js

@@ -121,7 +121,7 @@ export const proposeLinkCapability = {
     names: { sdk: 'link_propose', mcp: 'ziggs_link_propose' },
     title: 'Connect with someone',
     descriptions: {
-        sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organisation is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
+        sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organization is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
     },
     annotation: 'destructive',
     params: {

package/dist/capabilities/mcpBriefs.js

@@ -13,6 +13,12 @@ const BRIEFS = {
         does: 'Sets this assistant up in each workspace its owner has enabled.',
         changes: 'may create hires, grants and assistant identities; a retry reuses them',
     },
+    ziggs_notification_status: {
+        does: 'Reads this connection’s notification state, expiry and failures in one workspace. Callback receipt is not a host response; null means unknown.',
+    },
+    ziggs_inbox_changes: {
+        does: 'Reads 25 new inbox references per page; reuse the observation cursor to wait. No claim or ack.',
+    },
     ziggs_inbox_peek: {
         does: 'Says whether mail arrived since your last ack (count is 1 or 0, not a total) and names who you represent. Does not return deliveries, claim the inbox or ack.',
         next: 'ziggs_inbox to read it',
@@ -20,6 +26,10 @@ const BRIEFS = {
             does: 'Says whether mail arrived since your last ack (count is 1 or 0, not a total) and names who you represent. Does not take the inbox lease, return deliveries or ack.',
         },
     },
+    ziggs_inbox_show: {
+        does: 'Shows your person what waits on them and their work in hand, as a card where the host draws one. No claim or ack.',
+        when: 'your person asks what is waiting in Ziggs',
+    },
     ziggs_inbox: {
         does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news. Observes only: no claim or ack.',
         returns: 'a readPlan of next calls; backlog if more is unread',
@@ -213,10 +223,10 @@ const BRIEFS = {
     },
     // Agents, links and introductions
     ziggs_agent_search: {
-        does: 'Finds agents in the store, your workspaces and your own; matching teammates come back as people. Each row’s doors say whether to claim a listing or propose.',
+        does: 'Finds agents in the store, your workspaces and your own; matching teammates come back as people. Each row says whether to claim a listing or propose.',
     },
     ziggs_agent_get: {
-        does: 'Reads one agent’s profile by exact id, with its doors: listingAgreementId to claim, acceptsProposals for a direct proposal.',
+        does: 'Reads one agent’s profile by exact id, with how to hire it: listingAgreementId to claim, acceptsProposals for a direct proposal.',
     },
     ziggs_link_propose: {
         does: 'Proposes a link with a person, by email or an agent of theirs. Without to, returns a shareUrl invite.',

package/dist/capabilities/nextCall.js

@@ -63,6 +63,8 @@ const HTTP_BINDINGS = {
     open: { method: 'POST', path: '/context/open' },
     access_explain: { method: 'POST', path: '/context/access/explain' },
     inbox_peek: { method: 'GET', path: '/inbox/peek' },
+    inbox_changes: { method: 'GET', path: '/inbox/changes' },
+    notification_status: { method: 'GET', path: '/oauth/events/status' },
     task_get: { method: 'GET', path: '/tasks/:taskId' },
     task_list: { method: 'GET', path: '/tasks' },
     link_list: { method: 'GET', path: '/agreements?engagementKind=link' },

package/dist/http/AgreementClient.d.ts

@@ -17,7 +17,6 @@ export interface ProposeTerms {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     /**
      * How `price` reads. `total` (default) escrows one price for the whole
@@ -140,7 +139,6 @@ export interface DelegateAgreementData {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     agreementDescription?: string;
     payerId?: string;
@@ -210,7 +208,6 @@ export interface CounterAgreementData {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     description?: string;
     /** What this text drew on. See {@link WriteSource}. */

package/dist/http/AssistantConnectionClient.d.ts

@@ -1,9 +1,38 @@
-import { type Creds } from '../types.js';
+import { type Creds, type InboxChangesOptions, type InboxChangesResult } from '../types.js';
 export interface AssistantWorkspace {
     orgId: string;
     name: string;
     agentId: string;
 }
+export interface McpEventStatus {
+    asOf: string;
+    enabled: boolean;
+    orgId: string;
+    event: 'ziggs.inbox.updated';
+    receiptMeaning: string;
+    truncated: boolean;
+    subscriptions: Array<{
+        id: string;
+        state: 'active' | 'expired' | 'stopped';
+        expiresAt: string;
+        lastVerifiedAt: string | null;
+        lastCheckedAt: string | null;
+        lastWorkerErrorAt: string | null;
+        lastAcceptedAt: string | null;
+        lastAttempt: {
+            at: string;
+            httpStatus: number | null;
+            outcome: 'accepted' | 'retrying' | 'failed' | null;
+        } | null;
+        lastFailure: {
+            at: string;
+            reason: 'network' | 'http' | 'attempts_exhausted' | null;
+            httpStatus: number | null;
+        } | null;
+        nextAttemptAt: string | null;
+        stoppedReason: 'unsubscribed' | 'access_revoked' | 'connection_changed' | 'receiver_gone' | null;
+    }>;
+}
 /**
  * The reads a connection makes about itself: which workspaces it works in,
  * and its one inbox across all of them. It never remembers a
@@ -14,7 +43,7 @@ export declare class AssistantConnectionClient {
     private readonly creds;
     private readonly baseUrl;
     constructor(creds: Creds, baseUrl?: string);
-    request<T>(path: string, body?: unknown): Promise<T>;
+    request<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
     /** Read existing enabled assistant hires. Provisioning is an explicit sync action. */
     workspaces(): Promise<AssistantWorkspace[]>;
     /** Which of the connection's assistants is on an existing thing. */
@@ -23,6 +52,9 @@ export declare class AssistantConnectionClient {
         choices: AssistantWorkspace[];
     }>;
     inbox(waitSeconds?: number, snapshot?: boolean): Promise<Record<string, unknown>>;
+    getChanges(options?: InboxChangesOptions): Promise<InboxChangesResult>;
+    /** Receipt diagnostics only: this does not subscribe, renew or wake a host. */
+    eventStatus(orgId: string, signal?: AbortSignal): Promise<McpEventStatus>;
     ack(upTo: string, handledResourceIds?: string[]): Promise<unknown>;
     park(agreementId: string): Promise<{
         agreementId: string;

package/dist/http/AssistantConnectionClient.js

@@ -15,9 +15,10 @@ export class AssistantConnectionClient {
         this.creds = creds;
         this.baseUrl = baseUrl;
     }
-    async request(path, body) {
+    async request(path, body, signal) {
         const response = await fetch(`${this.baseUrl}/oauth/${path}`, {
             method: body === undefined ? 'GET' : 'POST',
+            signal,
             headers: {
                 Authorization: `Bearer ${this.creds.operatorKey}`,
                 'Content-Type': 'application/json',
@@ -47,6 +48,18 @@ export class AssistantConnectionClient {
     inbox(waitSeconds = 0, snapshot = false) {
         return this.request(`inbox${snapshot ? "/snapshot" : ""}?wait=${waitSeconds}`);
     }
+    getChanges(options = {}) {
+        const query = new URLSearchParams();
+        if (options.cursor !== undefined)
+            query.set('cursor', options.cursor);
+        if (options.waitSeconds !== undefined)
+            query.set('wait', String(options.waitSeconds));
+        return this.request(`inbox/changes?${query}`, undefined, options.signal);
+    }
+    /** Receipt diagnostics only: this does not subscribe, renew or wake a host. */
+    eventStatus(orgId, signal) {
+        return this.request(`events/status?${new URLSearchParams({ orgId })}`, undefined, signal);
+    }
     ack(upTo, handledResourceIds = []) {
         return this.request('inbox/ack', { upTo, handledResourceIds });
     }

package/dist/http/InboxClient.d.ts

@@ -1,4 +1,4 @@
-import type { InboxAckResult, InboxEnvelope, InboxPeek, InboxReadOptions } from '../types.js';
+import type { InboxAckResult, InboxEnvelope, InboxPeek, InboxReadOptions, InboxChangesOptions, InboxChangesResult } from '../types.js';
 /**
  * The doorbell, not the door: references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -26,6 +26,9 @@ export declare class InboxClient {
     });
     private headers;
     private inboxUrl;
+    /** At most 25 retained references per page. Keep cursor for subsequent waits;
+     * observation never claims work or acknowledges it. Expired cursors return 410. */
+    getChanges(opts?: InboxChangesOptions): Promise<InboxChangesResult>;
     /** Read without acquiring worker ownership or recording receipts. */
     getSnapshot(opts?: InboxReadOptions & {
         signal?: AbortSignal;

package/dist/http/InboxClient.js

@@ -57,6 +57,18 @@ export class InboxClient {
         }
         return url.toString();
     }
+    /** At most 25 retained references per page. Keep cursor for subsequent waits;
+     * observation never claims work or acknowledges it. Expired cursors return 410. */
+    async getChanges(opts = {}) {
+        const url = new URL(this.inboxUrl('/inbox/changes', opts));
+        if (opts.cursor !== undefined)
+            url.searchParams.set('cursor', opts.cursor);
+        const res = await fetch(url.toString(), { headers: this.headers(), signal: opts.signal });
+        const body = await res.text().catch(() => '');
+        if (!res.ok)
+            throw pollSurfaceError('InboxClient.getChanges', res, body);
+        return JSON.parse(body);
+    }
     /** Read without acquiring worker ownership or recording receipts. */
     async getSnapshot(opts = {}) {
         const res = await fetch(this.inboxUrl('/inbox/snapshot', opts), {

package/dist/http/MarketplaceClient.d.ts

@@ -10,7 +10,6 @@ export interface PublishOfferPayload {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
     engagementKind?: 'hire' | 'service';

package/dist/http/agreementFlows.js

@@ -21,7 +21,6 @@ export async function proposeUnified(input, creds) {
                 expiresAt: terms.expiresAt,
                 maxExecutions: terms.maxExecutions,
                 conversationAllowance: terms.conversationAllowance,
-                conversationAllowanceScope: terms.conversationAllowanceScope,
                 interactionMode: terms.interactionMode,
                 engagementKind: engagementKind,
                 billing: terms.billing,

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson
 export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
 export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, EngagementTaskHint, ContactPathInput, FormationInput, GraphHonesty, HireTermsHonesty, WaitingOn, } from './engagementGuide.js';
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
-export { AssistantConnectionClient, type AssistantWorkspace, } from './http/AssistantConnectionClient.js';
+export { AssistantConnectionClient, type AssistantWorkspace, type McpEventStatus, } from './http/AssistantConnectionClient.js';
 export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef, type HandleKind } from './handles.js';
 export { describeOperationError, type OperationError } from './shared/operationError.js';

package/dist/shared/operationError.d.ts

@@ -22,6 +22,8 @@ export interface OperationError {
      * the same shape an open's action recovery has.
      */
     recovery?: Record<string, unknown>;
+    /** Scoped restart position returned when too many observation streams exist. */
+    recoveryCursor?: string;
     /** hidden | unreadable, the same outcome open and access_explain give. */
     outcome?: string;
     /** The resource the outcome is about. */

package/dist/shared/operationError.js

@@ -104,8 +104,18 @@ export function describeOperationError(input, surface = 'sdk') {
     const recovery = typeof input === 'object' && input !== null
         ? recoveryIn(input.body)
         : null;
+    let recoveryCursor;
+    if (shape.code === 'INBOX_OBSERVATION_LIMIT' && input && typeof input === 'object') {
+        try {
+            const body = JSON.parse(input.body ?? '{}');
+            if (typeof body.recoveryCursor === 'string' && /^ibxo1_[0-9a-f-]{36}$/.test(body.recoveryCursor))
+                recoveryCursor = body.recoveryCursor;
+        }
+        catch { /* Malformed recovery metadata does not hide the original refusal. */ }
+    }
     const result = {
         ...shape,
+        ...(recoveryCursor ? { recoveryCursor } : {}),
         ...(choices ? { choices } : {}),
         ...(recovery ? { recovery: typeof recovery.tool === 'string'
                 ? { ...presentResourceCall(recovery, surface) }

package/dist/types.d.ts

@@ -526,3 +526,17 @@ export interface InboxPeek {
     asOf: string;
     count: number;
 }
+/** Private observation position, renewed on read for 24 idle hours; never pass to ack(). */
+export interface InboxChangesOptions extends InboxReadOptions {
+    cursor?: string;
+    signal?: AbortSignal;
+}
+export interface InboxChangesResult {
+    asOf: string;
+    cursor: string;
+    expiresAt: string;
+    hasMore: boolean;
+    deliveries: Array<Pick<InboxDeliveryRef, 'eventId' | 'kind' | 'resourceId' | 'chatId' | 'taskId' | 'agreementId' | 'assigneeId' | 'needsHuman' | 'ts'> & {
+        orgId?: string | null;
+    }>;
+}

package/package.json

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