@ziggs-ai/api-client 0.37.27 → 0.38.0

package/dist/inboxAck.d.ts

@@ -1,70 +1,38 @@
-/**
- * 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.
- */
+/** Observation and handling are independent. Only explicit responsibility IDs settle work. */
 export interface InboxAckEnvelope {
     ackTo?: string | null;
     deliveries?: ReadonlyArray<{
         resourceId?: string | null;
+        responsibilityId?: string | null;
         assigneeId?: string | null;
         outOfReach?: unknown;
-        /** ISO instant; the axis a mark moves along. */
+        executionBlocked?: unknown;
         ts?: string | null;
-        /** Mark covering this row and everything before it in this window. */
         ackTo?: string | null;
     }>;
     openRequestsAwaitingMe?: ReadonlyArray<{
         agreementId?: string | null;
+        responsibilityId?: string | null;
         ts?: string | null;
     }>;
 }
-export interface InboxAckDecision {
-    /** True when this envelope may be acknowledged. */
-    allowed: boolean;
-    handledResourceIds: string[];
-}
 export interface PlanInboxAckOptions {
-    /**
-     * Rows whose `assigneeId` equals this are mine. Empty or omitted: every
-     * delivery counts (the MCP tool with no configured self id).
-     */
     ownAgentId?: string;
     ownAgentIds?: readonly string[];
-    /** Failed handovers hold the watermark unless `forceAck`. */
     failures?: number;
     forceAck?: boolean;
 }
-/** Resource ids this envelope's ack must list. */
-export declare function inboxAckHandledIds(envelope: InboxAckEnvelope, ownAgentId?: string, ownAgentIds?: readonly string[]): string[];
-/** Whether an ack is allowed for this envelope, given handover state. */
-export declare function inboxAckAllowed(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): boolean;
-export declare function planInboxAck(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): InboxAckDecision;
-/** How far a reader may ack right now, mid-pass. */
+export interface InboxAckDecision {
+    allowed: boolean;
+    handledDeliveryIds: string[];
+}
 export interface InboxAckStep {
-    /** A row's own token — never one the client made up. */
     ackTo: string;
-    handledResourceIds: string[];
+    handledDeliveryIds: string[];
 }
-/**
- * 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 declare function inboxAckHandledIds(envelope: InboxAckEnvelope, ownAgentId?: string, ownAgentIds?: readonly string[]): string[];
+export declare function inboxAckAllowed(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): boolean;
+/** Full-pass helper: only use after every listed responsibility succeeded. */
+export declare function planInboxAck(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): InboxAckDecision;
+/** Successful jobs can be handled in any order, even when another job failed. */
 export declare function planPartialInboxAck(envelope: InboxAckEnvelope, handled: ReadonlySet<string>, opts?: PlanInboxAckOptions): InboxAckStep | null;

package/dist/inboxAck.js

@@ -1,111 +1,21 @@
-/**
- * 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, ownAgentIds) {
-    const mine = (assigneeId) => ownAgentIds ? ownAgentIds.includes(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);
+    const mine = (id) => ownAgentIds ? ownAgentIds.includes(id ?? '') : ownAgentId ? id === ownAgentId : !!id;
+    return [...new Set([
+            ...(envelope.deliveries ?? []).filter(d => mine(d.assigneeId) && !d.outOfReach && !d.executionBlocked).map(d => d.responsibilityId),
+            ...(envelope.openRequestsAwaitingMe ?? []).map(r => r.responsibilityId),
+        ].filter((id) => !!id))];
 }
-/** Whether an ack is allowed for this envelope, given handover state. */
 export function inboxAckAllowed(envelope, opts = {}) {
-    if (!envelope.ackTo)
-        return false;
-    const failures = opts.failures ?? 0;
-    if (failures > 0 && !opts.forceAck)
-        return false;
-    return true;
+    return !!envelope.ackTo && (!(opts.failures ?? 0) || !!opts.forceAck);
 }
+/** Full-pass helper: only use after every listed responsibility succeeded. */
 export function planInboxAck(envelope, opts = {}) {
-    return {
-        allowed: inboxAckAllowed(envelope, opts),
-        handledResourceIds: inboxAckHandledIds(envelope, opts.ownAgentId, opts.ownAgentIds),
-    };
-}
-/** Every row whose instant the server's bury-guard will ask about. */
-function gatingRows(envelope, ownAgentId, ownAgentIds) {
-    const mine = (assigneeId) => ownAgentIds ? ownAgentIds.includes(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);
+    return { allowed: inboxAckAllowed(envelope, opts), handledDeliveryIds: inboxAckHandledIds(envelope, opts.ownAgentId, opts.ownAgentIds) };
 }
-/**
- * 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.
- */
+/** Successful jobs can be handled in any order, even when another job failed. */
 export function planPartialInboxAck(envelope, handled, opts = {}) {
-    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, opts.ownAgentIds);
-    // 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)
+    if (!envelope.ackTo)
         return null;
