@ziggs-ai/api-client 0.37.28 → 0.38.0

package/dist/http/GrantsClient.js

@@ -12,22 +12,13 @@ export class GrantsClient {
     operatorKey;
     agentId;
     baseUrl;
-    laneId;
-    /**
-     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. The server reads off it who the agent is acting for, and
-     *   answers the spendable rails with only the grants this wake may spend —
-     *   so an agent serving several customers is never handed a list it has to
-     *   choose between. Without it the list is everything the agent holds, and
-     *   the grant it picks may then be refused with nothing saying why.
-     */
-    constructor(operatorKey, agentId, baseUrl, laneId) {
+    /** Authority is supplied by withWorkExecution / withWorkExecutionId. */
+    constructor(operatorKey, agentId, baseUrl) {
         if (!operatorKey)
             throw new Error('GrantsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
-        this.laneId = laneId;
     }
     async listGrants(query = {}) {
         const url = new URL(`${this.baseUrl}/grants`);
@@ -51,7 +42,7 @@ export class GrantsClient {
         if (query.limit != null)
             url.searchParams.set('limit', String(query.limit));
         const res = await fetch(url.toString(), {
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId),
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, undefined),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {

package/dist/http/InboxClient.d.ts

@@ -49,7 +49,7 @@ export declare class InboxClient {
      * refused.
      */
     ack(upTo: string, opts?: {
-        handledResourceIds?: string[];
+        handledDeliveryIds?: string[];
     }): Promise<InboxAckResult>;
     /** The person said to leave this proposal pending. Does not approve or reject. */
     park(agreementId: string): Promise<{
@@ -62,7 +62,7 @@ export declare class InboxClient {
      * A second host-conflict is a live competitor and is rethrown unchanged.
      */
     ackOrTakeHost(upTo: string, opts?: {
-        handledResourceIds?: string[];
+        handledDeliveryIds?: string[];
     }): Promise<InboxAckResult>;
     /**
      * Drop this process's inbox host lease so another client can take

package/dist/http/InboxClient.js

@@ -119,9 +119,7 @@ export class InboxClient {
             headers: this.headers(),
             body: JSON.stringify({
                 upTo,
-                ...(opts.handledResourceIds
-                    ? { handledResourceIds: opts.handledResourceIds }
-                    : {}),
+                ...(opts.handledDeliveryIds ? { handledDeliveryIds: opts.handledDeliveryIds } : {}),
             }),
         });
         const body = await res.text().catch(() => '');

package/dist/http/PaymentsClient.d.ts

@@ -61,21 +61,8 @@ export declare class PaymentsClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
-    private readonly laneId?;
-    /**
-     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the backend which hire this wake is in, and the
-     *   backend reads off it WHO the spend is for. An agent that serves several
-     *   hirers holds all of their grants at once and the holder is the same agent
-     *   in every one, so without a lane, spend authority one customer gave is
-     *   spendable while the agent works for another. ConnectionsClient and
-     *   ArtifactsClient send the same header for the same reason.
-     *
-     *   Omitting it cannot widen anything — a stated lane can only cause a
-     *   refusal — but it does leave the spend unfenced, so a caller that knows
-     *   its lane should pass it.
-     */
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
+    /** Authority is supplied by withWorkExecution / withWorkExecutionId. */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     balance(): Promise<WalletBalance>;
     resolve({ userId, agentId }?: {
         userId?: string;

package/dist/http/PaymentsClient.js

@@ -22,27 +22,13 @@ export class PaymentsClient {
     operatorKey;
     agentId;
     baseUrl;
-    laneId;
-    /**
-     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the backend which hire this wake is in, and the
-     *   backend reads off it WHO the spend is for. An agent that serves several
-     *   hirers holds all of their grants at once and the holder is the same agent
-     *   in every one, so without a lane, spend authority one customer gave is
-     *   spendable while the agent works for another. ConnectionsClient and
-     *   ArtifactsClient send the same header for the same reason.
-     *
-     *   Omitting it cannot widen anything — a stated lane can only cause a
-     *   refusal — but it does leave the spend unfenced, so a caller that knows
-     *   its lane should pass it.
-     */
-    constructor(operatorKey, agentId, baseUrl, laneId) {
+    /** Authority is supplied by withWorkExecution / withWorkExecutionId. */
+    constructor(operatorKey, agentId, baseUrl) {
         if (!operatorKey)
             throw new Error('PaymentsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
-        this.laneId = laneId;
     }
     async balance() {
         const w = (await this._get('/payments/wallet'));
@@ -87,7 +73,7 @@ export class PaymentsClient {
      * (retired GET /payments/grants), following the cursor to completion.
      */
     async listGrants() {
-        const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl, this.laneId);
+        const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
         return grants.listAllGrants({ scopeKind: 'wallet', health: 'active' });
     }
     async faucet({ amount, description = 'Faucet', idempotencyKey, } = {}) {
@@ -100,7 +86,7 @@ export class PaymentsClient {
     async _request(method, path, body) {
         const init = {
             method,
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId, body !== undefined ? { 'content-type': 'application/json' } : {}, this.laneId),
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, body !== undefined ? { 'content-type': 'application/json' } : {}),
         };
         if (body !== undefined)
             init.body = JSON.stringify(body);

package/dist/http/TelemetryClient.js

@@ -1,6 +1,6 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
+import { buildOperatorHeaders, withoutExecution } from './operatorHeaders.js';
 export class TelemetryClient {
     operatorKey;
     agentId;
@@ -36,9 +36,9 @@ export class TelemetryClient {
         try {
             const res = await fetch(url, {
                 method: 'POST',
-                headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                headers: withoutExecution(buildOperatorHeaders(this.operatorKey, this.agentId, {
                     'content-type': 'application/json',
-                }),
+                })),
                 body: JSON.stringify({ payload }),
             });
             if (!res.ok) {

package/dist/http/ToolPickClient.js

@@ -1,4 +1,4 @@
-import { buildCredsHeaders } from './operatorHeaders.js';
+import { buildCredsHeaders, withoutExecution } from './operatorHeaders.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 /** A listing is always the fallback, so waiting long for a pick buys nothing. */
 const TIMEOUT_MS = 6000;
@@ -15,7 +15,7 @@ export function backendToolPick(creds) {
         try {
             const res = await fetch(`${getBackendUrl()}/internal/tool-pick`, {
                 method: 'POST',
-                headers: buildCredsHeaders(creds),
+                headers: withoutExecution(buildCredsHeaders(creds)),
                 body: JSON.stringify({ need, options }),
                 signal: AbortSignal.timeout(TIMEOUT_MS),
             });

package/dist/http/index.d.ts

@@ -35,5 +35,5 @@ export { SessionsClient } from './SessionsClient.js';
 export type { AssistantSessionRow } from './SessionsClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from '../inboxAck.js';
-export { WAKE_LANE_HEADER, WAKE_AGREEMENT_HEADER, laneHeader, laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick, type ToolPickOption, type ToolPickAnswer, type PickTool } from './ToolPickClient.js';

package/dist/http/index.js

@@ -26,5 +26,5 @@ export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds,
 // The lane header, built in one place — see operatorHeaders.ts. Exported
 // because the MCP transports in agent-sdk and ziggs-mcp send it too, and a
 // copy of a header nobody notices missing goes stale unseen.
-export { WAKE_LANE_HEADER, WAKE_AGREEMENT_HEADER, laneHeader, laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick } from './ToolPickClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -1,4 +1,7 @@
+import type { WorkExecutionContext } from '@ziggs-ai/contracts';
 type AssistantHints = {
+    executionContext?: WorkExecutionContext;
+    executionContextId?: string;
     orgId?: string;
     resource?: string;
     clientSessionId?: string;
@@ -10,49 +13,24 @@ type AssistantHints = {
 /** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
 export declare function withAssistantRequest<T>(hints: AssistantHints, run: () => T): Promise<Awaited<T>>;
 export declare function assistantRequestHeaders(): Record<string, string>;
-/**
- * Auth headers for operator-key HTTP clients.
- *
- * ONE place builds them, because the lane is the header a caller cannot be
- * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
- * the wake to the agent's own org instead, so a door that forgets it answers
- * short lists and refuses grants the agent's customer gave it — silently, and
- * only for the agents that serve someone other than their owner. A header
- * whose absence is indistinguishable from a legitimate answer has to be built
- * in one place, not copied into each caller.
- */
-/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
-export declare const WAKE_LANE_HEADER = "X-Ziggs-Lane";
-/**
- * The header naming the agreement a room wake works under. The backend takes
- * it only for an agreement the agent has mail under in that room, and reads
- * it off that mail when it is absent.
- */
-export declare const WAKE_AGREEMENT_HEADER = "X-Ziggs-Agreement";
-/**
- * A room lane that also names the agreement the wake works under:
- * `<chatId>@<agreementId>`. Every client already carries the lane to
- * {@link laneHeader}, so the agreement travels with it without a second
- * parameter on each of them. An `agrn-` lane already is its agreement.
- */
+/** A presentation routing key; it carries no authority. */
 export declare function laneUnderAgreement(laneId: string, agreementId?: string | null): string;
+export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>): Record<string, string>;
 /**
- * The lane headers, or nothing. `laneId` is a chat id, `agrn-<agreementId>`
- * for a task with no origin chat, or a chat id with the agreement the wake
- * works under (`<chatId>@<agreementId>`, see {@link laneUnderAgreement}).
- */
-export declare function laneHeader(laneId?: string): Record<string, string>;
-export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 
-/**
- * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
- * backend narrows the wake's reach to the engagement's orgs; omitting it
- * narrows to the agent's own org, so it can never widen reach.
+ * The host's own calls (wake gate, telemetry, tool picker) are not work
+ * actions: they never carry the selected execution, so they neither need a
+ * route that supports one nor record anything into it.
  */
-laneId?: string): Record<string, string>;
+export declare function withoutExecution(headers: Record<string, string>): Record<string, string>;
 /** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
 export declare function buildCredsHeaders(creds: {
     operatorKey: string;
     agentId: string;
     laneId?: string;
+    executionContextId?: string;
 }): Record<string, string>;
+/** Async-local scope: parallel agreement positions never share request headers. */
+export declare function withWorkExecution<T>(executionContext: WorkExecutionContext | undefined, run: () => T): Promise<Awaited<T>>;
+export declare function currentWorkExecution(): WorkExecutionContext | undefined;
+export declare function withWorkExecutionId<T>(executionContextId: string | undefined, run: () => T): Promise<Awaited<T>>;
 export {};

package/dist/http/operatorHeaders.js

@@ -14,6 +14,7 @@ export async function withAssistantRequest(hints, run) {
 export function assistantRequestHeaders() {
     const hints = assistantRequest?.getStore();
     return {
+        ...((hints?.executionContextId ?? hints?.executionContext?.contextId) ? { 'X-Ziggs-Execution': (hints?.executionContextId ?? hints?.executionContext?.contextId) } : {}),
         ...(hints?.orgId ? { 'X-Workspace-Id': hints.orgId } : {}),
         ...(hints?.resource ? { 'X-Ziggs-Resource': hints.resource } : {}),
         ...(hints?.clientSessionId ? { 'X-Ziggs-Session': hints.clientSessionId } : {}),
@@ -23,73 +24,48 @@ export function assistantRequestHeaders() {
         ...(hints?.sessionName ? { 'X-Ziggs-Session-Name': hints.sessionName } : {}),
     };
 }
-/**
- * Auth headers for operator-key HTTP clients.
- *
- * ONE place builds them, because the lane is the header a caller cannot be
- * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
- * the wake to the agent's own org instead, so a door that forgets it answers
- * short lists and refuses grants the agent's customer gave it — silently, and
- * only for the agents that serve someone other than their owner. A header
- * whose absence is indistinguishable from a legitimate answer has to be built
- * in one place, not copied into each caller.
- */
-/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
-export const WAKE_LANE_HEADER = 'X-Ziggs-Lane';
-/**
- * The header naming the agreement a room wake works under. The backend takes
- * it only for an agreement the agent has mail under in that room, and reads
- * it off that mail when it is absent.
- */
-export const WAKE_AGREEMENT_HEADER = 'X-Ziggs-Agreement';
-/**
- * A room lane that also names the agreement the wake works under:
- * `<chatId>@<agreementId>`. Every client already carries the lane to
- * {@link laneHeader}, so the agreement travels with it without a second
- * parameter on each of them. An `agrn-` lane already is its agreement.
- */
+/** A presentation routing key; it carries no authority. */
 export function laneUnderAgreement(laneId, agreementId) {
     if (!agreementId || laneId.startsWith('agrn-') || laneId.includes('@'))
         return laneId;
     return `${laneId}@${agreementId}`;
 }
-/**
- * The lane headers, or nothing. `laneId` is a chat id, `agrn-<agreementId>`
- * for a task with no origin chat, or a chat id with the agreement the wake
- * works under (`<chatId>@<agreementId>`, see {@link laneUnderAgreement}).
- */
-export function laneHeader(laneId) {
-    if (!laneId)
-        return {};
-    const at = laneId.indexOf('@');
-    if (at <= 0)
-        return { [WAKE_LANE_HEADER]: laneId };
-    return {
-        [WAKE_LANE_HEADER]: laneId.slice(0, at),
-        [WAKE_AGREEMENT_HEADER]: laneId.slice(at + 1),
-    };
-}
-export function buildOperatorHeaders(operatorKey, agentId, extra, 
-/**
- * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
- * backend narrows the wake's reach to the engagement's orgs; omitting it
- * narrows to the agent's own org, so it can never widen reach.
- */
-laneId) {
+export function buildOperatorHeaders(operatorKey, agentId, extra) {
     return {
         Authorization: `Bearer ${operatorKey}`,
         ...assistantRequestHeaders(),
         // `X-Agent-Id` is only sent when an agentId is present — agent-scoped keys
         // identify the agent themselves; fleet keys must pass one.
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),
-        ...laneHeader(laneId),
         ...extra,
     };
 }
+/**
+ * The host's own calls (wake gate, telemetry, tool picker) are not work
+ * actions: they never carry the selected execution, so they neither need a
+ * route that supports one nor record anything into it.
+ */
+export function withoutExecution(headers) {
+    const out = { ...headers };
+    delete out['X-Ziggs-Execution'];
+    delete out['x-ziggs-execution'];
+    return out;
+}
 /** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
 export function buildCredsHeaders(creds) {
     return {
         'content-type': 'application/json',
-        ...buildOperatorHeaders(creds.operatorKey, creds.agentId, undefined, creds.laneId),
+        ...(creds.executionContextId ? { 'X-Ziggs-Execution': creds.executionContextId } : {}),
+        ...buildOperatorHeaders(creds.operatorKey, creds.agentId),
     };
 }
+/** Async-local scope: parallel agreement positions never share request headers. */
+export async function withWorkExecution(executionContext, run) {
+    return withAssistantRequest({ ...assistantRequest?.getStore(), executionContext, executionContextId: executionContext?.contextId }, run);
+}
+export function currentWorkExecution() {
+    return assistantRequest?.getStore()?.executionContext;
+}
+export async function withWorkExecutionId(executionContextId, run) {
+    return withAssistantRequest({ ...assistantRequest?.getStore(), executionContextId: executionContextId ?? assistantRequest?.getStore()?.executionContextId }, run);
+}

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