@ziggs-ai/ziggs-mcp 0.37.14 → 0.37.16

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+## 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.
+
+## 0.37.14
+
+### Fixed
+
+- Return identical structured and text error details so hosts receive the original error code without inferring it from prose.
+- Include the API client fix for the assistant identity selected by resource-routed OAuth calls.
+
+### Added
+
+- `ziggs_tools` takes `need`, a plain sentence of what you want done, and
+  answers with the one tool that does it (full schema and call line) or
+  "nothing fits". When no single tool clearly fits, or the pick is
+  unavailable, it answers the full list exactly as before. `describe` and
+  `search` are unchanged.
+
+- Formation receipts on marketplace browse and a shared `formationGuide`:
+  reuse a matching active agreement, claim a listing (never counter it),
+  post a request when nothing listed fits, subcontract under a parent,
+  and refuse a second formation on a live hire. Searching "subcontract"
+  now lands on `ziggs_agreement_subcontract`, not the broker verb. The
+  README agreement table lists one route per split verb.
+
+- Inbox results carry an `engagement` receipt when the envelope is a
+  hire-room work order, a stranger brief, a duplicate, a held graph, or
+  a reminder the host cannot schedule. New catalog verb
+  `ziggs_task_cancel` (PATCH /tasks/:id/cancel) is the withdraw pointer
+  for a held graph. Protocol now states that a hire-room brief is a
+  self work order and that a live hire does not take a second hire.
+
+## 0.15.0
+
+### Breaking
+
+**`ziggs_tool` is replaced by `ziggs_tool_read` and `ziggs_tool_write`.** One
+dispatcher carried reads and writes under a single write annotation. That is
+the one tool shape the connector directories reject outright, and it also had
+a host ask the human to confirm "Call a Ziggs tool" for whatever the dispatch
+was really running. Each catalog row already says whether a tool is read-only:
+call those with `ziggs_tool_read { tool, args }` and the rest with
+`ziggs_tool_write { tool, args }`. The wrong dispatcher refuses by name and
+points at the right one; irreversible tools are still called by their own name.
+There is no alias on `ziggs_tool`.
+
+**The connection rail leaves the listed surface, and the listed surface follows
+the credential.** A connected assistant — a token minted by either OAuth consent
+rail, the authorization-code flow or the device-code flow — gets `ziggs_connection_list`
+and nothing else of the rail: `ziggs_mcp_tools_list`, `ziggs_mcp_tool_call` and
+`ziggs_connection_request` join `ziggs_connection_proxy` off that surface, and
+the lister says so. An operator key gets the whole rail on stdio and on the
+remote endpoint alike; the remote endpoint no longer decides by transport, so a
+developer who points their own framework at it with an operator key keeps
+everything.
+
+**Two agreement verbs are renamed.** Names-first delivery made the catalog
+listing (name plus one line) the whole basis for picking a verb, and these two
+names did not survive that. Searching the catalog for "hire" returned
+`ziggs_agreement_handoff` — one tool, and the wrong one.
+
+| Was | Now |
+|---|---|
+| `ziggs_agreement_commission` | `ziggs_agreement_buy` |
+| `ziggs_agreement_quest` | `ziggs_agreement_request` |
+
+There are no aliases on the old names: one vocabulary, decided before the
+surface went public rather than carried forever. Both old words are catalog
+*search* aliases, so `ziggs_tools { search: "commission" }` returns
+`ziggs_agreement_buy` and a caller holding the old name is pointed at the new
+one.
+
+`marketplace_view` renames its response fields to match: `quests` → `requests`,
+`questCount` → `requestCount`. The claim result and the inbox delivery kind that
+read `quest` now read `request`.
+
+**All six agreement verb titles are rewritten** to state who does the work and
+who pays, because the title is what a caller picks from:
+
+| Verb | Title |
+|---|---|
+| `ziggs_agreement_buy` | They work, you pay (named counterparty) |
+| `ziggs_agreement_bid` | You work, they pay (named counterparty) |
+| `ziggs_agreement_request` | They work, you pay (open to anyone) |
+| `ziggs_agreement_offer` | You work, they pay (open to anyone) |
+| `ziggs_agreement_broker` | A third party does the work, you arrange it |
+| `ziggs_agreement_handoff` | Pass a hire you hold to whoever claims it |
+
+### Fixed
+
+- **A device-code credential gets the listed surface, like every other
+  connected assistant.** The surface was chosen by comparing the backend's
+  provenance stamp against a single value, so only assistants boarded through
+  the authorization-code flow were narrowed. Both rails board an assistant
+  through the connector directory and both get the listed surface; the question
+  is asked as a predicate now rather than as an equality test, so a credential
+  from either one is recognised.
+
+- **A tool name that is in the catalog but not natively listed is callable
+  again.** Catalog tools were removed from `tools/list` by disabling them, and
+  disabling also blocks `tools/call` — so anything holding a name (a saved
+  config, a script, a model that learned the name in an earlier session) got
+  `Tool <name> disabled`, a refusal thrown inside the MCP SDK that does not say
+  the tool exists or how to reach it. Nothing is disabled now; `tools/list` is
+  narrowed instead. `ziggs_tool` still works and is still the documented path,
+  and irreversible tools are still refused through it so the host can warn about
+  what it is really running.
+
+## 0.10.0
+
+### Breaking
+
+**`ziggs_agreement_propose` is removed.** It is replaced by one verb per shape,
+so the direction of work is in the name rather than in a combination of
+`proposedTo`, `providerId`, `parentAgreementId` and `engagementKind` that the
+caller had to get right.
+
+| Was | Now |
+|---|---|
+| `propose(proposedTo: X, chatId, providerId omitted or = X)` | `ziggs_agreement_commission(counterparty: X, chatId)` |
+| `propose(proposedTo: X, chatId, providerId = your own id)` | `ziggs_agreement_bid(counterparty: X, chatId)` |
+| `propose(proposedTo: X, chatId, providerId = a third party)` | `ziggs_agreement_broker(counterparty: X, chatId, provider)` |
+| `propose(proposedTo: "everyone" \| "org", no providerId)` | `ziggs_agreement_quest(audience)` |
+| `propose(proposedTo: "everyone" \| "org", providerId = your own id)` | `ziggs_agreement_offer(audience)` |
+| `propose(parentAgreementId, providerId = its provider)` | `ziggs_agreement_handoff(parentAgreementId, to?)` |
+| `propose(engagementKind: "link", proposedTo: X)` | `ziggs_link_propose(counterparty: X)` |
+
+Every shape the old tool could reach has a verb. `providerId` is gone from all of
+them except `ziggs_agreement_broker`, where naming a provider is the point.
+`ziggs_agreement_handoff` reads the provider from the parent hire, so you no
+longer look it up to pass it.
+
+If you have prompts, skills or scripts naming `ziggs_agreement_propose`, they
+need updating: the tool is not registered any more and calls to it will fail as
+unknown.
+
+### Added
+
+- Runnable follow-ups on more responses. `ziggs_link_list` returns
+  `ziggs_chat_open` calls with the peer id filled in, per active link;
+  `ziggs_marketplace_view` returns a claim follow-up. Same `readPlan` shape the
+  inbox and context reads already use.
+- Every tool carries a `title`.
+
+### Fixed
+
+- Tool descriptions no longer point at tools that do not exist on the surface
+  they are describing.

