@ziggs-ai/ziggs-mcp 0.41.6 → 0.41.8

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.41.8
+
+- Calling a tool Ziggs removed now answers with an error the assistant can act on, not the SDK's bare "not found". It says the tool was removed and the assistant's tool list is out of date, names the tool (or tools, with when to use each) that does the job now, and says what to do next: on the compact door, call the replacement through `ziggs_tool_read` or `ziggs_tool_write` and give the person the refresh steps; on the directory door, ask the person once to refresh Ziggs, with steps for ChatGPT, Claude, Cursor and Claude Code. The same message answers a call through either dispatcher and `ziggs_tools` describe, and the server sends the tool-list-changed signal on a session that has a stream. `ziggs_tools` search finds the replacement for a retired word. 87 removed tools are covered, and a test fails when a tool leaves the registered set without a row in `src/retiredTools.ts`.
+- Bucket tools no longer take `agreement` items: an agreement brings its people into a bucket rather than going into one. `bucketId` on the hire tools is the bucket the other side joins once the hire starts.
+
+## 0.41.7
+
+- `ziggs_artifact_share` is removed from every surface, the directory included: an artifact reaches people only by being added to a bucket.
+- The inbox groups rows by the bucket they were sent in: each section lists its buckets, each with `bucketId`, `revision`, `count` and its rows oldest first, every row saying its own `from`. Rows in no bucket you are in stay grouped by sender, then thread.
+- The compact door lists the bucket tools: create, list, read, insert, remove, duplicate, move (into another bucket or a new one), add members, join, send inside a bucket, remove a member, rename and delete.
+
 ## 0.41.6
 
 ## 0.41.5

package/README.md

@@ -160,7 +160,6 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution. Error
 | `ziggs_context_read` | `GET /context/read/:type` |
 | `ziggs_artifact_record` | `POST /artifacts` |
 | `ziggs_artifact_list` | `GET /artifacts` |
-| `ziggs_artifact_share` | `POST /context/artifacts/:id/share` |
 | `ziggs_artifact_attach` | `POST /tasks/:id/artifacts` or `POST /agreements/:id/artifacts`; exact message references use `ziggs_message_send` |
 | `ziggs_artifact_upload_url` | `POST /artifacts/upload-url` (+ optional S3 PUT) |
 | `ziggs_artifact_complete_file` | `POST /artifacts/:id/complete` |

package/dist/directorySurface.js

@@ -11,7 +11,7 @@ ziggs_agreement_respond ziggs_agreement_revoke ziggs_agreement_counter ziggs_agr
 ziggs_inbox_changes ziggs_inbox_peek ziggs_inbox ziggs_inbox_show ziggs_inbox_claim ziggs_inbox_ack ziggs_inbox_defer
 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
+ziggs_artifact_record ziggs_artifact_list ziggs_artifact_find
 ziggs_artifact_attach ziggs_artifact_contribution_review ziggs_artifact_contribute
 ziggs_artifact_upload_url ziggs_artifact_complete_file ziggs_artifact_download
 ziggs_message_read ziggs_message_send ziggs_message_replies ziggs_message_list ziggs_message_controls
@@ -34,7 +34,7 @@ const OPEN_WORLD = new Set(`
 ziggs_agent_search ziggs_agent_get ziggs_marketplace_view
 ziggs_agreement_buy ziggs_agreement_bid ziggs_agreement_broker ziggs_agreement_request
 ziggs_agreement_handoff ziggs_agreement_claim ziggs_agreement_subcontract
-ziggs_task_delegate ziggs_artifact_share ziggs_artifact_attach ziggs_artifact_contribute
+ziggs_task_delegate ziggs_artifact_attach ziggs_artifact_contribute
 ziggs_message_send ziggs_context_delegate ziggs_access_request
 ziggs_link_propose ziggs_introduction_mint ziggs_introduction_redeem
 `.trim().split(/\s+/));

package/dist/inboxCompact.d.ts

@@ -27,11 +27,12 @@
  * the ack step's — is passed through byte for byte.
  *
  * The rows are written grouped rather than as one flat list: by who they are
- * for, then by who sent them, then by the chat, task or agreement they are
- * about. A flat list mixed the assistant's own work with mail it
- * only passes along to its person and mail for the person's other
- * assistants, and the split lived in one sentence of counts. Every row is
- * still there, oldest first inside its thread; see {@link groupDeliveries}.
+ * for, then by the bucket they were sent in, or, outside a bucket, by who sent
+ * them and the chat, task or agreement they are about. A flat list mixed the
+ * assistant's own work with mail it only passes along to its person and mail
+ * for the person's other assistants, and the split lived in one sentence of
+ * counts. Every row is still there, oldest first inside its bucket or thread;
+ * see {@link groupDeliveries}.
  */
 type Json = Record<string, unknown>;
 /** One delivery row, without what it would say by default or elsewhere. */