-    const reached = upTo;
-    return {
-        ackTo: tokenByInstant.get(reached),
-        handledResourceIds: [
-            ...new Set(gating.filter((r) => r.ts <= reached).map((r) => r.id)),
-        ],
-    };
+    const ids = inboxAckHandledIds(envelope, opts.ownAgentId, opts.ownAgentIds).filter(id => handled.has(id));
+    return ids.length ? { ackTo: envelope.ackTo, handledDeliveryIds: ids } : null;
 }

package/dist/index.d.ts

@@ -34,3 +34,6 @@ export { AssistantConnectionClient, type AssistantWorkspace, type McpEventStatus
 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';
+export { withWorkExecution, withWorkExecutionId, currentWorkExecution, withoutExecution } from './http/operatorHeaders.js';
+export { deliveryHandlingId, type WorkExecutionContext, type WorkPositionView } from '@ziggs-ai/contracts';
+export { validateWorkExecution } from './http/ExecutionContextClient.js';

package/dist/index.js

@@ -32,3 +32,6 @@ export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHe
 // Short handles: T…, A…, C…, F… (task, agreement, chat, artifact).
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef } from './handles.js';
 export { describeOperationError } from './shared/operationError.js';
+export { withWorkExecution, withWorkExecutionId, currentWorkExecution, withoutExecution } from './http/operatorHeaders.js';
+export { deliveryHandlingId } from '@ziggs-ai/contracts';
+export { validateWorkExecution } from './http/ExecutionContextClient.js';

package/dist/types.d.ts

@@ -19,23 +19,10 @@ export declare class RateLimitedError extends ApiError {
     constructor(message: string, retryAfterMs: number | null, body?: string, code?: string | null);
 }
 export interface Creds {
+    executionContextId?: string;
     operatorKey: string;
     agentId: string;
-    /**
-     * the lane (chat id, or `agrn-<agreementId>`) this call is being
-     * made from. Sent as `X-Ziggs-Lane` so the backend can fence the wake to the
-     * engagement the agent is actually acting inside.
-     *
-     * The operator key says WHO is calling; this says ON WHOSE BEHALF, RIGHT NOW.
-     * Without it an agent serving several customers carries its full authority
-     * into every call, so a read spans every engagement it holds rather than
-     * staying inside the one being worked.
-     *
-     * Optional, and omitting it can only narrow what comes back (the backend
-     * falls back to the agent's own org) — never widen it. Nothing here is
-     * trusted: the server re-derives the party orgs itself and refuses a lane the
-     * agent is not in.
-     */
+    /** Presentation routing only; authority comes from the execution context. */
     laneId?: string;
     /**
      * This host's stable identity, sent as `X-Ziggs-Instance` on inbox reads and
@@ -380,6 +367,8 @@ export interface InboxChatNews {
     latestAt: string;
 }
 export interface InboxProposalRef {
+    executionContext?: import('@ziggs-ai/contracts').WorkExecutionContext;
+    executionBlocked?: import('@ziggs-ai/contracts').ExecutionBlock;
     agreementId: string;
     title: string;
     proposedAt: string | null;
@@ -441,6 +430,8 @@ export interface InboxHumanAttention {
  * agreement (or self-assigned) reached nobody.
  */
 export interface InboxTaskRef {
+    executionContext?: import('@ziggs-ai/contracts').WorkExecutionContext;
+    executionBlocked?: import('@ziggs-ai/contracts').ExecutionBlock;
     taskId: string;
     agreementId: string | null;
     title: string;
@@ -488,7 +479,7 @@ export interface InboxEnvelope extends InboxRequestChannel {
     /** This agent's ASSIGNED chat mail, folded by chat. */
     chats: InboxChatNews[];
     /**
-     * Opaque watermark bundle. Pass to `ack(upTo, { handledResourceIds })`
+     * Opaque watermark bundle. Pass to `ack(upTo, { handledDeliveryIds })`
      * VERBATIM after acting — never construct or parse one; the per-mailbox
      * positions live inside the value. Null when there is nothing to ack. Ack
      * after acting, not after reading: a crash in between redelivers. Listing
@@ -510,6 +501,14 @@ export interface InboxEnvelope extends InboxRequestChannel {
 export interface InboxAckResult {
     /** Where the watermark now sits. Monotonic — a rewind is a no-op, not an error. */
     ackedUpTo: string | null;
+    /**
+     * Handled ids the server left pending: assigned to you, but the work became
+     * unreadable or blocked before the ack. Every other id in the ack settled.
+     */
+    refusedDeliveryIds?: Array<{
+        id: string;
+        reason: string;
+    }>;
 }
 /**
  * Long-poll option shared by the inbox reads. The server holds the request up

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.27",
+  "version": "0.38.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -31,7 +31,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "^0.31.0",
+    "@ziggs-ai/contracts": "^0.32.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [