@ziggs-ai/api-client 0.18.0 → 0.20.0

package/dist/inboxAck.js

@@ -0,0 +1,115 @@
+/**
+ * One answer for "what does this envelope's ack list, and may we send it?"
+ *
+ * The SDK loop and the MCP inbox tool both call this. The bury-guard is the
+ * same question on both rails: list every assigned row this reader actually
+ * handled, and do not ack a window that is incomplete or that failed in its
+ * hands.
+ */
+function isOutOfReach(note) {
+    if (!note || typeof note !== 'object')
+        return false;
+    const n = note;
+    return (typeof n.scopeKind === 'string' &&
+        typeof n.scopeId === 'string' &&
+        typeof n.remedy === 'string');
+}
+/** Resource ids this envelope's ack must list. */
+export function inboxAckHandledIds(envelope, ownAgentId) {
+    const mine = (assigneeId) => !ownAgentId || assigneeId === ownAgentId;
+    return [
+        ...new Set([
+            ...(envelope.deliveries ?? [])
+                .filter((d) => mine(d.assigneeId))
+                .filter((d) => !isOutOfReach(d.outOfReach))
+                .map((d) => d.resourceId),
+            ...(envelope.openRequestsAwaitingMe ?? []).map((q) => q.agreementId),
+        ]),
+    ].filter((id) => typeof id === 'string' && id.length > 0);
+}
+/** Whether an ack is allowed for this envelope, given handover state. */
+export function inboxAckAllowed(envelope, opts = {}) {
+    if (!envelope.ackTo)
+        return false;
+    if ((envelope.truncatedRequests ?? 0) !== 0)
+        return false;
+    const failures = opts.failures ?? 0;
+    if (failures > 0 && !opts.forceAck)
+        return false;
+    return true;
+}
+export function planInboxAck(envelope, opts = {}) {
+    return {
+        allowed: inboxAckAllowed(envelope, opts),
+        handledResourceIds: inboxAckHandledIds(envelope, opts.ownAgentId),
+    };
+}
+/** Every row whose instant the server's bury-guard will ask about. */
+function gatingRows(envelope, ownAgentId) {
+    const mine = (assigneeId) => !ownAgentId || assigneeId === ownAgentId;
+    return [
+        ...(envelope.deliveries ?? [])
+            .filter((d) => mine(d.assigneeId))
+            .filter((d) => !isOutOfReach(d.outOfReach))
+            .map((d) => ({ id: d.resourceId ?? '', ts: d.ts ?? '' })),
+        // Requests are projected out of `deliveries` for triage, but their rows
+        // are still in the log under the caller's stamp, so they gate a mark
+        // exactly as a delivery does.
+        ...(envelope.openRequestsAwaitingMe ?? []).map((q) => ({
+            id: q.agreementId ?? '',
+            ts: q.ts ?? '',
+        })),
+    ].filter((r) => r.id.length > 0 && r.ts.length > 0);
+}
+/**
+ * The furthest point in this envelope that is safe to ack RIGHT NOW, given what
+ * the reader has finished so far, or null when that is nowhere.
+ *
+ * Acking once at the end of a pass freezes the watermark for the whole pass,
+ * which is long enough for the stand-in's 90s takeover to elapse while the
+ * agent is still working. This lets the reader give the mark back in steps.
+ *
+ * The stopping point is a global instant, NOT the reader's current unit of
+ * work. A mark advances every source it names at once, so acking after one
+ * chat fold would bury an older row from a different chat — the guard would
+ * refuse it, correctly. So: walk the instants the server minted a token for,
+ * and stop at the last one where everything at or before it is handled.
+ * Anything else is either refused or a bug.
+ *
+ * Returns null when the server minted no per-row tokens, which is how an older
+ * backend is handled: the caller keeps its single end-of-pass ack.
+ */
+export function planPartialInboxAck(envelope, handled, opts = {}) {
+    if ((envelope.truncatedRequests ?? 0) !== 0)
+        return null;
+    const failures = opts.failures ?? 0;
+    if (failures > 0 && !opts.forceAck)
+        return null;
+    const tokenByInstant = new Map();
+    for (const d of envelope.deliveries ?? []) {
+        if (d.ts && d.ackTo)
+            tokenByInstant.set(d.ts, d.ackTo);
+    }
+    if (tokenByInstant.size === 0)
+        return null;
+    const gating = gatingRows(envelope, opts.ownAgentId);
+    // ISO-8601 sorts lexicographically in time order, which is what every other
+    // ts comparison on this rail already relies on.
+    const instants = [...tokenByInstant.keys()].sort();
+    let upTo = null;
+    for (const instant of instants) {
+        const settled = gating.every((r) => r.ts > instant || handled.has(r.id));
+        if (!settled)
+            break;
+        upTo = instant;
+    }
+    if (!upTo)
+        return null;
+    const reached = upTo;
+    return {
+        ackTo: tokenByInstant.get(reached),
+        handledResourceIds: [
+            ...new Set(gating.filter((r) => r.ts <= reached).map((r) => r.id)),
+        ],
+    };
+}

package/dist/index.d.ts

@@ -12,7 +12,11 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 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, InboxPeek, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
+export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
+export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from './inboxAck.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';
+export { sessionOrientation, } from './sessionOrientation.js';
+export type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson, SessionContinuation, SessionOrientation, SessionOrientationInput, } from './sessionOrientation.js';