@@ -54,20 +55,26 @@ export type InboxSection = (typeof INBOX_SECTIONS)[number];
  */
 export declare function sectionOf(row: Json, agentIds: readonly string[]): InboxSection;
 /**
- * The window's rows, grouped: section, then sender, then thread.
+ * The window's rows, grouped: section, then bucket, then the rows in it. A
+ * row in no bucket the reader is in goes under its sender, then its thread.
  *
- * Nothing is hidden and nothing is reordered within a thread. Senders and
- * threads are written in the order their oldest row arrived, which is the
- * order the server sends (oldest first), except that the reader's own actions
- * and their person's come last in a section: they are a record of what this
- * side did, not news from anyone.
+ * A bucket is the context its rows were sent in, so it holds them together
+ * whoever sent them: each of its rows says its own `from`, oldest first. The
+ * bucket's name and contents are a bucket read away; a reply to one of its
+ * messages goes back into it.
  *
- * A row drops only what its place in the grouping says: the sender (the
- * group's `from`), the thread's own id, the assignee in `forYou` when the
- * connection has one assistant, and `needsHuman` in `forYourPerson`. A thread
- * names the first agreement its rows sit under; a row under another one keeps
- * its own, and a row under none says `agreementId: null`, so every row reads
- * back exactly.
+ * Nothing is hidden and nothing is reordered within a bucket or a thread.
+ * Groups and threads are written in the order their oldest row arrived, which
+ * is the order the server sends (oldest first), except that the reader's own
+ * actions and their person's outside a bucket come last in a section: they
+ * are a record of what this side did, not news from anyone.
+ *
+ * A row drops only what its place in the grouping says: its bucket (the
+ * group's), the sender (a sender group's `from`), the thread's own id, the
+ * assignee in `forYou` when the connection has one assistant, and
+ * `needsHuman` in `forYourPerson`. A thread names the first agreement its
+ * rows sit under; a row under another one keeps its own, and a row under none
+ * says `agreementId: null`, so every row reads back exactly.
  */
 export declare function groupDeliveries(rows: readonly Json[], reader: InboxReader, compactRow?: (row: Json) => Json): Partial<Record<InboxSection, Json[]>>;
 /**

package/dist/inboxCompact.js

@@ -27,11 +27,12 @@
  * the ack step's — is passed through byte for byte.
  *
  * The rows are written grouped rather than as one flat list: by who they are
- * for, then by who sent them, then by the chat, task or agreement they are
- * about. A flat list mixed the assistant's own work with mail it
- * only passes along to its person and mail for the person's other
- * assistants, and the split lived in one sentence of counts. Every row is
- * still there, oldest first inside its thread; see {@link groupDeliveries}.
+ * for, then by the bucket they were sent in, or, outside a bucket, by who sent
+ * them and the chat, task or agreement they are about. A flat list mixed the
+ * assistant's own work with mail it only passes along to its person and mail
+ * for the person's other assistants, and the split lived in one sentence of
+ * counts. Every row is still there, oldest first inside its bucket or thread;
+ * see {@link groupDeliveries}.
  */
 const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /** Session fields `ziggs_auth_status` carries; the inbox does not repeat them. */
@@ -125,51 +126,77 @@ function anchorOf(row) {
         return ['agreementId', String(row.agreementId)];
     return [row.kind === 'artifact' ? 'artifactId' : 'resourceId', String(row.resourceId)];
 }
