@ziggs-ai/api-client 0.37.21 → 0.37.23

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.37.23
+
+- A pair `chat_open` accepts an idempotency key. Passing `chatId` without `participantIds` names only `chatId`.
+- `includeUnreadable: false` never attaches the unreadable list. Omitting it still attaches that list when nothing matched.
+- `fields` resolves `name`, `title`, `agentId`, `providerId`, `kind`, `scopeKind` and `scopeId` when the row stores them under another key, and lists a name that still matches nothing in `unknownFields`.
+- `respondToAgreement` uses the same refusal statuses as counter: 404 when the agreement is missing, 403 when this caller cannot approve it.
+
+## 0.37.22
+
+- A full inbox read says it takes or renews this host's lease and that waitSeconds long-polls. The read stays read-only. Acknowledgement stays on its own call.
+
 ## 0.37.21
 
 - A room lane can name the agreement the wake works under: `laneUnderAgreement(chatId, agreementId)` builds it, and the lane header sends it as `X-Ziggs-Agreement` beside `X-Ziggs-Lane`. The backend takes it only for an agreement the agent has mail under in that room.

package/dist/capabilities/artifacts.js

@@ -3,7 +3,7 @@ import { ARTIFACT_FILE_FORMATS, ArtifactsClient, } from '../http/ArtifactsClient
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient, } from '../http/ContextDiscoveryClient.js';
 import { fullCreds } from './types.js';
-import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { LIST_FIELDS_PARAM, listedFieldNote, parseListFields, pickListedRows } from './listedFields.js';
 import { nextCall } from './nextCall.js';
 /**
  * teaching: name the result slot on the success path so an agent finds
@@ -311,7 +311,11 @@ export const listArtifactsCapability = {
         });
         const fields = parseListFields(args['fields']);
         return fields
-            ? { ...listed, artifacts: pickListedRows(listed.artifacts, fields) }
+            ? {
+                ...listed,
+                artifacts: pickListedRows(listed.artifacts, fields),
+                ...listedFieldNote(listed.artifacts, fields),
+            }
             : listed;
     },
 };
@@ -418,7 +422,7 @@ export const findArtifactsCapability = {
         },
         includeUnreadable: {
             type: 'boolean',
-            description: 'Also list context you hold no grant on (labels only, never contents). Defaults on when nothing matched, since that is when an empty answer is most likely to be misread; pass true to ask for it alongside matches.',
+            description: 'Also list context you hold no grant on (labels only, never contents). When omitted, that list is attached only if nothing matched. Pass true to ask for it alongside matches. Pass false to leave it off.',
         },
         fields: LIST_FIELDS_PARAM,
     },
@@ -431,8 +435,14 @@ export const findArtifactsCapability = {
         });
         const fields = parseListFields(args['fields']);
         const shaped = fields
-            ? { ...found, artifacts: pickListedRows(found.artifacts, fields) }
+            ? {
+                ...found,
+                artifacts: pickListedRows(found.artifacts, fields),
+                ...listedFieldNote(found.artifacts, fields),
+            }
             : found;
+        if (args['includeUnreadable'] === false)
+            return shaped;
         const asked = args['includeUnreadable'] === true;
         if (!asked && found.artifacts.length > 0)
             return shaped;

package/dist/capabilities/chat.js

@@ -115,8 +115,8 @@ export const openConversationCapability = {
                 throw new Error('Group creation requires an idempotencyKey; reuse it when retrying');
             }
         }
-        else if (args.chatId || args.idempotencyKey) {
-            throw new Error('chatId and idempotencyKey require participantIds');
+        else if (args.chatId) {
+            throw new Error('chatId requires participantIds');
         }
         if (typeof args.name === 'string' && args.name.trim() && !Array.isArray(args.participantIds) && args.newChat !== true) {
             throw new Error('A name is for a new group or a newChat room. Pair rooms take no name; the person is the name.');

package/dist/capabilities/grants.js

@@ -1,7 +1,7 @@
 import { GrantsClient } from '../http/GrantsClient.js';
 import { GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fullCreds } from './types.js';
-import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { LIST_FIELDS_PARAM, listedFieldNote, parseListFields, pickListedRows } from './listedFields.js';
 // BOTH the tool's param enum and its validator, so a missing kind makes the
 // filter the description advertises fail validation. Derived from the canonical
 // list next to the type rather than restated, because that is exactly how
@@ -97,6 +97,7 @@ export const listGrantsCapability = {
         return {
             count: items.length,
             grants: pickListedRows(items, fields),
+            ...listedFieldNote(items, fields),
             nextCursor,
             ...(unreadableRails?.length ? { unreadableRails } : {}),
         };

package/dist/capabilities/index.d.ts

@@ -8,7 +8,7 @@ export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
-export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, listedFieldNote, } from './listedFields.js';
 export { CHAT_LIST_DEFAULT_FIELDS, projectChatListRows, utf8Bytes, approxTokens, } from './chatListFields.js';
 export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTaskOutcome, type TaskOutcomeEffects, type TaskOutcomePresentation, } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';

package/dist/capabilities/index.js

@@ -8,7 +8,7 @@ export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
-export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, listedFieldNote, } from './listedFields.js';
 export { CHAT_LIST_DEFAULT_FIELDS, projectChatListRows, utf8Bytes, approxTokens, } from './chatListFields.js';
 export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTaskOutcome, } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';

package/dist/capabilities/listedFields.d.ts

@@ -13,5 +13,16 @@ export declare const LIST_FIELDS_PARAM: {
     description: string;
 };
 export declare function parseListFields(raw: unknown): string[] | undefined;
+/** The value a caller asked for, including the names list rows actually store. */
+export declare function readListedField(row: Record<string, unknown>, key: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
 export declare function pickListedRow(row: Record<string, unknown>, fields: string[] | undefined): Record<string, unknown>;
+/** Names in `fields` that no row could resolve. Empty rows say nothing. */
+export declare function listedFieldNote(rows: unknown[], fields: string[] | undefined): {
+    unknownFields?: string[];
+};
 export declare function pickListedRows(rows: unknown[], fields: string[] | undefined): unknown[];

package/dist/capabilities/listedFields.js

@@ -8,7 +8,7 @@
 export const LIST_FIELDS_PARAM = {
     type: 'array',
     items: { type: 'string' },
-    description: 'Return only these keys on each row. Omit for the full row. Keep the id you will use next (agreementId, taskId, artifactId, grantId).',
+    description: 'Return only these keys on each row. Omit for the full row. Keep the id you will use next (agreementId, taskId, artifactId, grantId). A name no row has is listed in unknownFields.',
 };
 export function parseListFields(raw) {
     if (raw == null)
@@ -26,16 +26,67 @@ export function parseListFields(raw) {
     }
     return out;
 }
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The value a caller asked for, including the names list rows actually store. */
+export function readListedField(row, key) {
+    if (key in row)
+        return { found: true, value: row[key] };
+    const scope = asRecord(row.scope);
+    if (key === 'scopeKind' && scope && 'kind' in scope)
+        return { found: true, value: scope.kind };
+    if (key === 'scopeId' && scope && 'id' in scope)
+        return { found: true, value: scope.id };
+    const terms = asRecord(row.terms);
+    const description = typeof row.description === 'string'
+        ? row.description
+        : typeof terms?.description === 'string'
+            ? terms.description
+            : undefined;
+    if ((key === 'name' || key === 'title') && description !== undefined)
+        return { found: true, value: description };
+    if (key === 'name' && typeof row.title === 'string')
+        return { found: true, value: row.title };
+    if (key === 'title' && typeof row.name === 'string')
+        return { found: true, value: row.name };
+    if (key === 'agentId' && 'providerAgent' in row)
+        return { found: true, value: row.providerAgent };
+    if (key === 'providerId' && 'provider' in row)
+        return { found: true, value: row.provider };
+    if (key === 'kind' && 'engagementKind' in row)
+        return { found: true, value: row.engagementKind };
+    const parties = asRecord(row.parties);
+    const provider = asRecord(parties?.provider);
+    if (key === 'agentId' && provider && 'actor' in provider)
+        return { found: true, value: provider.actor };
+    if (key === 'providerId' && provider && 'principal' in provider)
+        return { found: true, value: provider.principal };
+    return { found: false };
+}
 export function pickListedRow(row, fields) {
     if (!fields)
         return row;
     const picked = {};
     for (const key of fields) {
-        if (key in row)
-            picked[key] = row[key];
+        const resolved = readListedField(row, key);
+        if (resolved.found)
+            picked[key] = resolved.value;
     }
     return picked;
 }
+/** Names in `fields` that no row could resolve. Empty rows say nothing. */
+export function listedFieldNote(rows, fields) {
+    if (!fields || rows.length === 0)
+        return {};
+    const unknown = fields.filter((key) => !rows.some((row) => {
+        const record = asRecord(row);
+        return record != null && readListedField(record, key).found;
+    }));
+    return unknown.length > 0 ? { unknownFields: unknown } : {};
+}
 export function pickListedRows(rows, fields) {
     if (!fields)
         return rows;

package/dist/capabilities/marketplace.js

@@ -2,7 +2,7 @@ import { marketplaceFormation } from '../engagementGuide.js';
 import { pullOffersPage, pullRequests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
-import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { LIST_FIELDS_PARAM, listedFieldNote, parseListFields, pickListedRows } from './listedFields.js';
 const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
     const claim = env.surface === 'mcp' ? 'ziggs_agreement_claim' : 'agreement_claim';
@@ -102,8 +102,11 @@ export const marketplaceViewCapability = {
         ]);
         const offers = offerPage.offers;
         const fields = parseListFields(args['fields']);
-        const requestRows = pickListedRows(requests.map((q) => toListingRow(q, 'request')), fields);
-        const offerRows = pickListedRows(offers.map((o) => toListingRow(o, 'offer')), fields);
+        const requestSource = requests.map((q) => toListingRow(q, 'request'));
+        const offerSource = offers.map((o) => toListingRow(o, 'offer'));
+        const requestRows = pickListedRows(requestSource, fields);
+        const offerRows = pickListedRows(offerSource, fields);
+        const fieldNote = listedFieldNote([...requestSource, ...offerSource], fields);
         const listingAgreementIds = [...requests, ...offers]
             .map((row) => row.agreementId)
             .filter((id) => typeof id === 'string' && id.length > 0);
@@ -128,6 +131,7 @@ export const marketplaceViewCapability = {
                         : {}),
                 }
                 : {}),
