@ziggs-ai/ziggs-mcp 0.37.15 → 0.37.18

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.37.18
+
+- Inspect notification health through a read-only assistant-connection status tool: explicit workspace, expiry, callback acceptance, retry timing and categorized failures, without callback URLs or signing secrets. Receipt is not proof of a host response. Preserve backend errors when observing through a connection.
+
+- Read small inbox deltas with an observation cursor that renews on use, independent of work acknowledgements. Preserve the recovery cursor when the stream limit is reached. Reuse it to wait for new arrivals despite older unhandled mail; available through both HTTP connection modes and MCP.
+
+## 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/directorySurface.js

@@ -2,12 +2,13 @@
 const directories = new WeakSet();
 export const DIRECTORY_TOOLS = new Set(`
 ziggs_auth_status ziggs_org_list ziggs_workspace_sync ziggs_context_snapshot
+ziggs_notification_status
 ziggs_agreement_list ziggs_agreement_get ziggs_chat_list ziggs_chat_open ziggs_chat_send
 ziggs_agreement_buy ziggs_agreement_bid ziggs_agreement_broker ziggs_agreement_request
 ziggs_agreement_handoff
 ziggs_agreement_claim ziggs_agreement_subcontract ziggs_marketplace_view
 ziggs_agreement_respond ziggs_agreement_revoke ziggs_agreement_counter ziggs_agreement_fulfill
-ziggs_inbox_peek ziggs_inbox ziggs_inbox_claim ziggs_inbox_ack ziggs_inbox_park
+ziggs_inbox_changes ziggs_inbox_peek ziggs_inbox ziggs_inbox_claim ziggs_inbox_ack ziggs_inbox_park
 ziggs_grant_list ziggs_context_expand_reach ziggs_context_discover_grantable
 ziggs_open ziggs_access_explain ziggs_context_read
 ziggs_artifact_record ziggs_artifact_list ziggs_artifact_find ziggs_artifact_share
@@ -25,7 +26,7 @@ ziggs_introduction_list ziggs_introduction_revoke ziggs_context_revoke_grant zig
  * in one workspace, so tools.ts registers it only when the key carries a
  * connection. Tests subtract this set for such a key.
  */
-export const CONNECTION_ONLY_DIRECTORY_TOOLS = new Set(['ziggs_workspace_sync']);
+export const CONNECTION_ONLY_DIRECTORY_TOOLS = new Set(['ziggs_workspace_sync', 'ziggs_notification_status']);
 /** Public discovery and actions accepting new counterparties or audiences. */
 const OPEN_WORLD = new Set(`
 ziggs_agent_search ziggs_agent_get ziggs_marketplace_view

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/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, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, SOURCES_DESCRIPTION, } from '@ziggs-ai/api-client';
+import { presentResourceActions, getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, ContextReadClient, GrantsClient, InboxClient, AssistantConnectionClient, 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, SOURCES_DESCRIPTION, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -613,6 +613,29 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
+    if (decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId) {
+        registerStrictTool(server, 'ziggs_notification_status', {
+            orgId: z.string().min(1).max(200).describe('Workspace ID.'),
+        }, readOnly('Notification status'), async ({ orgId }) => {
+            try {
+                return textResult(await new AssistantConnectionClient(creds).eventStatus(orgId));
+            }
+            catch (error) {
+                return toolError(error);
+            }
+        });
+    }
+    registerStrictTool(server, 'ziggs_inbox_changes', {
+        cursor: z.string().optional().describe('Observation cursor; reads renew it for 24h. Omit or restart on 410 to scan retained history. Never ack it.'),
+        waitSeconds: z.number().min(0).optional().describe('Wait up to 110 seconds for an unobserved delivery; use 55 during an active session.'),
+    }, readOnly('Read new inbox arrivals'), async ({ cursor, waitSeconds }) => {
+        try {
+            return textResult(await inboxFor(creds).getChanges({ cursor, waitSeconds }));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
     registerStrictTool(server, 'ziggs_inbox_peek', {
         waitSeconds: z
             .number()

package/dist/workspaceRouting.js

@@ -1,4 +1,5 @@
 import { isDirectorySurface } from './directorySurface.js';
+import { toolError } from './toolError.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { AssistantConnectionClient, withAssistantRequest, decodeOperatorKeyClaims, parseRef, } from '@ziggs-ai/api-client';
 import { formatInboxToolResult } from './inboxToolResult.js';
@@ -14,6 +15,8 @@ const CONNECTION = new Set([
     'ziggs_org_list',
     'ziggs_inbox',
     'ziggs_inbox_peek',
+    'ziggs_inbox_changes',
+    'ziggs_notification_status',
     'ziggs_inbox_ack',
     'ziggs_inbox_park',
     'ziggs_inbox_claim',
@@ -249,6 +252,15 @@ export class WorkspaceRouter {
                     instruction: `deliveries.forYou is your work; deliveries.forYourPerson is for your person to see. ${ASK_YOUR_HUMAN}`,
                 }, { agentIds: self.agentIds ?? [] });
             }
+            if (name === 'ziggs_notification_status') {
+                return result(await this.client.eventStatus(args.orgId));
+            }
+            if (name === 'ziggs_inbox_changes') {
+                return result(await this.client.getChanges({
+                    cursor: args.cursor,
+                    waitSeconds: args.waitSeconds,
+                }));
+            }
             if (name === 'ziggs_inbox_peek') {
                 return result(await this.client.request(`inbox/peek?wait=${Number(args.waitSeconds ?? 0)}`));
             }
@@ -258,6 +270,8 @@ export class WorkspaceRouter {
             return result({ count: workspaces.length, orgs: workspaces });
         }
         catch (error) {
+            if (name === 'ziggs_notification_status' || name === 'ziggs_inbox_changes')
+                return toolError(error);
             return refusal('CONNECTION_REQUEST_FAILED', error instanceof Error ? error.message : String(error));
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.37.15",
+  "version": "0.37.18",
   "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.18",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"