@ziggs-ai/api-client 0.36.2 → 0.36.4

package/dist/capabilities/context.d.ts

@@ -20,6 +20,34 @@ export declare const contextReadCapability: CapabilityDefinition;
 export declare const contextExpandReachCapability: CapabilityDefinition;
 export declare const contextDiscoverGrantableCapability: CapabilityDefinition;
 export declare const contextDelegateCapability: CapabilityDefinition;
+/**
+ * One answer for "you cannot read this", whichever tool asked.
+ *
+ * A get that the server refuses (404 or 403) used to answer in its own words:
+ * agreement_get said "not found" for an agreement that exists and that the
+ * caller could ask for, and task_get said "not a party" for a task that does
+ * not exist. The server already judges this once, for open and access_explain:
+ * readable, unreadable with a request to make, or hidden (and hidden looks
+ * exactly like missing). A refused get asks that same judgement, so every tool
+ * gives the same outcome and the same recovery for the same case, and none
+ * reveals more than open already does.
+ *
+ * Null when the judgement says the caller may read it after all: the refusal
+ * was something else, and the caller reports its own error.
+ */
+export interface RefusedRead {
+    code: 'RESOURCE_HIDDEN' | 'RESOURCE_UNREADABLE';
+    outcome: 'hidden' | 'unreadable';
+    message: string;
+    ref: {
+        kind: string;
+        id: string;
+    };
+    actions?: unknown[];
+}
+export declare const RESOURCE_HIDDEN_MESSAGE = "Not found, or not available to you. The two look the same.";
+export declare const RESOURCE_UNREADABLE_MESSAGE = "This exists and you cannot read it yet. actions has the request to make.";
+export declare function explainRefusedRead(kind: 'agreement' | 'task' | 'chat' | 'artifact', id: string, env: CapabilityEnv): Promise<RefusedRead | null>;
 export declare const openCapability: CapabilityDefinition;
 export declare const accessExplainCapability: CapabilityDefinition;
 export declare const contextRequestCapability: CapabilityDefinition;

package/dist/capabilities/context.js

@@ -322,17 +322,47 @@ function presentOpenResult(result, env) {
         } : {}),
     };
 }
+export const RESOURCE_HIDDEN_MESSAGE = 'Not found, or not available to you. The two look the same.';
+export const RESOURCE_UNREADABLE_MESSAGE = 'This exists and you cannot read it yet. actions has the request to make.';
+export async function explainRefusedRead(kind, id, env) {
+    const creds = fullCreds(env);
+    let presented;
+    try {
+        const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
+        presented = presentOpenResult(await client.explain({ [`${kind}Id`]: id }), env);
+    }
+    catch {
+        return null;
+    }
+    const outcome = presented['outcome'];
+    if (outcome !== 'hidden' && outcome !== 'unreadable')
+        return null;
+    const actions = Array.isArray(presented['actions']) ? presented['actions'] : [];
+    return outcome === 'hidden'
+        ? { code: 'RESOURCE_HIDDEN', outcome, message: RESOURCE_HIDDEN_MESSAGE, ref: { kind, id } }
+        : {
+            code: 'RESOURCE_UNREADABLE',
+            outcome,
+            message: RESOURCE_UNREADABLE_MESSAGE,
+            ref: { kind, id },
+            ...(actions.length ? { actions } : {}),
+        };
+}
 export const openCapability = {
     key: 'open',
     names: { sdk: 'open', mcp: 'ziggs_open' },
     title: 'Open a returned resource',
     descriptions: {
-        sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document.',
+        sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document. To read a chat\'s messages under one agreement, use context_read with type=messages, via=chat:<id> and agreementId.',
     },
     annotation: 'read-only',
+    // agreementId here is the agreement to open, one id among four
+    // (OPEN_ID_PARAMS). It used to carry context_read's filter wording, so an
+    // agent passed it beside chatId as a filter and was refused by the
+    // exactly-one rule. Filtering a room's messages to one agreement is
+    // context_read's job, and the description says so.
     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/discovery.js

@@ -1,4 +1,5 @@
 import { AgentSearchClient } from '../http/AgentSearchClient.js';
+import { RESOURCE_HIDDEN_MESSAGE } from './context.js';
 import { fullCreds } from './types.js';
 export const agentSearchCapability = {
     key: 'agent_search',
@@ -83,7 +84,13 @@ export const agentGetCapability = {
         const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
         const result = await client.getAgentById(args['agentId']);
         if (!result.success) {
-            throw new Error(result.error ?? 'agent not found');
+            // A missing agent and one you may not see answer alike, in the words
+            // every read tool uses. There is nothing to request: an agent is reached
+            // through its listing or its person, not by access to its profile.
+            if (result.error === 'agent not found') {
+                throw Object.assign(new Error(RESOURCE_HIDDEN_MESSAGE), { code: 'RESOURCE_HIDDEN' });
+            }
+            throw new Error(result.error ?? 'Failed to get agent details');
         }
         const { success: _success, ...agent } = result;
         return { agent };

package/dist/capabilities/index.d.ts

@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
-export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, type RefusedRead, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/index.js

@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
-export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/mcpBriefs.js

@@ -125,7 +125,7 @@ const BRIEFS = {
     },
     // Reading context
     ziggs_open: {
-        does: 'Reads one artifact, chat, task or agreement by id, with the actions you may take and any recovery call. Hidden and unknown look the same.',
+        does: 'Reads one artifact, chat, task or agreement by id (exactly one id), with the actions you may take and any recovery call. Hidden and unknown look the same. A chat\'s messages under one agreement: ziggs_context_read with agreementId.',
     },
     ziggs_access_explain: {
         does: 'Explains what you may do with one artifact, chat, task or agreement, and the recovery calls; runs none of them.',

package/dist/http/ContextOpenClient.js

@@ -33,7 +33,9 @@ export class ContextOpenClient {
     async post(path, body) {
         const filled = ['artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
         if (filled.length !== 1) {
-            throw new Error('ContextOpenClient: pass exactly one of artifactId, chatId, taskId, agreementId');
+            // A caller's input mistake, named in the caller's words: the shared
+            // INVALID_INPUT code, and no internal class name in the sentence.
+            throw Object.assign(new Error('Pass exactly one of artifactId, chatId, taskId, agreementId.'), { code: 'INVALID_INPUT' });
         }
         const url = `${this.baseUrl || getBackendUrl()}${path}`;
         const res = await fetch(url, {

package/dist/http/PaymentsClient.d.ts

@@ -90,11 +90,6 @@ export declare class PaymentsClient {
         holderId: string;
         caveats?: unknown;
     }): Promise<PaymentGrantEnvelope>;
-    attenuateGrant({ grantId, holderId, caveats, }: {
-        grantId: string;
-        holderId: string;
-        caveats?: unknown;
-    }): Promise<PaymentGrantEnvelope>;
     revokeGrant(grantId: string): Promise<RevokeGrantResult>;
     /**
      * Live wallet grants the acting agent holds, via the unified GET /grants

package/dist/http/PaymentsClient.js

@@ -79,12 +79,6 @@ export class PaymentsClient {
     async issueGrant({ holderId, caveats }) {
         return (await this._post('/payments/grants', { holderId, caveats }));
     }
-    async attenuateGrant({ grantId, holderId, caveats, }) {
-        return (await this._post(`/payments/grants/${grantId}/attenuate`, {
-            holderId,
-            caveats,
-        }));
-    }
     async revokeGrant(grantId) {
         return (await this._request('DELETE', `/payments/grants/${grantId}`, undefined));
     }

package/package.json

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