+/** The bucket the server says a row was put in, if any. */
+function bucketOf(row) {
+    const bucket = row.bucket;
+    if (!isRecord(bucket) || !bucket.bucketId)
+        return null;
+    return { bucketId: String(bucket.bucketId), revision: bucket.revision };
+}
 /**
- * The window's rows, grouped: section, then sender, then thread.
+ * The window's rows, grouped: section, then bucket, then the rows in it. A
+ * row in no bucket the reader is in goes under its sender, then its thread.
+ *
+ * A bucket is the context its rows were sent in, so it holds them together
+ * whoever sent them: each of its rows says its own `from`, oldest first. The
+ * bucket's name and contents are a bucket read away; a reply to one of its
+ * messages goes back into it.
  *
- * Nothing is hidden and nothing is reordered within a thread. Senders and
- * threads are written in the order their oldest row arrived, which is the
- * order the server sends (oldest first), except that the reader's own actions
- * and their person's come last in a section: they are a record of what this
- * side did, not news from anyone.
+ * Nothing is hidden and nothing is reordered within a bucket or a thread.
+ * Groups and threads are written in the order their oldest row arrived, which
+ * is the order the server sends (oldest first), except that the reader's own
+ * actions and their person's outside a bucket come last in a section: they
+ * are a record of what this side did, not news from anyone.
  *
- * A row drops only what its place in the grouping says: the sender (the
- * group's `from`), the thread's own id, the assignee in `forYou` when the
- * connection has one assistant, and `needsHuman` in `forYourPerson`. A thread
- * names the first agreement its rows sit under; a row under another one keeps
- * its own, and a row under none says `agreementId: null`, so every row reads
- * back exactly.
+ * A row drops only what its place in the grouping says: its bucket (the
+ * group's), the sender (a sender group's `from`), the thread's own id, the
+ * assignee in `forYou` when the connection has one assistant, and
+ * `needsHuman` in `forYourPerson`. A thread names the first agreement its
+ * rows sit under; a row under another one keeps its own, and a row under none
+ * says `agreementId: null`, so every row reads back exactly.
  */
 export function groupDeliveries(rows, reader, compactRow = (row) => ({ ...row })) {
     const sections = new Map();
     for (const row of rows) {
         const section = sectionOf(row, reader.agentIds);
+        let groups = sections.get(section);
+        if (!groups)
+            sections.set(section, (groups = new Map()));
+        const bucket = bucketOf(row);
+        if (bucket) {
+            const key = `bucket:${bucket.bucketId}`;
+            let group = groups.get(key);
+            if (!group)
+                groups.set(key, (group = { kind: 'bucket', ...bucket, rows: [] }));
+            group.rows.push(row);
+            continue;
+        }
         const from = row.actorId ? String(row.actorId) : null;
         const anchor = anchorOf(row);
-        let senders = sections.get(section);
-        if (!senders)
-            sections.set(section, (senders = new Map()));
-        let group = senders.get(String(from));
+        let group = groups.get(`from:${from}`);
         if (!group)
-            senders.set(String(from), (group = { from, threads: new Map() }));
+            groups.set(`from:${from}`, (group = { kind: 'sender', from, threads: new Map() }));
         const key = anchor.join(':');
         let thread = group.threads.get(key);
         if (!thread)
             group.threads.set(key, (thread = { anchor, rows: [] }));
         thread.rows.push(row);
     }
-    const own = (from) => from !== null && (reader.agentIds.includes(from) || from === reader.personId);
+    const own = (g) => g.kind === 'sender' &&
+        g.from !== null &&
+        (reader.agentIds.includes(g.from) || g.from === reader.personId);
     const out = {};
     for (const section of INBOX_SECTIONS) {
-        const senders = sections.get(section);
-        if (!senders)
+        const groups = sections.get(section);
+        if (!groups)
             continue;
-        const ordered = [...senders.values()];
+        const ordered = [...groups.values()];
         out[section] = [
-            ...ordered.filter((g) => !own(g.from)),
-            ...ordered.filter((g) => own(g.from)),
+            ...ordered.filter((g) => !own(g)),
+            ...ordered.filter((g) => own(g)),
         ].map((g) => {
+            if (g.kind === 'bucket')
+                return writeBucket(g, section, reader, compactRow);
             const threads = [...g.threads.values()].map((t) => writeThread(t, section, reader, compactRow));
             const count = [...g.threads.values()].reduce((n, t) => n + t.rows.length, 0);
             return {
@@ -183,6 +210,29 @@ export function groupDeliveries(rows, reader, compactRow = (row) => ({ ...row })
     }
     return out;
 }
+/** What a row's section already says about it. */
+function dropWhatTheSectionSays(row, section, reader) {
+    if (section === 'forYou') {
+        if (reader.agentIds.length === 1)
+            delete row.assigneeId;
+        if (row.assignedToConnection === true)
+            delete row.assignedToConnection;
+    }
+    if (section === 'forYourPerson')
+        delete row.needsHuman;
+}
+function writeBucket(group, section, reader, compactRow) {
+    const rows = group.rows.map((original) => {
+        const { actorId, ...row } = compactRow(original);
+        // Every row of one read carries the bucket's revision at that read; one
+        // that somehow differs keeps its own.
+        if (bucketOf(row)?.revision === group.revision)
+            delete row.bucket;
+        dropWhatTheSectionSays(row, section, reader);
+        return actorId ? { from: actorId, ...row } : row;
+    });
+    return { bucketId: group.bucketId, revision: group.revision, count: rows.length, rows };
+}
 function writeThread(thread, section, reader, compactRow) {
     const [field, id] = thread.anchor;
     const lifted = field === 'agreementId'
@@ -199,14 +249,7 @@ function writeThread(thread, section, reader, compactRow) {
             else if (!row.agreementId)
                 row.agreementId = null;
         }
-        if (section === 'forYou') {
-            if (reader.agentIds.length === 1)
-                delete row.assigneeId;
-            if (row.assignedToConnection === true)
-                delete row.assignedToConnection;
-        }
-        if (section === 'forYourPerson')
-            delete row.needsHuman;
+        dropWhatTheSectionSays(row, section, reader);
         return row;
     });
     return { [field]: id, ...(lifted ? { agreementId: lifted } : {}), rows };
@@ -299,5 +342,5 @@ export function windowNote(deliveries, selfAgentIds) {
     const parts = INBOX_SECTIONS.filter((s) => s === 'forYou' || count(s) > 0).map((s) => `${s} ${count(s)} (${words[s]})`);
     const reach = outOfReach ? ` ${outOfReach} of them ${outOfReach === 1 ? 'is' : 'are'} out of reach.` : '';
     const total = `${rows.length} ${rows.length === 1 ? 'delivery' : 'deliveries'}`;
-    return `Those counts are decisions and tasks, not messages. This window has ${total}, grouped by who they are for, then by sender: ${parts.join(', ')}.${reach}`;
+    return `Those counts are decisions and tasks, not messages. This window has ${total}, grouped by who they are for, then by bucket, or by sender outside a bucket: ${parts.join(', ')}.${reach}`;
 }

package/dist/retiredCalls.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Door } from './retiredTools.js';
+/**
+ * Answer a direct call to a removed tool with the removed-tool message, before
+ * the MCP SDK can say only that the tool was not found. Wraps whatever
+ * `tools/call` handler is installed, so call it after every other one.
+ *
+ * On a session that keeps an open stream, the tool-list-changed signal goes out
+ * as well, so an app that acts on it reloads its list without its person doing
+ * anything. A session with no stream has nobody to tell; that is not an error.
+ */
+export declare function answerRetiredCalls(server: McpServer, door: Door): void;

package/dist/retiredCalls.js

@@ -0,0 +1,29 @@
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { doorContext, retiredTool, retiredToolResult } from './retiredTools.js';
+/**
+ * Answer a direct call to a removed tool with the removed-tool message, before
+ * the MCP SDK can say only that the tool was not found. Wraps whatever
+ * `tools/call` handler is installed, so call it after every other one.
+ *
+ * On a session that keeps an open stream, the tool-list-changed signal goes out
+ * as well, so an app that acts on it reloads its list without its person doing
+ * anything. A session with no stream has nobody to tell; that is not an error.
+ */
+export function answerRetiredCalls(server, door) {
+    const inner = server.server;
+    const built = inner._requestHandlers?.get('tools/call');
+    if (!built)
+        return;
+    server.server.setRequestHandler(CallToolRequestSchema, (async (req, extra) => {
+        const retired = retiredTool(req.params.name);
+        if (!retired)
+            return built(req, extra);
+        try {
+            server.sendToolListChanged();
+        }
+        catch {
+            // No open stream on this session.
+        }
+        return retiredToolResult(req.params.name, retired, doorContext(server, door));
+    }));
+}

package/dist/retiredTools.d.ts

@@ -0,0 +1,62 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tools we removed, and what replaced them.
+ *
+ * An assistant that loaded its Ziggs tool list before a removal still holds the
+ * old name. Without this table the call dies on the MCP SDK's bare "not found",
+ * and the assistant tells its person Ziggs is broken. Every way of reaching a
+ * tool by name reads this table: a direct call, both dispatchers, and describe.
+ *
+ * Retired names are never registered, so they never appear in `tools/list`.
+ * Removing a tool adds its row in the same change; retiredTools.test.ts fails
+ * when a name leaves the registered set without one.
+ */
+export interface Replacement {
+    tool: string;
+    /** When to use this one, for a job that was split across several tools. */
+    when?: string;
+}
+export interface RetiredTool {
+    /** The tools that do the job now. Empty when nothing replaces it. */
+    use: Replacement[];
+    /** What changed, in one line. */
+    note?: string;
+}
+export declare const RETIRED_TOOLS: Readonly<Record<string, RetiredTool>>;
+export declare function retiredTool(name: string): RetiredTool | undefined;
+/** The replacement tools for a search word such as `commission` or `ziggs_quest`. */
+export declare function retiredReplacementsFor(needle: string): string[];
+export type Door = 'compact' | 'directory';
+/** How a person refreshes Ziggs in the app the connection came from. */
+export declare function refreshSteps(clientName: string | undefined): string;
+/**
+ * The tool result for a call to a removed tool: an ordinary error the assistant
+ * can act on. The compact door can call the replacement through its dispatcher
+ * at once; the directory door cannot call a tool that is not in its list, so
+ * its message asks the person to refresh, once.
+ */
+export declare function retiredToolResult(name: string, retired: RetiredTool, ctx: {
+    door: Door;
+    clientName?: string;
+}): {
+    structuredContent: {
+        error: {
+            code: string;
+            message: string;
+            retired: {
+                name: string;
+                replacements: Replacement[];
+            };
+        };
+    };
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/** Which door this server was built for, and the client's name once it has connected. */
+export declare function doorContext(server: McpServer, door: Door): {
+    door: Door;
+    clientName: string | undefined;
+};

package/dist/retiredTools.js

@@ -0,0 +1,174 @@
+import { toolError } from './toolError.js';
+const same = (tool, note) => ({ use: [{ tool }], ...(note ? { note } : {}) });
+const gone = (note) => ({ use: [], note });
+const split = (...use) => ({
+    use: use.map(([tool, when]) => ({ tool, when })),
+});
+/** One tool does the same job under a new name. */
+const RENAMED = [
+    ['ziggs_agreement_commission', 'ziggs_agreement_buy'],
+    ['ziggs_agreement_quest', 'ziggs_agreement_request'],
+    ['ziggs_cancel_task', 'ziggs_task_cancel'],
+    ['ziggs_chat_open', 'ziggs_message_send', 'There is no room to open; send the message.'],
+    ['ziggs_chat_send', 'ziggs_message_send'],
+    ['ziggs_claim_link_invite', 'ziggs_agreement_claim'],
+    ['ziggs_claim_offer', 'ziggs_agreement_claim'],
+    ['ziggs_connection_status', 'ziggs_auth_status'],
+    ['ziggs_context_request', 'ziggs_access_request'],
+    ['ziggs_conversation_send', 'ziggs_message_send'],
+    ['ziggs_counter_agreement', 'ziggs_agreement_counter'],
+    ['ziggs_create_link_invite', 'ziggs_link_propose'],
+    ['ziggs_create_party_connection_invite', 'ziggs_link_propose'],
+    ['ziggs_create_task', 'ziggs_task_create'],
+    ['ziggs_delegate_grant', 'ziggs_context_delegate'],
+    ['ziggs_discover_grantable', 'ziggs_context_discover_grantable'],
+    ['ziggs_expand_context', 'ziggs_context_expand_reach'],
+    ['ziggs_fulfill_agreement', 'ziggs_agreement_fulfill'],
+    ['ziggs_get_active_tasks', 'ziggs_task_list'],
+    ['ziggs_get_agent', 'ziggs_agent_get'],
+    ['ziggs_get_agreement', 'ziggs_agreement_get'],
+    ['ziggs_get_scope', 'ziggs_context_snapshot'],
+    ['ziggs_get_task', 'ziggs_task_get'],
+    ['ziggs_inbox_park', 'ziggs_inbox_defer'],
+    ['ziggs_issue_grant', 'ziggs_context_delegate'],
+    ['ziggs_link_create_invite', 'ziggs_link_propose'],
+    ['ziggs_list_connections', 'ziggs_connection_list'],
+    ['ziggs_list_grants', 'ziggs_grant_list'],
+    ['ziggs_list_links', 'ziggs_link_list'],
+    ['ziggs_list_messages', 'ziggs_message_list'],
+    ['ziggs_list_my_agreements', 'ziggs_agreement_list'],
+    ['ziggs_list_my_connections', 'ziggs_connection_list'],
+    ['ziggs_list_my_grants', 'ziggs_grant_list'],
+    ['ziggs_list_my_orgs', 'ziggs_org_list'],
+    ['ziggs_list_party_connections', 'ziggs_link_list'],
+    ['ziggs_list_tasks', 'ziggs_task_list'],
+    ['ziggs_open_conversation', 'ziggs_message_send'],
+    ['ziggs_pending_decisions', 'ziggs_inbox', 'A fresh inbox read carries the decisions.'],
+    ['ziggs_publish_quest', 'ziggs_agreement_request'],
+    ['ziggs_read_context', 'ziggs_context_read'],
+    ['ziggs_record_artifact', 'ziggs_artifact_record'],
+    ['ziggs_redeem_party_connection_invite', 'ziggs_agreement_claim'],
+    ['ziggs_request_connection_status', 'ziggs_connection_list'],
+    ['ziggs_request_link', 'ziggs_link_propose'],
+    ['ziggs_request_party_connection', 'ziggs_link_propose'],
+    ['ziggs_respond_to_agreement', 'ziggs_agreement_respond'],
+    ['ziggs_respond_to_party_connection', 'ziggs_agreement_respond'],
+    ['ziggs_revoke_agreement', 'ziggs_agreement_revoke'],
+    ['ziggs_revoke_grant', 'ziggs_context_revoke_grant'],
+    ['ziggs_revoke_link', 'ziggs_agreement_revoke'],
+    ['ziggs_revoke_party_connection', 'ziggs_agreement_revoke'],
+    ['ziggs_search_agents', 'ziggs_agent_search'],
+    ['ziggs_send_message', 'ziggs_message_send'],
+    ['ziggs_set_task_result', 'ziggs_task_set_result'],
+];
+const PROPOSE = split(['ziggs_agreement_buy', 'you pay a named party'], ['ziggs_agreement_bid', 'you offer your work to a named party'], ['ziggs_agreement_request', 'an open call for anyone'], ['ziggs_agreement_broker', 'you arrange a deal between others'], ['ziggs_agreement_handoff', 'you pass your work on to someone else'], ['ziggs_link_propose', 'you want a link']);
+const LISTING = gone("Posting and pausing a listing is the person's job in the web app. Claim someone's listing with ziggs_agreement_claim; browse with ziggs_marketplace_view.");
+const ROOMS = gone('Rooms are gone. Read with ziggs_inbox or ziggs_message_list.');
+const ANSWERS = gone('Messages are fyi or request now; there are no answer requests. Read replies with ziggs_message_replies.');
+const PAYMENT = gone('Agents do not move points. ziggs_payment_balance is the only payment tool.');
+const OTHER = [
+    ['ziggs_agreement_propose', PROPOSE],
+    ['ziggs_propose_agreement', PROPOSE],
+    ['ziggs_context_issue_grant', split(['ziggs_context_delegate', 'a slice of a grant you hold'], ['ziggs_bucket_insert', 'one file: add it to a bucket'])],
+    ['ziggs_conversation_read', split(['ziggs_message_read', 'one message'], ['ziggs_message_list', 'the whole thread, with conversationOf'])],
+    ['ziggs_discover_context', split(['ziggs_grant_list', 'what you hold'], ['ziggs_context_discover_grantable', 'what exists that you cannot read yet'])],
+    ['ziggs_list_artifacts', split(['ziggs_artifact_list', 'what you wrote'], ['ziggs_context_read', 'what is in a scope, with type artifacts'])],
+    ['ziggs_post_task_plan_step', split(['ziggs_task_replace_plan', 'the whole plan'], ['ziggs_task_update_steps', 'progress only'])],
+    ['ziggs_tool', split(['ziggs_tool_read', 'reads'], ['ziggs_tool_write', 'writes'])],
+    ['ziggs_agreement_offer', LISTING],
+    ['ziggs_publish_offer', LISTING],
+    ['ziggs_listing_pause', LISTING],
+    ['ziggs_listing_resume', LISTING],
+    ['ziggs_chat_list', ROOMS],
+    ['ziggs_list_chats', ROOMS],
+    ['ziggs_message_answers', ANSWERS],
+    ['ziggs_message_answer_cancel', ANSWERS],
+    ['ziggs_payment_attenuate_grant', PAYMENT],
+    ['ziggs_payment_hold', PAYMENT],
+    ['ziggs_payment_issue_grant', PAYMENT],
+    ['ziggs_payment_release', PAYMENT],
+    ['ziggs_payment_resolve_wallet', PAYMENT],
+    ['ziggs_payment_revoke_grant', PAYMENT],
+    ['ziggs_payment_transfer', PAYMENT],
+    ['ziggs_payment_wait_for_approval', PAYMENT],
+    ['ziggs_context_record_message', gone('Send messages with ziggs_message_send.')],
+    ['ziggs_context_record_thought', gone('Nothing replaces it. Save finished work with ziggs_artifact_record.')],
+    ['ziggs_get_subtasks', gone('Nothing replaces it. Nearest: ziggs_task_list, ziggs_task_get.')],
+    ['ziggs_mark_task_processing', gone('Nothing replaces it. Nearest: ziggs_inbox_claim.')],
+    ['ziggs_update_task_state', gone('Nothing replaces it. Finish with ziggs_task_set_result or stop with ziggs_task_cancel.')],
+    ['ziggs_switch_org', gone('The workspace is chosen when Ziggs is connected. See them with ziggs_org_list.')],
+    ['ziggs_request_connection', gone('Requesting a connection is not a Ziggs MCP tool any more. See yours with ziggs_connection_list.')],
+    ['ziggs_artifact_reextract', gone('Not an agent tool any more.')],
+    ['ziggs_provision_relay_workers', gone('Not an agent tool any more. Engage agents with the agreement tools and ziggs_task_create.')],
+];
+export const RETIRED_TOOLS = Object.freeze({
+    ...Object.fromEntries(RENAMED.map(([name, tool, note]) => [name, same(tool, note)])),
+    ...Object.fromEntries(OTHER),
+});
+export function retiredTool(name) {
+    return Object.hasOwn(RETIRED_TOOLS, name) ? RETIRED_TOOLS[name] : undefined;
+}
+/** The replacement tools for a search word such as `commission` or `ziggs_quest`. */
+export function retiredReplacementsFor(needle) {
+    const hits = new Set();
+    for (const candidate of [needle, `ziggs_${needle}`, `ziggs_agreement_${needle}`]) {
+        for (const entry of retiredTool(candidate)?.use ?? [])
+            hits.add(entry.tool);
+    }
+    return [...hits];
+}
+/** How a person refreshes Ziggs in the app the connection came from. */
+export function refreshSteps(clientName) {
+    const name = (clientName ?? '').toLowerCase();
+    if (name.includes('chatgpt') || name.includes('openai'))
+        return 'In ChatGPT: Settings → Apps & Connectors → Ziggs → Refresh. ChatGPT never refreshes by itself. On Business and Enterprise plans a workspace admin refreshes or republishes it.';
+    if (name.includes('cursor'))
+        return 'In Cursor: turn Ziggs off and on in MCP settings, or restart Cursor. Cursor ignores the list-changed signal.';
+    if (name.includes('claude-code') || name.includes('claude code'))
+        return 'In Claude Code: run /mcp and reconnect Ziggs, or start a new session.';
+    if (name.includes('claude'))
+        return 'In Claude: Settings → Connectors → Ziggs → ⋯ → refresh the tool list, or remove Ziggs and add it again.';
+    return "Reconnect Ziggs in the app's connector settings, or start a new conversation.";
+}
+/**
+ * The tool result for a call to a removed tool: an ordinary error the assistant
+ * can act on. The compact door can call the replacement through its dispatcher
+ * at once; the directory door cannot call a tool that is not in its list, so
+ * its message asks the person to refresh, once.
+ */
+export function retiredToolResult(name, retired, ctx) {
+    const lines = [`${name} was removed from Ziggs, so your list of Ziggs tools is out of date.`];
+    if (retired.note)
+        lines.push(retired.note);
+    if (retired.use.length === 1) {
+        lines.push(`Use ${retired.use[0].tool} for this now.`);
+    }
+    else if (retired.use.length > 1) {
+        lines.push(`This job is now done by more than one tool: ${retired.use.map((u) => `${u.tool} (${u.when})`).join('; ')}.`);
+    }
+    if (ctx.door === 'compact') {
+        lines.push(retired.use.length
+            ? 'Call the replacement now through ziggs_tool_read (read-only tools) or ziggs_tool_write (tools that change something), and also give your person these steps so your tool list is current:'
+            : 'Give your person these steps so your tool list is current:');
+    }
+    else {
+        lines.push('You cannot call a tool that is not in your list. Ask your person, once per conversation, to refresh Ziggs:');
+    }
+    lines.push(refreshSteps(ctx.clientName));
+    const result = toolError(lines.join(' '));
+    const error = {
+        ...result.structuredContent.error,
+        code: 'TOOL_RETIRED',
+        message: lines.join(' '),
+        retired: { name, replacements: retired.use },
+    };
+    return {
+        structuredContent: { error },
+        content: [{ type: 'text', text: JSON.stringify({ error }, null, 2) }],
+        isError: true,
+    };
+}
+/** Which door this server was built for, and the client's name once it has connected. */
+export function doorContext(server, door) {
+    return { door, clientName: server.server.getClientVersion()?.name };
+}

package/dist/server.js

@@ -10,6 +10,7 @@ import { loadConfig } from './config.js';
 import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
 import { applySurfacePolicy, listWithoutSchemaDialect } from './surface.js';
+import { answerRetiredCalls } from './retiredCalls.js';
 import { backendToolPick } from './toolPick.js';
 import { renderConnectText } from './protocol/connectText.js';
 import { CHANNEL_CAPABILITY, observeFor, startInboxChannel } from './inboxChannel.js';
@@ -44,6 +45,7 @@ export function createZiggsMcpServer(creds, cfg) {
     if (cfg.directConnection !== false)
         applySurfacePolicy(server, { pickTool: backendToolPick(creds) });
     listWithoutSchemaDialect(server);
+    answerRetiredCalls(server, cfg.directConnection === false ? 'directory' : 'compact');
     return server;
 }
 /** Drop this process's inbox host. Best-effort — shutdown must not fail on it. */

package/dist/surface.js

@@ -6,6 +6,7 @@ import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { textResult } from './capabilityAdapter.js';
 import { aliasMatches } from './toolAliases.js';
+import { doorContext, retiredReplacementsFor, retiredTool, retiredToolResult } from './retiredTools.js';
 import { pickLine } from './toolPick.js';
 import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry, } from './toolCatalog.js';
 /**
@@ -141,6 +142,9 @@ function registerDispatcher(server, lane) {
     }, lane.annotations, async ({ tool, args }) => {
         const entry = catalogEntry(server, tool);
         if (!entry) {
+            const retired = retiredTool(tool);
+            if (retired)
+                return retiredToolResult(tool, retired, doorContext(server, 'compact'));
             return toolError(`No such tool: ${tool}. Call ${TOOLS_CATALOG_NAME} for the full list of names.`);
         }
         // Each lane carries one kind of tool, so its annotation is true of every
@@ -218,6 +222,9 @@ export function applySurfacePolicy(server, opts = {}) {
                         unknown.push(name);
                 }
                 if (!found.length) {
+                    const retired = unknown.map((name) => [name, retiredTool(name)]).find(([, r]) => r);
+                    if (retired?.[1])
+                        return retiredToolResult(retired[0], retired[1], doorContext(server, 'compact'));
                     return toolError(`No such tool: ${unknown.join(', ')}. Call ${TOOLS_CATALOG_NAME} with no arguments for the full list of names.`);
                 }
                 return textResult({
@@ -250,7 +257,8 @@ export function applySurfacePolicy(server, opts = {}) {
             const rows = (needle
                 ? all.filter((e) => e.name.toLowerCase().includes(needle) ||
                     e.title.toLowerCase().includes(needle) ||
-                    aliasMatches(e.name, needle))
+                    aliasMatches(e.name, needle) ||
+                    retiredReplacementsFor(needle).includes(e.name))
                 : all).map((entry) => withCall(entry, catalogRow(entry)));
             return textResult({
                 count: rows.length,

package/dist/toolAliases.d.ts

@@ -13,15 +13,12 @@
  * appear in a catalog row, and cost nothing at connect time because the search
  * runs server-side.
  *
- * Two kinds of word belong here:
+ * The word belonging here is the plain-English word for the intent, when our
+ * name is a term of art: "hire" for claim (the default) and for buy (a direct
+ * proposal), "subcontract" for the parent-rail verb.
  *
- * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for claim (the default) and for buy (a direct proposal),
- *    "subcontract" for the parent-rail verb.
- * 2. A name we retired. `agreement_commission` and `agreement_quest` were
- *    renamed before the surface went public; anything still holding the old
- *    word searches it and lands on the tool that replaced it, rather than on
- *    nothing.
+ * A retired name is not an alias: retiredTools.ts holds those, and search
+ * reads it, so anything still holding an old name lands on its replacement.
  */
 export declare const SEARCH_ALIASES: Readonly<Record<string, readonly string[]>>;
 /** Does `needle` match one of this tool's aliases? Substring, both ways. */

package/dist/toolAliases.js

@@ -13,15 +13,12 @@
  * appear in a catalog row, and cost nothing at connect time because the search
  * runs server-side.
  *
- * Two kinds of word belong here:
+ * The word belonging here is the plain-English word for the intent, when our
+ * name is a term of art: "hire" for claim (the default) and for buy (a direct
+ * proposal), "subcontract" for the parent-rail verb.
  *
- * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for claim (the default) and for buy (a direct proposal),
- *    "subcontract" for the parent-rail verb.
- * 2. A name we retired. `agreement_commission` and `agreement_quest` were
- *    renamed before the surface went public; anything still holding the old
- *    word searches it and lands on the tool that replaced it, rather than on
- *    nothing.
+ * A retired name is not an alias: retiredTools.ts holds those, and search
+ * reads it, so anything still holding an old name lands on its replacement.
  */
 export const SEARCH_ALIASES = {
     ziggs_message_send: ['contact', 'message someone', 'teammate', 'group'],
@@ -30,14 +27,12 @@ export const SEARCH_ALIASES = {
     ziggs_agreement_claim: ['hire'],
     ziggs_agreement_buy: [
         'hire',
-        'commission', // retired name
         'procure',
         'outsource',
         'engage',
     ],
     ziggs_agreement_bid: ['sell', 'pitch', 'apply', 'tender', 'quote'],
     ziggs_agreement_request: [
-        'quest', // retired name
         'wanted',
         'open call',
         'rfp',

package/dist/tools.js

@@ -2,7 +2,7 @@ import { MESSAGING_CAPABILITIES } from '@ziggs-ai/api-client';
 import { isDirectorySurface } from './directorySurface.js';
 import { INBOX_CARD_TOOL_META, inboxCardResult, registerInboxCardResource, } from './inboxCard.js';
 import { z } from 'zod';
-import { presentResourceActions, getAgreement, getMyAgreements, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, ConnectionsClient, ContextReadClient, GrantsClient, InboxClient, SessionsClient, AssistantConnectionClient, createTask, updateTaskState, acknowledgeTaskControl, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_TERMS_PARAMS, AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, delegateTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, listedFieldNote, sessionOrientation, presentTaskOutcome, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, SOURCES_DESCRIPTION, } from '@ziggs-ai/api-client';
+import { presentResourceActions, getAgreement, getMyAgreements, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, ConnectionsClient, ContextReadClient, GrantsClient, InboxClient, SessionsClient, AssistantConnectionClient, createTask, updateTaskState, acknowledgeTaskControl, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, BUCKET_CAPABILITIES, AGREEMENT_TERMS_PARAMS, AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, attachArtifactCapability, reviewArtifactContributionCapability, contributeArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, delegateTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, listedFieldNote, sessionOrientation, 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';
@@ -801,6 +801,9 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     registerCapabilities(server, GRANTS_CAPABILITIES, creds);
+    // Buckets: compact door only until runs work in buckets; the directory
+    // allow-list leaves them out.
+    registerCapabilities(server, BUCKET_CAPABILITIES, creds);
     registerCapability(server, contextExpandReachCapability, creds);
     registerCapability(server, contextDiscoverGrantableCapability, creds);
     registerCapability(server, openCapability, creds);
@@ -827,7 +830,6 @@ export function registerZiggsTools(server, creds, cfg) {
     // question and carries its own honesty: what it searched, and what it could
     // not.
     registerCapability(server, findArtifactsCapability, creds);
-    registerCapability(server, shareArtifactCapability, creds);
     registerCapability(server, attachArtifactCapability, creds);
     registerCapability(server, reviewArtifactContributionCapability, creds);
     registerCapability(server, contributeArtifactCapability, creds);

package/dist/trustTools.d.ts

@@ -5,6 +5,6 @@ import type { ZiggsMcpConfig } from './config.js';
  * The SDK-twin tools (search/get, links, delegate) come from the shared
  * capability layer; only revoking a grant stays MCP-local. Issuing one is a
  * person's act (POST /context/grants takes a signed-in session), so there is
- * no agent tool for it: an agent shares with artifact_share, a chat_open
- * invite, or context_delegate. */
+ * no agent tool for it: an artifact reaches people through a bucket, and an
+ * agent passes on a slice of its own grant with context_delegate. */
 export declare function registerTrustTools(server: McpServer, creds: Creds, cfg?: ZiggsMcpConfig): void;

package/dist/trustTools.js

@@ -9,8 +9,8 @@ const DEFAULT_WEB_URL = 'https://ziggsai.com';
  * The SDK-twin tools (search/get, links, delegate) come from the shared
  * capability layer; only revoking a grant stays MCP-local. Issuing one is a
  * person's act (POST /context/grants takes a signed-in session), so there is
- * no agent tool for it: an agent shares with artifact_share, a chat_open
- * invite, or context_delegate. */
+ * no agent tool for it: an artifact reaches people through a bucket, and an
+ * agent passes on a slice of its own grant with context_delegate. */
 export function registerTrustTools(server, creds, cfg) {
     const webUrl = cfg?.ZIGGS_WEB_URL?.replace(/\/$/, '') ?? DEFAULT_WEB_URL;
     registerCapabilities(server, DISCOVERY_CAPABILITIES, creds);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.41.6",
+  "version": "0.41.8",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -51,13 +51,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.40.4",
+    "@ziggs-ai/api-client": "0.40.6",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {
-    "@ziggs-ai/agent-sdk": "0.46.3"
+    "@ziggs-ai/agent-sdk": "0.46.4"
   },
   "engines": {
     "node": ">=20"

package/skills/ziggs/references/grants-and-approvals.md

@@ -56,7 +56,7 @@ counterparty owner approves it, and unpublished delegates can then reach each ot
 3. Target human approves via **`ziggs_agreement_respond`** (action `approve`) when the
    pending link agreement shows in their inbox / `ziggs_link_list`. This is the same generic
    approval tool used for hire and service proposals: there is no separate link-response tool.
-4. **`ziggs_message_send`** with explicit readers, delivery recipients and any requested answer. To share existing context use **`ziggs_artifact_share`** for an exact artifact or **`ziggs_context_delegate`** for a bounded slice of a grant you hold. Contact, sharing and work remain separate operations.
+4. **`ziggs_message_send`** with explicit readers, delivery recipients and any requested answer. To give someone an artifact, add it to a bucket with them (**`ziggs_bucket_insert`**, or **`ziggs_bucket_create`** with items); use **`ziggs_context_delegate`** for a bounded slice of a grant you hold. Contact, sharing and work remain separate operations.
 5. To read their context, they grant it or you ask with **`ziggs_access_request`**.
 6. `ziggs_context_revoke_grant` when context access should end; **`ziggs_agreement_revoke`** when
    the agreement should end (any kind: hire, service, request, offer, or link).
@@ -83,4 +83,4 @@ which workspace it is, and call `ziggs_introduction_redeem` with `confirm: true`
 ## Web UI (Settings → Connections)
 
 Confusingly named after the *other* "connection" (this is the agent-link handshake UI, not
-`ziggs_connection_proxy` third-party connections). After an agent link appears under **Connected**, use your Claude delegate (MCP) for **`ziggs_message_send`**, **`ziggs_artifact_share`** or **`ziggs_context_delegate`**. The web UI manages handshake only, not chat or context grants.
+`ziggs_connection_proxy` third-party connections). After an agent link appears under **Connected**, use your Claude delegate (MCP) for **`ziggs_message_send`**, a bucket with them, or **`ziggs_context_delegate`**. The web UI manages handshake only, not chat or context grants.