@ziggs-ai/api-client 0.39.5 → 0.40.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 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.
+
 ## 0.39.5
 
 - `message_send` explains its "Nothing authorizes giving … access to this message" refusal: the reader has no contact basis, so ask its owner with `access_request` `scopeKind: "contact"`, then send once they approve.

package/dist/capabilities/context.js

@@ -270,7 +270,7 @@ const OPEN_REF_PARAMS = {
 function resumeResource(kind, id, env) {
     // After a send grant is approved there is nothing to read: send to the destination.
     if (kind === 'contact')
-        return { tool: env.surface === 'mcp' ? 'ziggs_message_send' : 'message_send', args: { command: { audience: { kind: 'explicit', principalIds: [id] }, deliveries: { kind: 'explicit', principalIds: [id] }, effect: { kind: 'none' } } } };
+        return { tool: env.surface === 'mcp' ? 'ziggs_message_send' : 'message_send', args: { command: { audience: { kind: 'explicit', principalIds: [id] }, deliveries: { kind: 'explicit', principalIds: [id] }, intent: 'fyi' } } };
     const tool = kind === 'message' ? 'message_read' : 'open';
     return {
         tool: env.surface === 'mcp' ? `ziggs_${tool}` : tool,

package/dist/capabilities/links.js

@@ -65,7 +65,7 @@ export const listLinksCapability = {
         // this side, because the addressable id is not in the payload to find. It
         // is now, as `peer`, resolved relative to whoever asked.
         const readPlan = active.length ? [
-            nextCall(env, 'message_send', undefined, 'Send an explicit message command to a returned peer.id; choose readers, delivery recipients and any requested answer separately. A link grants no history access.'),
+            nextCall(env, 'message_send', undefined, 'Send an explicit message command to a returned peer.id; choose readers, delivery recipients and the intent (fyi or request) separately. A link grants no history access.'),
             nextCall(env, 'artifact_share', undefined, 'Share only the selected artifact under its grant and consent policy.'),
         ] : [];
         return {

package/dist/capabilities/mcpBriefs.js

@@ -169,13 +169,11 @@ const BRIEFS = {
         does: 'Shares one artifact you authored with another agent.',
         changes: 'grants it at once to a connected agent; otherwise asks your owner to approve (pending_approval)',
     },
-    ziggs_message_send: { does: 'Sends a canonical command with independent readers, recipients, answer effect and optional mandate.', changes: 'delivers a message and grants its readers access' },
+    ziggs_message_send: { does: 'Sends a canonical command with independent readers, recipients, an intent (fyi or request) and optional mandate.', changes: 'delivers a message and grants its readers access; a request wakes the agents it reaches' },
     ziggs_message_replies: { does: 'Reads authorized causal replies by messageId; a reference grants no access and receipt expiry does not erase history.' },
     ziggs_message_read: { does: 'Reads an exact message by messageId under current access and execution policy. Does not acknowledge its receipt.' },
     ziggs_message_list: { does: 'Queries authorized messages by participants, agreement or task. Filters select history, not authority.' },
     ziggs_message_controls: { does: 'Inspects recipients and authority for an explicit agreement or task without reading history.' },
-    ziggs_message_answers: { does: 'Reads durable answer requests and their outcomes independently of inbox acknowledgment.' },
-    ziggs_message_answer_cancel: { does: 'Cancels one exact pending answer request as its author.', changes: 'closes the request without deleting history or cancelling tasks' },
     ziggs_task_delegate: {
         does: 'Delegates work, returns a child output, or rechecks readiness.',
         changes: 'creates or returns isolated work',

package/dist/capabilities/messaging.d.ts

@@ -4,6 +4,4 @@ export declare const sendMessageCapability: CapabilityDefinition;
 export declare const readRepliesCapability: CapabilityDefinition;
 export declare const queryMessagesCapability: CapabilityDefinition;
 export declare const messageControlsCapability: CapabilityDefinition;
-export declare const messageAnswersCapability: CapabilityDefinition;
-export declare const cancelAnswerCapability: CapabilityDefinition;
 export declare const MESSAGING_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/messaging.js

@@ -1,11 +1,9 @@
 import { MessageRecordsClient } from '../http/MessageRecordsClient.js';
 import { fullCreds } from './types.js';
 const client = (env) => { const creds = fullCreds(env); return new MessageRecordsClient(creds.operatorKey, creds.agentId, env.baseUrl); };
-export const readMessageCapability = { key: 'message_read', names: { sdk: 'message_read', mcp: 'ziggs_message_read' }, title: 'Read exact message', descriptions: { sdk: 'Read one authorized message. Returns content, independent readers/recipients, requested-answer action slots and authorized relationships. Does not acknowledge delivery.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true } }, handler: (args, env) => client(env).get(String(args.messageId)) };
-export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; effect:{kind:"none"} or request-answers:{requests:[{requestId,responsiblePrincipalId}]} or answer:{action:{kind:"message",id,slot:"answer",requestId},artifacts:[]} or provide-input:{action}. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. Reuse operationId unchanged on retry. A causal reply alone never resolves an answer. No room required. Refused with "Nothing authorizes giving … access to this message" means you have no contact basis for that reader (membership, a link, an agreement or a listing): ask its owner with access_request scopeKind=contact and scopeId=that reader, then send once they approve.' }, annotation: 'destructive', needsAgentId: true, params: { command: { type: 'object', required: true, description: 'MessageCommand with explicit independent audience, deliveries, action effect and optional mandate.' } }, handler: (args, env) => client(env).send(args.command) };
+export const readMessageCapability = { key: 'message_read', names: { sdk: 'message_read', mcp: 'ziggs_message_read' }, title: 'Read exact message', descriptions: { sdk: 'Read one authorized message. Returns content, intent (fyi or request), independent readers/recipients and authorized relationships. Does not acknowledge delivery.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true } }, handler: (args, env) => client(env).get(String(args.messageId)) };
+export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; intent:"fyi" or "request". 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: a reply is a message with relationships.replyToMessageId. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. Reuse operationId unchanged on retry. No room required. Refused with "Nothing authorizes giving … access to this message" means you have no contact basis for that reader (membership, a link, an agreement or a listing): ask its owner with access_request scopeKind=contact and scopeId=that reader, then send once they approve.' }, annotation: 'destructive', needsAgentId: true, params: { command: { type: 'object', required: true, description: 'MessageCommand with explicit independent audience, deliveries, intent and optional mandate.' } }, handler: (args, env) => client(env).send(args.command) };
 export const readRepliesCapability = { key: 'message_replies', names: { sdk: 'message_replies', mcp: 'ziggs_message_replies' }, title: 'Read replies', descriptions: { sdk: 'Read currently authorized causal replies; links never grant access. Continue using nextCursor as before.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).replies(String(args.messageId), { before: args.before, limit: args.limit }) };
 export const queryMessagesCapability = { key: 'message_list', names: { sdk: 'message_list', mcp: 'ziggs_message_list' }, title: 'Query messages', descriptions: { sdk: 'Query authorized messages. Use conversationOf with an exact message id to browse messages connected by readable reply relationships; use nextCursor as before for earlier turns. Select conversationOf independently of agreementId, taskId or participantIds. History never selects authority.' }, annotation: 'read-only', needsAgentId: true, params: { conversationOf: { type: 'string', description: 'Authorized anchor message; follows readable causal links, never a reader roster. Each result still requires read access and any execution input authorization.' }, q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string' }, taskId: { type: 'string' }, participantIds: { type: 'array', items: { type: 'string' } }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).list(args) };
 export const messageControlsCapability = { key: 'message_controls', names: { sdk: 'message_controls', mcp: 'ziggs_message_controls' }, title: 'Inspect message mandate', descriptions: { sdk: 'Discover recipients and current authority under an explicitly selected agreement/task without reading message history.' }, annotation: 'read-only', needsAgentId: true, params: { q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string', required: true }, taskId: { type: 'string' } }, handler: (args, env) => client(env).controls(String(args.agreementId), args.taskId) };
-export const messageAnswersCapability = { key: 'message_answers', names: { sdk: 'message_answers', mcp: 'ziggs_message_answers' }, title: 'Read answer requests', descriptions: { sdk: 'Read durable requested-answer outcomes independently of inbox ACK state.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true } }, handler: (args, env) => client(env).answers(String(args.messageId)) };
-export const cancelAnswerCapability = { key: 'message_answer_cancel', names: { sdk: 'message_answer_cancel', mcp: 'ziggs_message_answer_cancel' }, title: 'Cancel answer request', descriptions: { sdk: 'As the request author, cancel one exact pending answer slot. Does not delete history or cancel tasks.' }, annotation: 'destructive', needsAgentId: true, params: { messageId: { type: 'string', required: true }, requestId: { type: 'string', required: true } }, handler: (args, env) => client(env).cancelAnswer(String(args.messageId), String(args.requestId)) };
-export const MESSAGING_CAPABILITIES = [readMessageCapability, sendMessageCapability, readRepliesCapability, queryMessagesCapability, messageControlsCapability, messageAnswersCapability, cancelAnswerCapability];
+export const MESSAGING_CAPABILITIES = [readMessageCapability, sendMessageCapability, readRepliesCapability, queryMessagesCapability, messageControlsCapability];

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' | 'maximum' | 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 === 'maximum')
+        return `${max}, the maximum, because no charge was stated with the completion`;
+    return `${max}, as stated${charge.note ? ` (${charge.note})` : ''}${charge.capped ? ', capped at the maximum' : ''}`;
+}

package/dist/engagementGuide.js

@@ -227,7 +227,7 @@ export function contactPath(env, input) {
             summary: sameOrg && !linked
                 ? 'Same-org person: reach them under this scoped identity.'
                 : 'Linked person: choose an explicit message audience and delivery. A link does not reveal their org roster.',
-            next: nextCall(env, 'message_send', undefined, `send an explicit message command to ${partyId}; choose readers, delivery and answer responsibility separately`),
+            next: nextCall(env, 'message_send', undefined, `send an explicit message command to ${partyId}; choose readers, delivery and intent (fyi or request) separately`),
         };
     }
     if (partyKind === 'person' && !linked) {

package/dist/http/MessageRecordsClient.d.ts

@@ -29,9 +29,5 @@ export declare class MessageRecordsClient {
         limit?: number;
     }): Promise<MessagePage>;
     controls(agreementId: string, taskId?: string): Promise<MessagingControls>;
-    answers(id: string): Promise<unknown>;
-    cancelAnswer(id: string, requestId: string): Promise<{
-        state: 'cancelled';
-    }>;
 }
 export type { MessageCommand, MessageCommandResult, MessageRecord } from '@ziggs-ai/contracts';

package/dist/http/MessageRecordsClient.js

@@ -2,6 +2,7 @@ import { parseMessageCommand } from '@ziggs-ai/contracts';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
+const isIntent = (value) => value === 'fyi' || value === 'request';
 /** One command and one representation, independent of navigation. */
 export class MessageRecordsClient {
     operatorKey;
@@ -14,9 +15,9 @@ export class MessageRecordsClient {
     }
     async request(path, init = {}) { const res = await fetch(`${this.baseUrl ?? getBackendUrl()}/messaging/${path}`, { ...init, headers: { 'content-type': 'application/json', ...buildOperatorHeaders(this.operatorKey, this.agentId) } }); if (!res.ok)
         throwApiError(res, await res.text().catch(() => ''), `Messaging failed: ${res.status}`); return await res.json(); }
-    async get(id) { const row = await this.request(`messages/${encodeURIComponent(id)}`); if (row.messageId !== id || !row.content || !Array.isArray(row.requestedAnswers))
+    async get(id) { const row = await this.request(`messages/${encodeURIComponent(id)}`); if (row.messageId !== id || !row.content || !isIntent(row.intent))
         throw new Error('Invalid exact message response'); return row; }
-    async send(command) { const result = await this.request('messages', { method: 'POST', body: JSON.stringify(parseMessageCommand(command)) }); if (!['created', 'existing'].includes(result.outcome) || !result.message?.messageId || !result.message.content || !Array.isArray(result.message.recipients) || !Array.isArray(result.message.requestedAnswers))
+    async send(command) { const result = await this.request('messages', { method: 'POST', body: JSON.stringify(parseMessageCommand(command)) }); if (!['created', 'existing'].includes(result.outcome) || !result.message?.messageId || !result.message.content || !Array.isArray(result.message.recipients) || !isIntent(result.message.intent))
         throw new Error('Invalid message command response'); return result; }
     list(input = {}) { const query = new URLSearchParams(); for (const [key, value] of Object.entries(input))
         if (value !== undefined)
@@ -25,6 +26,4 @@ export class MessageRecordsClient {
         if (value !== undefined)
             query.set(key, String(value)); return this.request(`messages/${encodeURIComponent(id)}/replies?${query}`); }
     controls(agreementId, taskId) { const query = new URLSearchParams({ agreementId, ...(taskId ? { taskId } : {}) }); return this.request(`controls?${query}`); }
-    answers(id) { return this.request(`messages/${encodeURIComponent(id)}/answers`); }
-    cancelAnswer(id, requestId) { return this.request(`messages/${encodeURIComponent(id)}/answers/${encodeURIComponent(requestId)}/cancel`, { method: 'POST' }); }
 }

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 costs the maximum.
+     */
+    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/dist/types.d.ts

@@ -457,7 +457,6 @@ export interface InboxEnvelope extends InboxRequestChannel, Partial<InboxPlanAck
      */
     ackTo: string | null;
     /** Open tasks assigned to this agent — the work channel. */
-    answersAwaitingMe?: InboxDeliveryRef[];
     tasksAwaitingMe: InboxTaskRef[];
     truncatedTasks: number;
     proposalsAwaitingMe: InboxProposalRef[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.39.5",
+  "version": "0.40.1",
   "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.45.0",
+    "@ziggs-ai/contracts": "0.46.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [