@ziggs-ai/api-client 0.40.0 → 0.40.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.40.2
+
+- A task on an agreement priced at completion with no stated charge is free; the outcome's metering line says so. `charge` docs say the same.
+
+## 0.40.1
+
+- `updateTaskState` takes `charge: { amount, basis? }` with `completed`: what the task cost and what that rests on. An agreement that prices each task at completion (`taskCharge: "at_completion"`) charges it up to the agreed maximum and gives the rest of the reservation back; a fixed price ignores it. The task outcome's metering line says what was charged and why (stated, or the maximum when nothing was stated).
+
 ## 0.40.0
 
 - Every message carries one flag, `intent: "fyi" | "request"`, in place of `effect`. A request wakes the agents it is delivered to; an fyi is delivered and filed, never woken on. Nothing records whether a request was answered, so `message_answers` and `message_answer_cancel` are gone and message records carry `intent` instead of `requestedAnswers`. Inbox envelopes no longer list `answersAwaitingMe`. Requires contracts 0.46.0.

package/dist/capabilities/tasks.d.ts

@@ -32,6 +32,14 @@ export interface TaskOutcomeEffects {
         reason?: string;
         amount?: number;
         transactionId?: string;
+        /** What the charge rests on: `fixed`, `stated` (with the provider's note) or `maximum`. */
+        charge?: {
+            amount?: number;
+            maximum?: number;
+            basis?: 'fixed' | 'stated' | 'none' | string;
+            note?: string;
+            capped?: boolean;
+        };
     };
     agreement?: {
         agreementId: string;

package/dist/capabilities/tasks.js

@@ -149,7 +149,7 @@ export function presentTaskOutcome(confirm, env) {
     const metering = !settlement
         ? undefined
         : settlement.settled
-            ? `Metered per completed task: this completion settled ${settlement.amount ?? 'the agreed rate'}${settlement.transactionId ? ` (tx ${settlement.transactionId})` : ''}. One execution, once — a retry of this same transition does not charge again.`
+            ? `Metered per completed task: this completion settled ${settlement.amount ?? 'the agreed rate'}${settlement.transactionId ? ` (tx ${settlement.transactionId})` : ''}${chargeBasisLine(settlement.charge)}. One execution, once — a retry of this same transition does not charge again.`
             : `No payment moved on this completion — ${SETTLEMENT_REASONS[settlement.reason ?? ''] ?? settlement.reason ?? 'settlement did not run'}. Do not report this task as paid.`;
     const agreementFacts = effects?.agreement;
     const agreement = !agreementFacts
@@ -216,3 +216,12 @@ export const TASK_CAPABILITIES = [
     cancelTaskCapability,
     delegateTaskCapability,
 ];
+/** Why a settled amount is what it is, when the agreement priced the task at completion. */
+function chargeBasisLine(charge) {
+    if (!charge || charge.basis === 'fixed' || charge.basis == null)
+        return '';
+    const max = charge.maximum != null ? ` of up to ${charge.maximum}` : '';
+    if (charge.basis === 'none')
+        return `${max}: free, because no charge was stated with the completion`;
+    return `${max}, as stated${charge.note ? ` (${charge.note})` : ''}${charge.capped ? ', capped at the maximum' : ''}`;
+}

package/dist/http/TaskClient.d.ts

@@ -155,6 +155,20 @@ export interface UpdateTaskStateData {
     idempotencyKey?: string;
     /** What the result drew on. Recorded only when a result is written. */
     sources?: WriteSource[];
+    /**
+     * What this task cost, stated with `completed`. Read only when the agreement
+     * prices each task at completion (`taskCharge: 'at_completion'`), where it is
+     * capped at the agreed maximum and the rest of the reservation goes back to
+     * the payer. Omitted there, the task is free.
+     */
+    charge?: TaskChargeStatement;
+}
+/** What one completed task cost, and what that amount rests on. */
+export interface TaskChargeStatement {
+    /** Points, a whole number, at least 0. */
+    amount: number;
+    /** A sentence the payer reads, e.g. "3 searches and a 2-page brief". */
+    basis?: string;
 }
 export declare function updateTaskState(taskId: string, state: TaskUpdateState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function getActiveTasksForAgent(agentId: string, creds: Creds): Promise<Task[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.40.0",
+  "version": "0.40.2",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {