@ziggs-ai/api-client 0.22.3 → 0.23.0

package/dist/capabilities/agreementVerbs.js

@@ -50,6 +50,9 @@ const TERMS_PARAMS = {
         type: 'string',
         description: 'ISO timestamp after which this can no longer be acted on.',
     },
+    interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
+    conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
+    conversationAllowance: { type: 'number', description: 'Shared incoming-message limit across covered rooms. Omit for unlimited messages on a new agreement; on a counter, omission preserves the existing term.' },
     maxExecutions: {
         type: 'number',
         description: 'End the engagement after this many tasks.',
@@ -69,6 +72,9 @@ function termsFrom(args) {
         ...(args['expiresAt'] === undefined
             ? {}
             : { expiresAt: args['expiresAt'] }),
+        ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
+        ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
+        ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
         ...(args['maxExecutions'] === undefined
             ? {}
             : { maxExecutions: args['maxExecutions'] }),
@@ -96,7 +102,7 @@ const MANDATE_PARAM = {
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
-    const declared = args['mandateAgreementId'];
+    const declared = args['parentAgreementId'] ?? args['mandateAgreementId'];
     return typeof declared === 'string' && declared ? { parentAgreementId: declared } : {};
 }
 /** The audience a broadcast reaches. */
@@ -165,6 +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.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -196,6 +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.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -235,6 +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.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -265,6 +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.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -315,6 +325,9 @@ export const agreementOfferCapability = {
             lifecycle: terms.lifecycle,
             expiresAt: terms.expiresAt,
             maxExecutions: terms.maxExecutions,
+            conversationAllowance: terms.conversationAllowance,
+            conversationAllowanceScope: terms.conversationAllowanceScope,
+            interactionMode: terms.interactionMode,
             billing: terms.billing,
             engagementKind: engagementKindFrom(args),
             audience: args['audience'],
@@ -428,6 +441,9 @@ export const agreementSubcontractCapability = {
         },
         expiresAt: { type: 'string' },
         maxExecutions: { type: 'number' },
+        interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
+        conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
+        conversationAllowance: { type: 'number', description: 'Message allowance; direct to this agreement unless conversationAllowanceScope explicitly says subtree.' },
         agreementDescription: { type: 'string' },
         payerId: {
             type: 'string',
@@ -451,6 +467,9 @@ export const agreementSubcontractCapability = {
             ...(args['expiresAt'] === undefined
                 ? {}
                 : { expiresAt: args['expiresAt'] }),
+            ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
+            ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
+            ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
             ...(args['maxExecutions'] === undefined
                 ? {}
                 : { maxExecutions: args['maxExecutions'] }),

package/dist/capabilities/agreements.js

@@ -83,6 +83,7 @@ export const agreementClaimCapability = {
         // doing needs — waited on a human every time. It authorizes; it does not
         // re-parent: the row belongs to whoever posted it, and a claimer cannot move
         // somebody else's agreement into its own tree.
+        parentAgreementId: { type: 'string', description: 'Place the new service-listing claim under this governing relationship or work agreement. Requires separate consent to the posted terms.' },
         mandateAgreementId: {
             type: 'string',
             description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.',
@@ -91,9 +92,7 @@ export const agreementClaimCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), typeof declaredMandate === 'string' && declaredMandate
-            ? { mandateAgreementId: declaredMandate }
-            : {});
+        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}) });
         return presentClaimResult(agreement, kind, env);
     },
 };

package/dist/capabilities/artifacts.js

@@ -1,4 +1,4 @@
-import { ArtifactsClient } from '../http/ArtifactsClient.js';
+import { ARTIFACT_FILE_FORMATS, ArtifactsClient, } from '../http/ArtifactsClient.js';
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient, } from '../http/ContextDiscoveryClient.js';
 import { fullCreds } from './types.js';
@@ -105,6 +105,7 @@ async function recordFileArtifact(args, env, visibility) {
         visibility,
         chatId: args['chatId'],
         agreementId: args['agreementId'],
+        serviceAgreementId: args['serviceAgreementId'] ?? (!taskId && !args['agreementId'] ? env.serviceAgreementId : undefined),
         taskId,
         idempotencyKey: args['idempotencyKey'],
         // ArtifactsClient does the PUT and hands back the sha256 of what it sent,
@@ -129,6 +130,23 @@ async function recordFileArtifact(args, env, visibility) {
         reportingHint: reportingHint(env, args['contentType'], taskId),
     };
 }
+/** Both fields or neither. Shape is taught in the param description. */
+function parseExternalRef(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('externalRef must be { provider, url }');
+    }
+    const rec = raw;
+    const provider = typeof rec.provider === 'string' ? rec.provider.trim() : '';
+    const url = typeof rec.url === 'string' ? rec.url.trim() : '';
+    if (!provider && !url)
+        return undefined;
+    if (!provider || !url) {
+        throw new Error('externalRef needs both provider and url');
+    }
+    return { provider, url };
+}
 export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
@@ -176,7 +194,7 @@ export const recordArtifactCapability = {
         },
         format: {
             type: 'string',
-            enum: ['pdf', 'docx', 'hwpx', 'md', 'txt', 'html'],
+            enum: [...ARTIFACT_FILE_FORMATS],
             description: 'Optional file format; inferred from filename when omitted',
         },
         visibility: {
@@ -186,6 +204,7 @@ export const recordArtifactCapability = {
             description: 'chat = the scope’s parties can read it; agent-private = not shared with them. ' +
                 'Neither is permanent: you can share any artifact later with a specific agent.',
         },
+        serviceAgreementId: { type: 'string', description: 'Agreement authorizing this work, separate from the destination chat. Defaults to the SDK wake agreement when no task/agreement scope is supplied.' },
         chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
@@ -204,6 +223,12 @@ export const recordArtifactCapability = {
             description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it. ' +
                 'A task-bound result artifact is one deliverable per task: recordReport keys it `task-result:<taskId>`, so a retry after a partial failure reuses that row. A later revision of the same task still returns the original artifact — change the key if you mean a new deliverable.',
         },
+        externalRef: {
+            type: 'object',
+            description: 'When the deliverable lives in another system: { provider, url }. Both required. ' +
+                'text is the in-Ziggs summary. Ziggs stores the link and does not fetch it. ' +
+                'A grant on this artifact does not open the other system.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -238,6 +263,7 @@ export const recordArtifactCapability = {
         }
         const contentType = args['contentType'];
         const taskId = args['taskId'];
+        const externalRef = parseExternalRef(args['externalRef']);
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
             text,
@@ -246,8 +272,10 @@ export const recordArtifactCapability = {
             chatId,
             agreementId,
             taskId,
+            serviceAgreementId: args['serviceAgreementId'] ?? (!taskId && !agreementId ? env.serviceAgreementId : undefined),
             contentType,
             idempotencyKey: args['idempotencyKey'],
+            ...(externalRef ? { externalRef } : {}),
         });
         return {
             ok: true,
@@ -605,7 +633,7 @@ export const uploadArtifactUrlCapability = {
             'large to travel inside a tool call. Returns a short-lived uploadUrl: PUT the exact byteSize ' +
             'bytes to it (Content-Type = mime), then call artifact_complete_file with the sha256 hex of ' +
             'those bytes.',
-        mcp: 'Large-file escape hatch (pdf/docx/hwpx/md/txt/html). Ordinary files go through ' +
+        mcp: `Large-file escape hatch (${ARTIFACT_FILE_FORMATS.join('/')}). Ordinary files go through ` +
             'ziggs_artifact_record (filename + mime + contentBase64), which presigns, uploads and ' +
             'completes in one call — use this only when the bytes are too large to travel inside a tool ' +
             'call. Returns uploadUrl + artifactId: PUT the bytes with the declared mime, then call ' +
@@ -628,7 +656,7 @@ export const uploadArtifactUrlCapability = {
         },
         format: {
             type: 'string',
-            enum: ['pdf', 'docx', 'hwpx', 'md', 'txt', 'html'],
+            enum: [...ARTIFACT_FILE_FORMATS],
             description: 'Optional; inferred from filename when omitted',
         },
         visibility: {
@@ -641,6 +669,7 @@ export const uploadArtifactUrlCapability = {
             type: 'string',
             description: 'Optional agreement scope; mutually exclusive with chatId',
         },
+        serviceAgreementId: { type: 'string', description: 'Agreement authorizing this work, separate from the destination chat.' },
         taskId: { type: 'string', description: 'Optional task binding' },
         idempotencyKey: {
             type: 'string',
@@ -679,6 +708,7 @@ export const uploadArtifactUrlCapability = {
             chatId: args['chatId'],
             agreementId: args['agreementId'],
             taskId: args['taskId'],
+            serviceAgreementId: args['serviceAgreementId'] ?? (!args['taskId'] && !args['agreementId'] ? env.serviceAgreementId : undefined),
             idempotencyKey: args['idempotencyKey'],
             contentBase64: args['contentBase64'],
         });

package/dist/capabilities/context.js

@@ -79,6 +79,7 @@ export const contextReadCapability = {
             required: true,
             description: `Scope entry you hold, as <kind>:<id>. Accepted per type — ${VIA_BY_TYPE}.`,
         },
+        agreementId: { type: 'string', description: 'Filter message history to this exact work agreement. Use cursor pagination to expand a wake packet.' },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         after: { type: 'string', description: 'ISO timestamp for forward-delta (messages/artifacts)' },
         direction: {
@@ -119,6 +120,7 @@ export const contextReadCapability = {
         }
         return new ContextReadClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).read(type, {
             via,
+            agreementId: args['agreementId'],
             cursor: args['cursor'],
             after: args['after'],
             direction: direction,
@@ -310,6 +312,7 @@ export const openCapability = {
     annotation: 'read-only',
     params: {
         ...OPEN_ID_PARAMS,
+        agreementId: { type: 'string', description: 'Filter message history to this exact work agreement. Use cursor pagination to expand a wake packet.' },
         cursor: { type: 'string', description: 'Opaque cursor from a prior open page' },
         after: { type: 'string', description: 'ISO timestamp for a forward-delta' },
         limit: { type: 'number', description: 'Page size' },

package/dist/capabilities/marketplace.js

@@ -47,6 +47,7 @@ function toListingRow(a, kind) {
         engagementKind: a?.engagementKind,
         lifecycle: terms.lifecycle,
         ...(terms.expiresAt ? { expiresAt: terms.expiresAt } : {}),
+        ...(terms.conversationAllowance !== undefined ? { conversationAllowance: terms.conversationAllowance } : {}),
         ...(terms.maxExecutions != null ? { maxExecutions: terms.maxExecutions } : {}),
         // Who does the work on an offer, who is paying on a request. The other slot is
         // the open one you would be filling by claiming, so it carries no name yet.

package/dist/capabilities/types.d.ts

@@ -40,6 +40,8 @@ export interface CapabilityParam {
  * that impersonate set `needsAgentId` so the adapter fails early instead.
  */
 export interface CapabilityEnv {
+    /** Validated wake scope supplied by the host; never a resource-access grant. */
+    serviceAgreementId?: string;
     creds: {
         operatorKey: string;
         agentId?: string;

package/dist/http/AgreementClient.d.ts

@@ -12,6 +12,10 @@ export interface ProposeTerms {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /** Shared incoming-message allowance; null means unlimited. */
+    conversationAllowance?: number | null;
+    conversationAllowanceScope?: 'direct' | 'subtree';
+    interactionMode?: 'messages' | 'tasks' | 'both';
     /**
      * How `price` reads. `total` (default) escrows one price for the whole
      * engagement and pays at fulfillment; `per_task` is a RATE settled as each
@@ -127,6 +131,10 @@ export interface DelegateAgreementData {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /** Shared incoming-message allowance; null means unlimited. */
+    conversationAllowance?: number | null;
+    conversationAllowanceScope?: 'direct' | 'subtree';
+    interactionMode?: 'messages' | 'tasks' | 'both';
     agreementDescription?: string;
     payerId?: string;
     idempotencyKey?: string;
@@ -193,6 +201,10 @@ export interface CounterAgreementData {
     expiresAt?: string;
     lifecycle?: string;
     maxExecutions?: number;
+    /** Shared incoming-message allowance; null means unlimited. */
+    conversationAllowance?: number | null;
+    conversationAllowanceScope?: 'direct' | 'subtree';
+    interactionMode?: 'messages' | 'tasks' | 'both';
     description?: string;
 }
 export declare function counterAgreement(agreementId: string, counter: CounterAgreementData, creds: Creds): Promise<Agreement>;
@@ -298,6 +310,7 @@ export type ClaimedKind = 'link' | 'offer' | 'request' | 'hand-off';
  * agreement belongs to whoever posted it.
  */
 export interface ClaimOptions {
+    parentAgreementId?: string;
     /**
      * The active agreement whose work this claim is part of. An agent acting
      * inside a job its human approved does not need a second consent for the

package/dist/http/AgreementClient.js

@@ -92,6 +92,7 @@ export function linkSummary(a) {
  */
 export function shapeAgreement(a) {
     const wire = a;
+    const conversationAllowance = wire.terms?.conversationAllowance;
     const lifted = {
         ...a,
         ...(wire.terms?.description != null
@@ -106,6 +107,7 @@ export function shapeAgreement(a) {
         ...(wire.terms?.maxExecutions != null
             ? { maxExecutions: wire.terms.maxExecutions }
             : {}),
+        ...(conversationAllowance !== undefined ? { conversationAllowance } : {}),
         // A price with no billing mode is two different offers. Lifted
         // beside the executions cap because they are read together: "ϟ5 a task, up
         // to 10" and "ϟ5 for the lot" are the same three fields otherwise.
@@ -546,7 +548,7 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}),
+        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

package/dist/http/ArtifactsClient.d.ts

@@ -16,6 +16,7 @@ export interface ListArtifactsQuery {
     chatId?: string;
     agreementId?: string;
     taskId?: string;
+    serviceAgreementId?: string;
     /**
      * `'me'` lists artifacts YOU authored, in any scope or none. The
      * only listing that surfaces a free-standing artifact, since the others read
@@ -76,6 +77,7 @@ export interface WriteArtifactInput {
     agreementId?: string;
     /** Optional task binding — creates a TaskArtifactLink alongside the primary scope link. */
     taskId?: string;
+    serviceAgreementId?: string;
     service?: Record<string, unknown>;
     /**
      * Optional idempotency key. A redelivered write with the same key (same
@@ -84,8 +86,18 @@ export interface WriteArtifactInput {
      * reproduces it.
      */
     idempotencyKey?: string;
+    /**
+     * When the deliverable lives outside Ziggs: both provider and http(s) URL.
+     * The `text` is the in-Ziggs summary. Ziggs does not fetch the URL.
+     */
+    externalRef?: {
+        provider: string;
+        url: string;
+    };
 }
-export type ArtifactFileFormat = 'pdf' | 'docx' | 'hwpx' | 'md' | 'txt' | 'html';
+/** Every file format the server stores, in its order. One list for the type and the tool enums. */
+export declare const ARTIFACT_FILE_FORMATS: readonly ["pdf", "docx", "hwpx", "pptx", "md", "txt", "html", "mp3"];
+export type ArtifactFileFormat = (typeof ARTIFACT_FILE_FORMATS)[number];
 export interface ArtifactUploadUrlInput {
     /** Short list name. Defaults to filename on the server when omitted. */
     name?: string;
@@ -98,6 +110,7 @@ export interface ArtifactUploadUrlInput {
     chatId?: string;
     agreementId?: string;
     taskId?: string;
+    serviceAgreementId?: string;
     service?: Record<string, unknown>;
     idempotencyKey?: string;
     /**
@@ -170,6 +183,7 @@ export declare class ArtifactsClient {
      */
     recordThought(sessionId: string, text: string, opts?: {
         idempotencyKey?: string;
+        serviceAgreementId?: string;
     }): Promise<void>;
     write(input: WriteArtifactInput): Promise<void>;
     /**

package/dist/http/ArtifactsClient.js

@@ -13,6 +13,8 @@ export const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT = `text exceeds ${ARTIFACT_INL
     'For larger content use ziggs_artifact_upload_url (file rail), or split into ' +
     'an index artifact plus part artifacts and list the part ids in the index. ' +
     'The server does not auto-split.';
+/** Every file format the server stores, in its order. One list for the type and the tool enums. */
+export const ARTIFACT_FILE_FORMATS = ['pdf', 'docx', 'hwpx', 'pptx', 'md', 'txt', 'html', 'mp3'];
 function resolveUploadBytes(input) {
     if (input.content != null) {
         return Buffer.isBuffer(input.content)
@@ -140,6 +142,7 @@ export class ArtifactsClient {
             contentType: 'thought',
             visibility: 'agent-private',
             idempotencyKey: opts.idempotencyKey,
+            serviceAgreementId: opts.serviceAgreementId,
         });
     }
     async write(input) {
@@ -185,8 +188,12 @@ export class ArtifactsClient {
                 chatId: input.chatId,
                 agreementId: input.agreementId,
                 taskId: input.taskId,
+                serviceAgreementId: input.serviceAgreementId,
                 service: input.service,
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(input.externalRef
+                    ? { externalRef: input.externalRef }
+                    : {}),
             }),
         });
         const body = await res.text().catch(() => '');
@@ -257,6 +264,7 @@ export class ArtifactsClient {
             chatId: input.chatId,
             agreementId: input.agreementId,
             taskId: input.taskId,
+            serviceAgreementId: input.serviceAgreementId,
             service: input.service,
             ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
         }, 'artifact upload-url');

package/dist/http/ChatClient.d.ts

@@ -44,6 +44,10 @@ export interface SendChatMessageInput {
     entryType?: string;
     contentType?: string;
     underAgreementId?: string;
+    /** Governing service agreement; independent of representation. */
+    conversationAgreementId?: string;
+    taskId?: string;
+    replyToMessageId?: string;
 }
 /**
  * Where the server says a send landed.

package/dist/http/ChatClient.js

@@ -105,6 +105,9 @@ export async function sendChatMessage(input, creds) {
             // clients send the object.
             receiver: input.receiverId ? { id: input.receiverId } : undefined,
             underAgreementId: input.underAgreementId,
+            conversationAgreementId: input.conversationAgreementId,
+            taskId: input.taskId,
+            replyToMessageId: input.replyToMessageId,
         }),
     });
     if (!res.ok) {

package/dist/http/ContextReadClient.d.ts

@@ -23,6 +23,7 @@ export declare function parseVia(via: string): {
     id: string;
 } | null;
 export interface ContextReadQuery {
+    agreementId?: string;
     via: string;
     cursor?: string;
     limit?: number;
@@ -56,6 +57,7 @@ export interface ContextSnapshotParticipant {
     [key: string]: unknown;
 }
 export interface ContextSnapshotResult {
+    work?: Record<string, unknown>;
     history: unknown[];
     agreements: unknown[];
     /** Bounded room inventory, without bodies. Absent on older backends. */
@@ -102,5 +104,10 @@ export declare class ContextReadClient {
     snapshot(chatId: string, opts?: {
         maxMessages?: number;
         contextGrantId?: string;
+        agreementId?: string;
+        taskId?: string;
+        messageId?: string;
+        artifactId?: string;
+        via?: string;
     }): Promise<ContextSnapshotResult>;
 }

package/dist/http/ContextReadClient.js

@@ -80,6 +80,8 @@ export class ContextReadClient {
         }
         const url = new URL(`${this.baseUrl}/context/read/${encodeURIComponent(type)}`);
         url.searchParams.set('via', query.via.trim());
+        if (query.agreementId)
+            url.searchParams.set('agreementId', query.agreementId);
         if (query.cursor)
             url.searchParams.set('cursor', query.cursor);
         if (query.limit != null)
@@ -119,7 +121,13 @@ export class ContextReadClient {
             throw new Error('ContextReadClient.snapshot: chatId is required');
         }
         const url = new URL(`${this.baseUrl}/context/snapshot`);
-        url.searchParams.set('via', `chat:${chatId}`);
+        url.searchParams.set('via', opts.taskId ? `task:${opts.taskId}` : opts.via ?? (chatId.startsWith('agrn-') ? `agreement:${opts.agreementId ?? chatId.slice(5)}` : `chat:${chatId}`));
+        if (opts.agreementId)
+            url.searchParams.set('agreementId', opts.agreementId);
+        if (opts.messageId)
+            url.searchParams.set('messageId', opts.messageId);
+        if (opts.artifactId)
+            url.searchParams.set('artifactId', opts.artifactId);
         if (opts.maxMessages != null) {
             url.searchParams.set('maxMessages', String(opts.maxMessages));
         }

package/dist/http/MarketplaceClient.d.ts

@@ -5,6 +5,10 @@ export interface PublishOfferPayload {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /** Shared incoming-message allowance; null means unlimited. */
+    conversationAllowance?: number | null;
+    conversationAllowanceScope?: 'direct' | 'subtree';
+    interactionMode?: 'messages' | 'tasks' | 'both';
     /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
     engagementKind?: 'hire' | 'service';
     /**

package/dist/http/TaskClient.d.ts

@@ -20,6 +20,20 @@ export interface TaskWriteConfirm {
     terminalState?: string;
     [key: string]: unknown;
 }
+export interface TaskControl {
+    requestId: string;
+    action: 'pause' | 'resume' | 'stop';
+    status: 'requested' | 'acknowledged' | 'unsupported';
+    requestedAt: string;
+    acknowledgedAt: string | null;
+}
+export declare function requestTaskControl(taskId: string, request: {
+    action: TaskControl['action'];
+    requestId: string;
+    previousRequestId: string | null;
+}, creds: Creds): Promise<TaskWriteConfirm>;
+/** Runtime-only: call after all work for this task has quiesced, never on receipt alone. */
+export declare function acknowledgeTaskControl(taskId: string, requestId: string, supported: boolean, creds: Creds): Promise<TaskWriteConfirm>;
 /**
  * When the buyer reviews a task's plan. Task-rail only — an agreement has no
  * plan to review, which is why cut this from the propose/counter/
@@ -185,6 +199,8 @@ export declare class TaskClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string);
+    requestControl(taskId: string, request: Parameters<typeof requestTaskControl>[1]): Promise<TaskWriteConfirm>;
+    acknowledgeControl(taskId: string, requestId: string, supported?: boolean): Promise<TaskWriteConfirm>;
     createTask(data: CreateTaskData): Promise<Task>;
     getTask(taskId: string): Promise<Task>;
     updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<TaskWriteConfirm>;

package/dist/http/TaskClient.js

@@ -25,6 +25,27 @@ function extractTask(data) {
     }
     return null;
 }
+export async function requestTaskControl(taskId, request, creds) {
+    return writeTaskControl(taskId, 'control', 'PATCH', request, creds);
+}
+/** Runtime-only: call after all work for this task has quiesced, never on receipt alone. */
+export async function acknowledgeTaskControl(taskId, requestId, supported, creds) {
+    return writeTaskControl(taskId, 'control/ack', 'POST', { requestId, supported }, creds);
+}
+async function writeTaskControl(taskId, path, method, body, creds) {
+    if (!taskId)
+        throw new Error('Task control requires a taskId');
+    assertCreds(creds, 'task control');
+    const res = await fetch(`${getTaskBaseUrl()}/${encodeURIComponent(taskId)}/${path}`, {
+        method, headers: buildHeaders(creds), body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throwApiError(res, await res.text().catch(() => ''), `Task control failed: ${res.status}`);
+    const result = extractWriteConfirm(await res.json());
+    if (!result)
+        throw new Error('Invalid task control response');
+    return result;
+}
 function extractWriteConfirm(data) {
     if (!data || typeof data !== 'object')
         return null;
@@ -36,6 +57,7 @@ function extractWriteConfirm(data) {
         d['description'] === undefined) {
         return {
             ok: true,
+            ...(d['control'] ? { control: d['control'] } : {}),
             taskId: d['taskId'],
             ...(typeof d['agreementId'] === 'string' ? { agreementId: d['agreementId'] } : {}),
             state: d['state'],
@@ -454,6 +476,8 @@ export class TaskClient {
         // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
+    requestControl(taskId, request) { return requestTaskControl(taskId, request, this.creds); }
+    acknowledgeControl(taskId, requestId, supported = true) { return acknowledgeTaskControl(taskId, requestId, supported, this.creds); }
     createTask(data) { return createTask(data, this.creds); }
     getTask(taskId) { return getTask(taskId, this.creds); }
     updateTaskState(taskId, state, data) { return updateTaskState(taskId, state, data ?? {}, this.creds); }

package/dist/http/agreementFlows.js

@@ -20,6 +20,9 @@ export async function proposeUnified(input, creds) {
                 lifecycle: terms.lifecycle,
                 expiresAt: terms.expiresAt,
                 maxExecutions: terms.maxExecutions,
+                conversationAllowance: terms.conversationAllowance,
+                conversationAllowanceScope: terms.conversationAllowanceScope,
+                interactionMode: terms.interactionMode,
                 engagementKind: engagementKind,
                 billing: terms.billing,
                 audience,

package/dist/types.d.ts

@@ -55,6 +55,8 @@ export interface PlanStep {
     result?: unknown;
 }
 export interface Task {
+    executorIsYou?: boolean;
+    control?: import('./http/TaskClient.js').TaskControl | null;
     taskId: string;
     description: string;
     /**
@@ -216,6 +218,10 @@ export interface Agreement {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    conversationAllowance?: number | null;
+    conversationUsage?: {
+        messages: number;
+    };
     /**
      * What `money.price` MEANS: `total` is the whole engagement, settled once;
      * `per_task` is a rate charged as each task completes.

package/package.json

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