@ziggs-ai/api-client 0.33.0 → 0.34.0

package/dist/capabilities/agreementVerbs.js

@@ -171,7 +171,7 @@ export const agreementBuyCapability = {
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
-        parentAgreementId: { type: 'string', description: 'Governing agreement, including a link or negotiation agreement. This placement does not grant spending consent.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -203,7 +203,7 @@ export const agreementBidCapability = {
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
-        parentAgreementId: { type: 'string', description: 'Governing agreement, including a link or negotiation agreement. This placement does not grant spending consent.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -243,7 +243,7 @@ export const agreementBrokerCapability = {
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
-        parentAgreementId: { type: 'string', description: 'Governing agreement, including a link or negotiation agreement. This placement does not grant spending consent.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -274,7 +274,7 @@ export const agreementRequestCapability = {
         ...TERMS_PARAMS,
         match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
-        parentAgreementId: { type: 'string', description: 'Governing agreement, including a link or negotiation agreement. This placement does not grant spending consent.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {

package/dist/http/ContextReadClient.d.ts

@@ -105,6 +105,8 @@ export declare class ContextReadClient {
      *   intended. Send it on every read made while acting on a wake.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
+    /** The same reader acting on one wake's lane. */
+    withLane(laneId: string | undefined): ContextReadClient;
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
     /**
      * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The

package/dist/http/ContextReadClient.js

@@ -74,6 +74,12 @@ export class ContextReadClient {
         this.baseUrl = baseUrl || getBackendUrl();
         this.laneId = laneId;
     }
+    /** The same reader acting on one wake's lane. */
+    withLane(laneId) {
+        if (!laneId || laneId === this.laneId)
+            return this;
+        return new ContextReadClient(this.operatorKey, this.agentId, this.baseUrl, laneId);
+    }
     async read(type, query) {
         if (!query.via?.trim()) {
             throw new Error('ContextReadClient.read: via is required');

package/dist/shared/apiError.d.ts

@@ -31,9 +31,11 @@ export declare function parseErrorCode(responseBody: string): string | null;
 export declare function parseRetryAfterMs(headers: {
     get(name: string): string | null;
 }): number | null;
+export declare function isCoverageRefusal(code: string | null | undefined): boolean;
 /**
  * Throw the parsed failure as an {@link ApiError} (or {@link RateLimitedError}
- * for 429), preserving status, body, machine code, and Retry-After.
+ * for a 429 that is not a coverage refusal), preserving status, body, machine
+ * code, and Retry-After.
  */
 export declare function throwApiError(response: {
     status: number;

package/dist/shared/apiError.js

@@ -100,14 +100,34 @@ function clampRetryMs(ms) {
         return 1_000;
     return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, Math.round(ms)));
 }
+/**
+ * Coverage refusals name themselves. A 429 with one of these codes is not a
+ * wait-and-retry: the writer has to hire, or someone has to set the agreement
+ * up. The backend answers them as 403; this keeps a stale 429 from becoming a
+ * rate limit too.
+ */
+const COVERAGE_REFUSALS = new Set([
+    'CONVERSATION_ALLOWANCE_EXHAUSTED',
+    'CONTACT_POLICY_REFUSED',
+    'LISTING_PAUSED',
+    'CONVERSATION_COVERAGE_REQUIRED',
+    'CONVERSATION_COVERAGE_ENDED',
+    'CONVERSATION_NOT_FUNDED',
+    'CONVERSATION_SPONSORSHIP_REQUIRED',
+    'TASK_ONLY_AGENT',
+]);
+export function isCoverageRefusal(code) {
+    return !!code && COVERAGE_REFUSALS.has(code);
+}
 /**
  * Throw the parsed failure as an {@link ApiError} (or {@link RateLimitedError}
- * for 429), preserving status, body, machine code, and Retry-After.
+ * for a 429 that is not a coverage refusal), preserving status, body, machine
+ * code, and Retry-After.
  */
 export function throwApiError(response, responseBody, defaultMessage) {
     const message = parseErrorMessage(responseBody, defaultMessage);
     const code = parseErrorCode(responseBody);
-    if (response.status === 429) {
+    if (response.status === 429 && !isCoverageRefusal(code)) {
         throw new RateLimitedError(message, response.headers ? parseRetryAfterMs(response.headers) : null, responseBody, code);
     }
     throw new ApiError(message, response.status, responseBody, code);

package/dist/shared/rateLimit.js

@@ -1,5 +1,5 @@
 import { ApiError, RateLimitedError } from '../types.js';
-import { parseErrorCode, parseErrorMessage, parseRetryAfterMs, } from './apiError.js';
+import { isCoverageRefusal, parseErrorCode, parseErrorMessage, parseRetryAfterMs, } from './apiError.js';
 /**
  * a 429 is not a generic failure, it is an instruction with a
  * deadline attached.
@@ -33,7 +33,7 @@ export function isRateLimited(err) {
 export function pollSurfaceError(label, res, body) {
     const message = parseErrorMessage(body, `${label} failed: ${res.status}`);
     const code = parseErrorCode(body);
-    if (res.status === 429) {
+    if (res.status === 429 && !isCoverageRefusal(code)) {
         return new RateLimitedError(message, parseRetryAfterMs(res.headers), body, code);
     }
     return new ApiError(message, res.status, body, code);

package/package.json

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