@ziggs-ai/agent-sdk 0.43.2 → 0.43.3

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.43.3
+
+- An agent no longer retries a wake for an agreement it cannot read. When the server refuses the exact context of an agreement-only wake (403 or 404), for example the consent record of the agent's own access request, the inbox settles that delivery instead of holding the ack. Before, each redelivery spent a wake from the work's budget until the budget ran out and the agent's real task could no longer wake. Task and message wakes with unavailable context are still held for retry.
+
 ## 0.43.2
 
 ## 0.43.1

package/dist/platform/ZiggsEffectHandler.js

@@ -20,9 +20,9 @@ const emptySnapshot = (agentId) => ({
     latestSequence: null,
 });
 async function buildSnapshot(deps, agentId, opts = {}) {
+    const scope = opts.workScope;
+    const via = opts.via ?? (scope?.taskId ? `task:${scope.taskId}` : scope?.agreementId ? `agreement:${scope.agreementId}` : scope?.messageId ? `message:${scope.messageId}` : scope?.artifactId ? `artifact:${scope.artifactId}` : undefined);
     try {
-        const scope = opts.workScope;
-        const via = opts.via ?? (scope?.taskId ? `task:${scope.taskId}` : scope?.agreementId ? `agreement:${scope.agreementId}` : scope?.messageId ? `message:${scope.messageId}` : scope?.artifactId ? `artifact:${scope.artifactId}` : undefined);
         if (!via)
             throw new Error('Context requires an explicit message, artifact, task or agreement');
         const agreementId = scope?.agreementId ?? (via.startsWith('agreement:') ? via.slice('agreement:'.length) : undefined);
@@ -71,7 +71,7 @@ async function buildSnapshot(deps, agentId, opts = {}) {
         // no world to act in. Leaving it as an empty snapshot used to run a
         // full turn against refusals.
         if (status === 404 || status === 403) {
-            return { ...emptySnapshot(agentId), unavailable: true, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Required context is unavailable. Do not start work without verified scope and access.' } };
+            return { ...emptySnapshot(agentId), unavailable: true, refused: true, refusedVia: via, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Required context is unavailable. Do not start work without verified scope and access.' } };
         }
         runtimeLog.warn('ZiggsEffectHandler', `snapshot fetch failed: ${err?.message ?? err}`);
         return { ...emptySnapshot(agentId), unavailable: true, work: { minimumComplete: false, authorization: { active: false }, instruction: 'Context read failed. Retry or request access before acting; an empty packet is not permission.' } };

package/dist/platform/inboxLoop.js

@@ -106,6 +106,13 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
             return true;
         }
         catch (err) {
+            // A refused agreement-only wake never recovers by redelivery, and every
+            // redelivery spends a wake from the work's budget. Settle it.
+            if (err?.code === 'REQUIRED_CONTEXT_UNAVAILABLE'
+                && err.settled === true) {
+                warn(label, `${what} settled without a turn: this agent cannot read that agreement`);
+                return true;
+            }
             failures++;
             forget?.();
             warn(label, `${what} was not handled: ${err?.message ?? err} — holding the ack`);

package/dist/runtime/requiredContext.d.ts

@@ -1,6 +1,15 @@
 /** A failed required read is retryable work, never a successfully handled wake. */
 export declare class RequiredContextUnavailable extends Error {
     readonly code = "REQUIRED_CONTEXT_UNAVAILABLE";
-    constructor();
+    /**
+     * The server refused an agreement-only wake outright (403/404): this agent is
+     * not on that agreement, e.g. the consent record of its own access request.
+     * Redelivery cannot change that, and each retry spends a wake, so the inbox
+     * settles it instead of holding the ack. A later grant arrives as its own event.
+     */
+    readonly settled: boolean;
+    constructor(opts?: {
+        settled?: boolean;
+    });
 }
 export declare function assertRequiredContext(snapshot: unknown): void;

package/dist/runtime/requiredContext.js

@@ -1,9 +1,17 @@
 /** A failed required read is retryable work, never a successfully handled wake. */
 export class RequiredContextUnavailable extends Error {
     code = 'REQUIRED_CONTEXT_UNAVAILABLE';
-    constructor() {
+    /**
+     * The server refused an agreement-only wake outright (403/404): this agent is
+     * not on that agreement, e.g. the consent record of its own access request.
+     * Redelivery cannot change that, and each retry spends a wake, so the inbox
+     * settles it instead of holding the ack. A later grant arrives as its own event.
+     */
+    settled;
+    constructor(opts = {}) {
         super('Required context is unavailable. Leave the responsibility pending until access or the read recovers.');
         this.name = 'RequiredContextUnavailable';
+        this.settled = opts.settled === true;
     }
 }
 export function assertRequiredContext(snapshot) {
@@ -18,6 +26,8 @@ export function assertRequiredContext(snapshot) {
     // authorization.active=false can be a readable proposal awaiting a decision.
     // Those packets still support recovery; operation/task policy gates new work.
     if (snapshot == null || root.unavailable === true || unavailable(root.work)) {
-        throw new RequiredContextUnavailable();
+        const settled = root.refused === true
+            && typeof root.refusedVia === 'string' && root.refusedVia.startsWith('agreement:');
+        throw new RequiredContextUnavailable({ settled });
     }
 }

package/dist/types.d.ts

@@ -367,6 +367,10 @@ export interface ContextSnapshot {
     timelineSummary?: string | null;
     latestSequence?: string | null;
     unavailable?: boolean;
+    /** The server refused the exact read (403/404), as opposed to a failed read. */
+    refused?: boolean;
+    /** The selector that was refused, e.g. `agreement:<id>`. */
+    refusedVia?: string;
     /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.43.2",
+  "version": "0.43.3",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {