@ziggs-ai/ziggs-mcp 0.36.4 → 0.36.6

package/dist/toolError.d.ts

@@ -22,6 +22,15 @@ export interface ToolErrorShape {
      * the same shape an open's action recovery has.
      */
     recovery?: Record<string, unknown>;
+    /** hidden | unreadable, the same outcome open and access_explain give. */
+    outcome?: string;
+    /** The resource the outcome is about. */
+    ref?: {
+        kind: string;
+        id: string;
+    };
+    /** For an unreadable resource: the request to make, as open lists it. */
+    actions?: unknown[];
 }
 /**
  * Classify a thrown client error (or a plain string this layer raised) into a
@@ -35,6 +44,26 @@ export declare function classifyToolError(input: unknown): ToolErrorShape;
  * HTTP status and server `code` that decide the hint.
  * A plain string is still accepted for refusals this layer raises on its own.
  */
+/** A refused read, answered as open would: its outcome, and any request to make. */
+export declare function refusalError(refusal: {
+    code: string;
+    message: string;
+    outcome?: string;
+    ref?: {
+        kind: string;
+        id: string;
+    };
+    actions?: unknown[];
+}): {
+    structuredContent: {
+        error: ToolErrorShape;
+    };
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
 export declare function toolError(input: unknown): {
     structuredContent: {
         error: ToolErrorShape;

package/dist/toolError.js

@@ -5,6 +5,12 @@
  * `code`, `body` / `message`). No client-prefix strip, no HTTP-status regex,
  * no re-parsing a JSON body that was concatenated into the message string.
  */
+/**
+ * The shared refusal vocabulary every read tool answers in (hidden,
+ * unreadable, invalid input), so an assistant can branch on the code instead
+ * of parsing each tool's sentence.
+ */
+const SHARED_REFUSALS = new Set(['RESOURCE_HIDDEN', 'RESOURCE_UNREADABLE', 'INVALID_INPUT']);
 const SCOPE_DENIED_HINT = 'For missing access to a returned artifact, chat, agreement, or task, use ' +
     'ziggs_access_request with that original resource id and your purpose. It creates ' +
     'a pending access approval agreement; it grants no access. After approval, ' +
@@ -127,6 +133,9 @@ export function classifyToolError(input) {
 }
 function classify(input) {
     const { message, status, code: machineCode } = thrownFields(input);
+    if (machineCode && SHARED_REFUSALS.has(machineCode)) {
+        return { code: machineCode, message };
+    }
     if (machineCode === 'AGENT_LACKS_HUMAN_AUTHORITY') {
         return {
             code: 'AGENT_LACKS_HUMAN_AUTHORITY',
@@ -181,6 +190,17 @@ function classify(input) {
  * HTTP status and server `code` that decide the hint.
  * A plain string is still accepted for refusals this layer raises on its own.
  */
+/** A refused read, answered as open would: its outcome, and any request to make. */
+export function refusalError(refusal) {
+    const shape = { ...refusal };
+    return {
+        structuredContent: { error: shape },
+        content: [
+            { type: 'text', text: JSON.stringify({ error: shape }, null, 2) },
+        ],
+        isError: true,
+    };
+}
 export function toolError(input) {
     const shape = classifyToolError(input);
     return {

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { isDirectorySurface } from './directorySurface.js';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { presentResourceActions, getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, acknowledgeTaskControl, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, projectChatListRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
+import { presentResourceActions, getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, acknowledgeTaskControl, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, projectChatListRows, sessionOrientation, presentSendResult, presentTaskOutcome, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -12,7 +12,7 @@ import { agreementAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload,
 import { resolveMcpConnectionTarget, withMcpGatewayClient, } from './mcpConnectionTools.js';
 import { readOnly, write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
-import { toolError } from './toolError.js';
+import { refusalError, toolError } from './toolError.js';
 import { registerCapability, registerCapabilities, textResult, } from './capabilityAdapter.js';
 // the strict artifact write (fail loudly, return the artifactId)
 // moved into ArtifactsClient.writeStrict, shared with the SDK's artifact_record.
@@ -245,7 +245,33 @@ function inboxFor(creds) {
         sessionName: creds.sessionName,
     });
 }
+/** A get the server refused for reach (403) or existence (404). */
+function isReadRefusal(e) {
+    const status = e?.status;
+    return status === 403 || status === 404;
+}
 export function registerZiggsTools(server, creds, cfg) {
+    // A refused get answers as open would: the server's one judgement of
+    // hidden or unreadable, and for unreadable the request to make. When that
+    // judgement cannot be had, the original refusal stands (or, for a get that
+    // returned nothing at all, hidden).
+    const refusedRead = async (kind, id, cause) => {
+        const refusal = await explainRefusedRead(kind, id, {
+            creds,
+            webUrl: cfg.ZIGGS_WEB_URL,
+            surface: 'mcp',
+        });
+        if (refusal)
+            return refusalError(refusal);
+        return cause
+            ? toolError(cause)
+            : refusalError({
+                code: 'RESOURCE_HIDDEN',
+                message: RESOURCE_HIDDEN_MESSAGE,
+                outcome: 'hidden',
+                ref: { kind, id },
+            });
+    };
     // A binding check and nothing else. This used to also report the
     // pending/active counts and point at a separate decisions tool for the card,
     // which is how a session start came to cost three calls that each said some
@@ -359,10 +385,12 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             const agreement = await getAgreement(agreementId, creds);
             if (!agreement)
-                return toolError(`Agreement not found: ${agreementId}`);
+                return refusedRead('agreement', agreementId);
             return textResult({ agreement });
         }
         catch (e) {
+            if (isReadRefusal(e))
+                return refusedRead('agreement', agreementId, e);
             return toolError(e);
         }
     });
@@ -1027,10 +1055,12 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             const task = await getTask(taskId, creds);
             if (!task)
-                return toolError(`Task not found: ${taskId}`);
+                return refusedRead('task', taskId);
             return textResult({ task });
         }
         catch (e) {
+            if (isReadRefusal(e))
+                return refusedRead('task', taskId, e);
             return toolError(e);
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.36.4",
+  "version": "0.36.6",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.36.2",
+    "@ziggs-ai/api-client": "0.36.4",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"