+            ...fieldNote,
             engagement,
             // Claiming is the move after browsing, and the id is in the row the
             // caller just received. The prose hint stays for the publish side, which

package/dist/capabilities/mcpBriefs.js

@@ -35,8 +35,7 @@ const BRIEFS = {
         returns: 'a readPlan of next calls; backlog if more is unread',
         next: 'ziggs_inbox_claim to handle them',
         compact: {
-            does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news.',
-            changes: 'takes or renews this host’s lease',
+            does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds long-polls. It takes or renews this host’s lease.',
             next: 'ziggs_inbox_ack after handling',
         },
     },

package/dist/capabilities/tasks.js

@@ -1,6 +1,6 @@
 import { cancelTask, listTasks } from '../http/TaskClient.js';
 import { fullCreds, rethrowWithContext, } from './types.js';
-import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { LIST_FIELDS_PARAM, listedFieldNote, parseListFields, pickListedRows } from './listedFields.js';
 import { nextCall, workContextFromEnv, } from './nextCall.js';
 /**
  * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
@@ -59,7 +59,11 @@ export const listTasksCapability = {
         }, creds);
         const fields = parseListFields(args['fields']);
         return fields
-            ? { ...listed, tasks: pickListedRows(listed.tasks, fields) }
+            ? {
+                ...listed,
+                tasks: pickListedRows(listed.tasks, fields),
+                ...listedFieldNote(listed.tasks, fields),
+            }
             : listed;
     },
 };

package/dist/http/AgreementClient.js

@@ -1,7 +1,7 @@
 import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
+import { ApiError, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
 import { buildCredsHeaders } from './operatorHeaders.js';
 // Lazy: read at call time so a `configureApiClient` call that lands after this
@@ -222,11 +222,11 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     // every link approval with "no pending approval entry".
     const agreement = opts.agreement ?? (await getAgreementDocument(agreementId, creds));
     if (!agreement) {
-        throw new Error(`Agreement ${agreementId} not found`);
+        throw new ApiError(`Agreement ${agreementId} not found`, 404);
     }
     const approval = agreement.approvalAction;
     if (approval && (approval.state !== 'available' || !approval.partyId)) {
-        throw new Error(`${approval.explanation}${opts.appUrl ? ` Review: ${opts.appUrl}` : ''}`);
+        throw new ApiError(`${approval.explanation}${opts.appUrl ? ` Review: ${opts.appUrl}` : ''}`, 403);
     }
     const partyId = approval?.partyId ?? resolveMyPendingApprovalPartyId(agreement, {
         ownerUserId: opts.ownerUserId,
@@ -246,11 +246,11 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
         // through ANY surface and the hand-off sat unclaimable forever. The
         // backend keeps a consented broadcast OPEN for claims.
         if (!partyId) {
-            throw new Error(`Agreement ${agreementId} is an open broadcast and has no personal approval slot — respond cannot ${action} it. Claim it with the claim tool (agreement_claim / ziggs_agreement_claim), or ignore it to pass.`);
+            throw new ApiError(`Agreement ${agreementId} is an open broadcast and has no personal approval slot — respond cannot ${action} it. Claim it with the claim tool (agreement_claim / ziggs_agreement_claim), or ignore it to pass.`, 403);
         }
     }
     else if (!partyId) {
-        throw new Error(`No pending approval entry for this operator on agreement ${agreementId}`);
+        throw new ApiError(`No pending approval entry for this operator on agreement ${agreementId}`, 403);
     }
     // If the slot is the principal's, the server accepts
     // only under a live approval-authority grant (else 403). Do not pre-refuse

package/package.json

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