package/dist/index.js

@@ -13,7 +13,9 @@ export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, }
 // half of them had drifted).
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
+export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.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';
+export { sessionOrientation, } from './sessionOrientation.js';

package/dist/instanceIdentity.d.ts

@@ -25,7 +25,7 @@ export declare function cliHostIdentity(): string;
  *
  * 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
+ * all of them on every deploy — a hosted read answering 409 for up to 220
  * 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

package/dist/instanceIdentity.js

@@ -4,7 +4,7 @@ import { decodeOperatorKeyClaims } from './shared/operatorKey.js';
  *
  * `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
+ * `409 INBOX_HOST_CONFLICT` until the owner has stopped renewing for 220
  * seconds, and an ack renews an owner but never acquires. A missing or
  * overlong value is `400 INBOX_HOST_REQUIRED`.
  *
@@ -71,7 +71,7 @@ export function cliHostIdentity() {
  *
  * 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
+ * all of them on every deploy — a hosted read answering 409 for up to 220
  * 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

package/dist/sessionOrientation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Who this session is, who it represents, and whether it can continue
+ * unattended. Built from the binding the caller already has. Does not
+ * read mail and does not take the inbox lease.
+ */
+export type InboxAckDriver = 'agent' | 'host';
+export type ContinuationKind = 'manual' | 'scheduled';
+export interface RepresentedPerson {
+    /** The human this agent acts for. Null when the key does not name one. */
+    id: string | null;
+    kind: 'user';
+}
+export interface SessionContinuation {
+    kind: ContinuationKind;
+    canScheduleWake: boolean;
+    summary: string;
+}
+export interface InboxHandling {
+    /** Who closes the inbox loop. Never both on the same identity. */
+    ackDriver: InboxAckDriver;
+    readAcquiresHost: true;
+    peekDoesNotAcquire: true;
+    peek: {
+        tool: string;
+        http: {
+            method: 'GET';
+            path: '/inbox/peek';
+        };
+    };
+}
+export interface SessionOrientation {
+    representedPerson: RepresentedPerson;
+    continuation: SessionContinuation;
+    inboxHandling: InboxHandling;
+    identity: {
+        agentId: string;
+        distinctFromBackgroundWorker: true;
+    };
+}
+export interface SessionOrientationInput {
+    agentId: string;
+    ownerUserId: string | null;
+    /** MCP assistants ack themselves. The hosted SDK host acks; the brain does not. */
+    surface: 'mcp' | 'sdk';
+}
+/**
+ * Facts a cold entry needs that `session.ownerId` never labelled: the
+ * represented person, whether this host can arm a wake, and who drives ack.
+ */
+export declare function sessionOrientation(input: SessionOrientationInput): SessionOrientation;

package/dist/sessionOrientation.js

@@ -0,0 +1,43 @@
+/**
+ * Who this session is, who it represents, and whether it can continue
+ * unattended. Built from the binding the caller already has. Does not
+ * read mail and does not take the inbox lease.
+ */
+const PEEK = {
+    tool: 'ziggs_inbox_peek',
+    http: { method: 'GET', path: '/inbox/peek' },
+};
+/**
+ * Facts a cold entry needs that `session.ownerId` never labelled: the
+ * represented person, whether this host can arm a wake, and who drives ack.
+ */
+export function sessionOrientation(input) {
+    const mcp = input.surface === 'mcp';
+    return {
+        representedPerson: {
+            id: input.ownerUserId,
+            kind: 'user',
+        },
+        continuation: mcp
+            ? {
+                kind: 'manual',
+                canScheduleWake: false,
+                summary: 'This MCP session has no wake_at. Continue by calling ziggs_inbox again — a scheduler in the host is the only unattended path.',
+            }
+            : {
+                kind: 'scheduled',
+                canScheduleWake: true,
+                summary: 'The hosted runtime can arm wake_at. The brain does not ack; the host owns the inbox loop.',
+            },
+        inboxHandling: {
+            ackDriver: mcp ? 'agent' : 'host',
+            readAcquiresHost: true,
+            peekDoesNotAcquire: true,
+            peek: PEEK,
+        },
+        identity: {
+            agentId: input.agentId,
+            distinctFromBackgroundWorker: true,
+        },
+    };
+}

package/dist/types.d.ts

@@ -442,6 +442,23 @@ export interface InboxEnvelope extends InboxRequestChannel {
     deliveries: InboxDeliveryRef[];
     /** True when there was more than one envelope's worth; the rest stay unacked. */
     deliveriesCapped: boolean;
+    /**
+     * How far behind this window is, when it stops short of the present. Null
+     * when it reaches it, and absent on older servers.
+     *
+     * The window is the oldest unacked rows: a reader that acks slides it
+     * forward every pass, and one that does not accumulates behind it. Hold this
+     * and you can never honestly report an empty inbox — say how far back you
+     * are looking, and ack to reach the rest.
+     */
+    backlog?: {
+        /** Unacked rows newer than `windowEndsAt`, across every mailbox. */
+        beyondWindow: number;
+        /** The newest unacked row anywhere in this view. */
+        newestAt: string | null;
+        /** The last row IN this window; everything after it is the backlog. */
+        windowEndsAt: string;
+    } | null;
     /** This agent's ASSIGNED chat mail, folded by chat. */
     chats: InboxChatNews[];
     /**

package/package.json

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