@ziggs-ai/ziggs-mcp 0.9.1 → 0.9.2

package/dist/toolError.d.ts

@@ -1,26 +1,26 @@
 /**
  * ZIG-667 — one error surface for every MCP tool.
  *
- * Raw client exceptions read like
- *   `ContextReadClient.read messages 403 {"error":"not authorized for this scope"}`
- * — an internal class.method name, a raw HTTP status, and a raw backend body.
- * LLM callers stall on stack-trace prose; they recover from errors they can
- * parse. This module strips the internals, keeps a stable machine-readable
- * code, and for authorization denials says what to do next.
+ * ZIG-1124 — classify from the thrown {@link ApiError} fields (`status`,
+ * `code`, `body` / `message`). No client-prefix strip, no HTTP-status regex,
+ * no re-parsing a JSON body that was concatenated into the message string.
  */
 export interface ToolErrorShape {
     code: string;
     message: string;
     hint?: string;
 }
-/** Classify a raw client error message into a stable shape. */
-export declare function classifyToolError(rawMessage: string, knownStatus?: number | null): ToolErrorShape;
+/**
+ * Classify a thrown client error (or a plain string this layer raised) into a
+ * stable MCP shape.
+ */
+export declare function classifyToolError(input: unknown): ToolErrorShape;
 /**
  * MCP tool error result: machine-readable code + cleaned message (+ hint).
  *
  * Pass the caught error itself, not `err.message` — an `ApiError` carries the
- * HTTP status that decides the code and the hint (ZIG-1086). A plain string is
- * still accepted for refusals this layer raises on its own.
+ * HTTP status and server `code` that decide the hint (ZIG-1086 / ZIG-1124).
+ * A plain string is still accepted for refusals this layer raises on its own.
  */
 export declare function toolError(input: unknown): {
     content: {

package/dist/toolError.js

@@ -1,15 +1,10 @@
 /**
  * ZIG-667 — one error surface for every MCP tool.
  *
- * Raw client exceptions read like
- *   `ContextReadClient.read messages 403 {"error":"not authorized for this scope"}`
- * — an internal class.method name, a raw HTTP status, and a raw backend body.
- * LLM callers stall on stack-trace prose; they recover from errors they can
- * parse. This module strips the internals, keeps a stable machine-readable
- * code, and for authorization denials says what to do next.
+ * ZIG-1124 — classify from the thrown {@link ApiError} fields (`status`,
+ * `code`, `body` / `message`). No client-prefix strip, no HTTP-status regex,
+ * no re-parsing a JSON body that was concatenated into the message string.
  */
-const CLIENT_PREFIX = /^[A-Z][A-Za-z0-9]*Client\.[A-Za-z0-9_]+\s+/;
-const HTTP_STATUS = /(?:^|\s)([1-5]\d{2})(?=\s|$)/;
 const SCOPE_DENIED_HINT = 'You are not authorized for this scope. To get access: ask the counterparty ' +
     'to issue you a context grant (they run ziggs_context_issue_grant), or propose a ' +
     'bilateral link first (ziggs_agreement_propose with engagementKind "link"). Check what you can already ' +
@@ -39,51 +34,52 @@ function codeForStatus(status) {
         return 'BAD_REQUEST';
     return 'TOOL_ERROR';
 }
-/** Pull a human reason out of an embedded backend JSON body, if any. */
-function extractBodyReason(raw) {
-    const start = raw.indexOf('{');
-    if (start === -1)
-        return null;
-    try {
-        const parsed = JSON.parse(raw.slice(start));
-        const reason = parsed['error'] ?? parsed['message'];
-        return typeof reason === 'string' && reason.trim() ? reason.trim() : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * An `ApiError` from api-client, recognised by shape rather than `instanceof`:
  * a bundled or duplicated copy of the class would fail an identity check while
  * carrying exactly the fields we need.
  */
-function thrownStatus(err) {
-    if (typeof err !== 'object' || err === null)
-        return null;
-    const status = err.status;
-    return typeof status === 'number' && status >= 100 && status < 600 ? status : null;
+function thrownFields(err) {
+    if (typeof err === 'string') {
+        return { message: err, status: null, code: null };
+    }
+    if (typeof err !== 'object' || err === null) {
+        return { message: String(err), status: null, code: null };
+    }
+    const o = err;
+    const status = typeof o.status === 'number' && o.status >= 100 && o.status < 600
+        ? o.status
+        : null;
+    const code = typeof o.code === 'string' && o.code ? o.code : null;
+    const message = typeof o.message === 'string' && o.message ? o.message : String(err);
+    return { message, status, code };
 }
-/** Classify a raw client error message into a stable shape. */
-export function classifyToolError(rawMessage, knownStatus) {
-    const cleaned = rawMessage.replace(CLIENT_PREFIX, '').trim();
-    // ZIG-1086: the status is scraped from the message only as a LAST resort.
-    // `ApiError` carries it as a real field, and every caller that dropped it
-    // (passing `err.message` instead of `err`) landed here with nothing to match:
-    // "missing scope: context:admin" has no digits, so it fell through to a bare
-    // TOOL_ERROR and the agent never saw the recovery hint it needed.
-    const statusMatch = HTTP_STATUS.exec(cleaned);
-    const status = knownStatus ?? (statusMatch ? Number(statusMatch[1]) : null);
-    const bodyReason = extractBodyReason(cleaned);
+/**
+ * Classify a thrown client error (or a plain string this layer raised) into a
+ * stable MCP shape.
+ */
+export function classifyToolError(input) {
+    const { message, status, code: machineCode } = thrownFields(input);
+    if (machineCode === 'AGENT_LACKS_HUMAN_AUTHORITY') {
+        return {
+            code: 'AGENT_LACKS_HUMAN_AUTHORITY',
+            message,
+            hint: HUMAN_AUTHORITY_HINT,
+        };
+    }
+    if (machineCode === 'NOT_AUTHORIZED_FOR_SCOPE') {
+        return {
+            code: 'NOT_AUTHORIZED_FOR_SCOPE',
+            message,
+            hint: SCOPE_DENIED_HINT,
+        };
+    }
     if (status === null) {
-        return { code: 'TOOL_ERROR', message: cleaned || rawMessage };
+        return { code: 'TOOL_ERROR', message };
     }
     const code = codeForStatus(status);
-    // Prefer the backend's own reason over the transport framing.
-    const message = bodyReason ?? cleaned;
-    // The human-authority guard refuses every impersonated agent, whatever it
-    // asked for. Checked before the scope branch below: its message also mentions
-    // scopes, and "ask for a grant on this scope" is the wrong advice here.
+    // Backend human-authority already sends AGENT_LACKS_HUMAN_AUTHORITY; keep a
+    // message fallback for older bodies / tests that omit `code`.
     if (code === 'NOT_AUTHORIZED' && /impersonated agent cannot perform/i.test(message)) {
         return {
             code: 'AGENT_LACKS_HUMAN_AUTHORITY',
@@ -91,9 +87,8 @@ export function classifyToolError(rawMessage, knownStatus) {
             hint: HUMAN_AUTHORITY_HINT,
         };
     }
-    // Context-scope denials (the backend says "…for this scope") get the scope
-    // code and a recovery path. Other 403s (connection grants, party checks)
-    // keep the generic code — their fixes live in other domains.
+    // Many scope denials still throw a bare ForbiddenException string with no
+    // machine code — classify those by the word "scope" in the message.
     if (code === 'NOT_AUTHORIZED' && /\bscope\b/i.test(message)) {
         return {
             code: 'NOT_AUTHORIZED_FOR_SCOPE',
@@ -107,14 +102,11 @@ export function classifyToolError(rawMessage, knownStatus) {
  * MCP tool error result: machine-readable code + cleaned message (+ hint).
  *
  * Pass the caught error itself, not `err.message` — an `ApiError` carries the
- * HTTP status that decides the code and the hint (ZIG-1086). A plain string is
- * still accepted for refusals this layer raises on its own.
+ * HTTP status and server `code` that decide the hint (ZIG-1086 / ZIG-1124).
+ * A plain string is still accepted for refusals this layer raises on its own.
  */
 export function toolError(input) {
-    const message = typeof input === 'string'
-        ? input
-        : (input?.message ?? String(input));
-    const shape = classifyToolError(String(message), thrownStatus(input));
+    const shape = classifyToolError(input);
     return {
         content: [
             { type: 'text', text: JSON.stringify({ error: shape }, null, 2) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.9.0",
+    "@ziggs-ai/api-client": "^0.9.1",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },