@ziggs-ai/api-client 0.37.17 → 0.37.18

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 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.

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',

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