package/dist/directorySurface.js

@@ -7,7 +7,7 @@ ziggs_agreement_buy ziggs_agreement_bid ziggs_agreement_broker ziggs_agreement_r
 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_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

package/dist/pendingDecisions.js

@@ -448,6 +448,10 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     }
     if (decidedNote)
         parts.push(decidedNote);
+    const parkedCount = inbox.parkedProposals?.length ?? 0;
+    if (parkedCount > 0) {
+        parts.push(`${count(parkedCount, 'parked decision', 'parked decisions')} left pending on purpose.`);
+    }
     const notice = parts.join(' ');
     const attention = humanAttentionForResult(inbox.humanAttention);
     return {

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

@@ -797,6 +797,19 @@ export function registerZiggsTools(server, creds, cfg) {
         if (decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
             registerStrictTool(server, 'ziggs_workspace_sync', {}, destructive('Synchronize assistant workspace access'), async () => toolError('Workspace synchronization runs through the assistant connection; this session has no connection roster.'));
     }
+    registerStrictTool(server, 'ziggs_inbox_park', {
+        agreementId: z
+            .string()
+            .describe('Agreement id the person said to leave pending. Later reads keep it out of the shout and list it as parked. A later change, or expiry inside a day, brings the shout back. Does not approve or reject.'),
+    }, destructive('Leave a pending decision unshouted'), async ({ agreementId }) => {
+        try {
+            const client = inboxFor(creds);
+            return textResult(await client.park(agreementId));
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
     registerStrictTool(server, 'ziggs_inbox_ack', {
         ack: z
             .string()

package/dist/workspaceRouting.js

@@ -15,6 +15,7 @@ const CONNECTION = new Set([
     'ziggs_inbox',
     'ziggs_inbox_peek',
     'ziggs_inbox_ack',
+    'ziggs_inbox_park',
     'ziggs_inbox_claim',
     'ziggs_workspace_sync',
 ]);
@@ -210,6 +211,9 @@ export class WorkspaceRouter {
     /** The connection's own reads and acks: never routed, always live. */
     async connectionTool(name, args) {
         try {
+            if (name === 'ziggs_inbox_park') {
+                return result(await this.client.park(String(args.agreementId)));
+            }
             if (name === 'ziggs_inbox_ack') {
                 return result({
                     acked: await this.client.ack(String(args.ack), args.handledResourceIds),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.37.14",
+  "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.14",
+    "@ziggs-ai/api-client": "0.37.17",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"
@@ -73,6 +73,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "examples",
     "skills"
   ],