@ziggs-ai/ziggs-mcp 0.37.15 → 0.37.16

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.37.16
+
+- Clarify the shared hiring instructions: a mandate governs the work; agent-initiated hires need a covering grant or approval on the existing agreement.
+
+- Expose existing-hire admission recovery through `ziggs_chat_open` and retain cached resource reference compatibility.
+- Use the shared API-client refusal formatter; surface actionable requests and approvers without telling assistants they must use a browser to hire.
+- Verify read-tool compatibility and workspace hire selection through the registered MCP transport, and preserve server decisions without inferring permission from error prose.
+
 ## 0.37.15
 
 - `ziggs_inbox_park` leaves one proposal pending. Later reads keep it out of the session card and name it as parked.

package/dist/toolError.d.ts

@@ -1,42 +1,6 @@
-/**
- * one error surface for every MCP tool.
- *
- * 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;
-    /**
-     * What the caller may pick from, when the refusal is a choice: the
-     * agreements of WORK_SELECTION_REQUIRED, the workspaces of
-     * WORKSPACE_SELECTION_REQUIRED. Carried through verbatim so an assistant can
-     * ask its human instead of re-reading the message.
-     */
-    choices?: unknown[];
-    /**
-     * The call that is the next step, when the server sent one: the access
-     * request of WORK_ACCESS_REQUIRED, ready to send. Carried through verbatim,
-     * 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
- * stable MCP shape.
- */
-export declare function classifyToolError(input: unknown): ToolErrorShape;
+import { type OperationError } from '@ziggs-ai/api-client';
+export type ToolErrorShape = OperationError;
+export declare const classifyToolError: (input: unknown) => OperationError;
 /**
  * MCP tool error result: machine-readable code + cleaned message (+ hint).
  *
@@ -56,7 +20,7 @@ export declare function refusalError(refusal: {
     actions?: unknown[];
 }): {
     structuredContent: {
-        error: ToolErrorShape;
+        error: OperationError;
     };
     content: {
         type: "text";
@@ -66,7 +30,7 @@ export declare function refusalError(refusal: {
 };
 export declare function toolError(input: unknown): {
     structuredContent: {
-        error: ToolErrorShape;
+        error: OperationError;
     };
     content: {
         type: "text";

package/dist/toolError.js

@@ -1,188 +1,5 @@
-/**
- * one error surface for every MCP tool.
- *
- * 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.
- */
-/**
- * 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, ' +
-    'ziggs_open the same resource using the same agent identity. For earlier chat ' +
-    'messages request temporal=from-start; replying also requires permission=reply. ' +
-    'Do not issue yourself a grant. A new room does not show this room\'s history.';
-// a human-authority denial is not "try again with more scope": no
-// retry by this caller can ever pass it, because the guard refuses on being an
-// agent at all, before it looks at what was asked. Without a next action the
-// only strategy left is repetition, which is what agents did.
-const HUMAN_AUTHORITY_HINT = 'This action is the account owner\'s to take, not yours — retrying will not ' +
-    'change that. Your paths: ziggs_context_delegate to pass on a narrower slice ' +
-    'of a grant you ALREADY hold, ziggs_artifact_share for an artifact you ' +
-    'authored, ziggs_access_request to ask for your own missing resource access, or tell your human to do it in the Ziggs app.';
-/**
- * What covers a conversation, refused. These arrive as 429 or 403,
- * and a 429 read as "rate limited" tells an agent to wait and retry, which can
- * never help: the writer has to hire the agent, or their person has to set up
- * the agreement. The backend's own code and sentence are the answer.
- */
-const COVERAGE_REFUSALS = new Set([
-    'CONVERSATION_ALLOWANCE_EXHAUSTED',
-    'CONTACT_POLICY_REFUSED',
-    'LISTING_PAUSED',
-    'CONVERSATION_COVERAGE_REQUIRED',
-    'CONVERSATION_COVERAGE_ENDED',
-    'CONVERSATION_NOT_FUNDED',
-    'CONVERSATION_SPONSORSHIP_REQUIRED',
-    'TASK_ONLY_AGENT',
-]);
-const COVERAGE_HINT = 'Not a rate limit: retrying will not change it. Tell the person you work ' +
-    'for what the message says; hiring an agent, or agreeing the terms that ' +
-    'cover this conversation, is their decision in the Ziggs app.';
-function codeForStatus(status) {
-    if (status === 401)
-        return 'NOT_AUTHENTICATED';
-    if (status === 403)
-        return 'NOT_AUTHORIZED';
-    if (status === 404)
-        return 'NOT_FOUND';
-    if (status === 409)
-        return 'CONFLICT';
-    if (status === 429)
-        return 'RATE_LIMITED';
-    if (status >= 500)
-        return 'UPSTREAM_ERROR';
-    if (status >= 400)
-        return 'BAD_REQUEST';
-    return 'TOOL_ERROR';
-}
-/**
- * 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 thrownFields(err) {
-    if (typeof err === 'string') {
-        return { message: err, status: null, code: null, choices: null };
-    }
-    if (typeof err !== 'object' || err === null) {
-        return { message: String(err), status: null, code: null, choices: 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, choices: choicesIn(o.body) };
-}
-/** The `recovery` call of a refusal body, when the server sent one. */
-function recoveryIn(body) {
-    if (typeof body !== 'string' || !body)
-        return null;
-    try {
-        const parsed = JSON.parse(body);
-        const recovery = parsed?.recovery;
-        if (!recovery || typeof recovery !== 'object' || Array.isArray(recovery))
-            return null;
-        // The server names its tools by verb; here they are the MCP tools, the
-        // same renaming an open's actions get.
-        const call = recovery;
-        return typeof call.tool === 'string' && !call.tool.startsWith('ziggs_')
-            ? { ...call, tool: `ziggs_${call.tool}` }
-            : call;
-    }
-    catch {
-        return null;
-    }
-}
-/** The `choices` list of a refusal body, when the server sent one. */
-function choicesIn(body) {
-    if (typeof body !== 'string' || !body)
-        return null;
-    try {
-        const parsed = JSON.parse(body);
-        return Array.isArray(parsed?.choices) && parsed.choices.length
-            ? parsed.choices
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Classify a thrown client error (or a plain string this layer raised) into a
- * stable MCP shape.
- */
-export function classifyToolError(input) {
-    const shape = classify(input);
-    const { choices } = thrownFields(input);
-    const recovery = typeof input === 'object' && input !== null
-        ? recoveryIn(input.body)
-        : null;
-    return {
-        ...shape,
-        ...(choices ? { choices } : {}),
-        ...(recovery ? { recovery } : {}),
-    };
-}
-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',
-            message,
-            hint: HUMAN_AUTHORITY_HINT,
-        };
-    }
-    // Can read the agreement, cannot work on it: the server's sentence and its
-    // recovery are the answer, and the generic scope hint would send the agent
-    // back for the read it already has.
-    if (machineCode === 'WORK_ACCESS_REQUIRED') {
-        return { code: machineCode, message };
-    }
-    if (machineCode && COVERAGE_REFUSALS.has(machineCode)) {
-        return { code: machineCode, message, hint: COVERAGE_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 };
-    }
-    const code = codeForStatus(status);
-    // 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',
-            message,
-            hint: HUMAN_AUTHORITY_HINT,
-        };
-    }
-    // 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',
-            message,
-            hint: SCOPE_DENIED_HINT,
-        };
-    }
-    return { code, message };
-}
+import { describeOperationError } from '@ziggs-ai/api-client';
+export const classifyToolError = (input) => describeOperationError(input, 'mcp');
 /**
  * MCP tool error result: machine-readable code + cleaned message (+ hint).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.37.15",
+  "version": "0.37.16",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.15",
+    "@ziggs-ai/api-client": "0.37.17",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"