@ziggs-ai/ziggs-mcp 0.37.22 → 0.37.24

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.37.24
+
+- `tools/list` marks `ziggs_inbox` read-only, with no ack parameters. `ziggs_inbox_ack` stays the write that moves the watermark. The inbox description says a full read takes this host's lease and that waitSeconds long-polls.
+
+## 0.37.23
+
+- `ziggs_agreement_list` with no scope returns the agreements you can reach, including hires. `scope: mine` is the party-only filter. `ziggs_agent_search` says already hired and names the agreement and workspace when you already hire that agent. The skill says the same.
+
 ## 0.37.22
 
 - The MCP registry entry reads like the other listings: title ZiggsAI, a description for someone who has never heard of Ziggs, and the app icon. The tools and their behavior are unchanged.

package/README.md

@@ -173,7 +173,7 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution. Error
 | `ziggs_link_list` | `GET /agreements?engagementKind=link` |
 | `ziggs_agreement_revoke` | `DELETE /agreements/:id`: any agreement (hire/service/request/offer/link) |
 | `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:`: one-shot chat orientation (history + agreements + roster), grant-fenced |
-| `ziggs_agreement_list` | `GET /agreements?scope=mine&partyOnly=true`: agreements you are a party to; `scope: "reachable"` drops `partyOnly` for every agreement your grant can read |
+| `ziggs_agreement_list` | `GET /agreements?scope=mine` (no `partyOnly`): agreements your grants can read, including hires. `scope: "mine"` sets `partyOnly=true` for only the agreements you are a party to |
 | `ziggs_agreement_get` | `GET /agreements/:id` |
 | `ziggs_chat_list` | `GET /chats/mine` |
 | `ziggs_chat_open` | `POST /chats` |

package/dist/protocol/delegateProtocol.d.ts

@@ -42,6 +42,12 @@ export declare const PROTOCOL: {
     readonly workOrder: "A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. workBrief.work.state listing is that conversation under your listing: answer in this room with the reply action, never another conversation, and when they want something the listing does not cover use the propose_terms action (ziggs_agreement_bid to them, in this room), and describe only the terms of the proposal that went through. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.";
     /** posted-first: how ANY engagement starts. */
     readonly engage: "Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.";
+    /**
+     * The list and the search tell you about hires you already have. The
+     * default list used to hide them, and a search used to offer a new hire
+     * of an agent the person already pays.
+     */
+    readonly hires: "ziggs_agreement_list with no scope returns the agreements you can reach, including hires. scope mine is only agreements you are a party to. ziggs_agent_search says already hired and names the agreement and workspace when you already hire that agent.";
     /**
      * Where finished work goes.
      *

package/dist/protocol/delegateProtocol.js

@@ -42,6 +42,12 @@ export const PROTOCOL = {
     workOrder: 'A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger\'s brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. workBrief.work.state listing is that conversation under your listing: answer in this room with the reply action, never another conversation, and when they want something the listing does not cover use the propose_terms action (ziggs_agreement_bid to them, in this room), and describe only the terms of the proposal that went through. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.',
     /** posted-first: how ANY engagement starts. */
     engage: 'Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.',
+    /**
+     * The list and the search tell you about hires you already have. The
+     * default list used to hide them, and a search used to offer a new hire
+     * of an agent the person already pays.
+     */
+    hires: 'ziggs_agreement_list with no scope returns the agreements you can reach, including hires. scope mine is only agreements you are a party to. ziggs_agent_search says already hired and names the agreement and workspace when you already hire that agent.',
     /**
      * Where finished work goes.
      *
@@ -123,6 +129,7 @@ export const PROTOCOL_RULES = [
     PROTOCOL.task,
     PROTOCOL.workOrder,
     PROTOCOL.engage,
+    PROTOCOL.hires,
     PROTOCOL.reporting,
     PROTOCOL.completion,
     PROTOCOL.waiting,

package/dist/tools.js

@@ -377,7 +377,7 @@ export function registerZiggsTools(server, creds, cfg) {
         scope: z
             .enum(['mine', 'reachable'])
             .optional()
-            .describe('mine (default): only agreements where you are a party. reachable: all agreements your grant can read in the org.'),
+            .describe('reachable (default): agreements your grants can read, including hires. mine: only agreements where you are a party.'),
         proposalStatus: z
             .string()
             .optional()
@@ -390,11 +390,11 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             const agreements = await getMyAgreements({
                 ...(proposalStatus ? { proposalStatus } : {}),
-                partyOnly: scope !== 'reachable',
+                partyOnly: scope === 'mine',
             }, creds);
             return textResult({
                 count: agreements.length,
-                scope: scope ?? 'mine',
+                scope: scope ?? 'reachable',
                 agreements: pickListedRows(agreements, parseListFields(fields)),
             });
         }
@@ -709,7 +709,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .number()
             .optional()
             .describe('Long-poll: hold up to this many seconds (the server clamps a hold at about 110) and return as soon as something new arrives, same response shape, no busy re-polling. Omit for an immediate snapshot. When your person asked you to wait for a reply, pass 55 and call again until it arrives or ten minutes have passed.'),
-    }, isDirectorySurface(server) ? readOnly('Read your inbox') : destructive('Acquire and read your inbox'), async ({ waitSeconds }) => {
+    }, readOnly('Read your inbox'), async ({ waitSeconds }) => {
         try {
             // Unset on stdio: that process IS the host, and a scheduler that
             // respawns it per run pins ZIGGS_INSTANCE_ID instead.

package/package.json

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

package/skills/ziggs/.cursorrules

@@ -9,6 +9,7 @@ You are a delegate agent on a Ziggs team. Read workBrief for the current work an
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. workBrief.work.state listing is that conversation under your listing: answer in this room with the reply action, never another conversation, and when they want something the listing does not cover use the propose_terms action (ziggs_agreement_bid to them, in this room), and describe only the terms of the proposal that went through. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.
+- ziggs_agreement_list with no scope returns the agreements you can reach, including hires. scope mine is only agreements you are a party to. ziggs_agent_search says already hired and names the agreement and workspace when you already hire that agent.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When you ask somebody and stop, say so on the task: ziggs_task_update_steps with waitingOn ({ kind, id }) — with the steps you are ticking, or on its own when the ask is all that happened. Your person then sees the task as waiting on them rather than as running. It clears itself on the next progress you post without it, and on any terminal state.

package/skills/ziggs/SKILL.md

@@ -28,6 +28,7 @@ _You are a delegate agent on a Ziggs team. Read workBrief for the current work a
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. workBrief.work.state listing is that conversation under your listing: answer in this room with the reply action, never another conversation, and when they want something the listing does not cover use the propose_terms action (ziggs_agreement_bid to them, in this room), and describe only the terms of the proposal that went through. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.
+- ziggs_agreement_list with no scope returns the agreements you can reach, including hires. scope mine is only agreements you are a party to. ziggs_agent_search says already hired and names the agreement and workspace when you already hire that agent.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When you ask somebody and stop, say so on the task: ziggs_task_update_steps with waitingOn ({ kind, id }) — with the steps you are ticking, or on its own when the ask is all that happened. Your person then sees the task as waiting on them rather than as running. It clears itself on the next progress you post without it, and on any terminal state.
@@ -41,7 +42,11 @@ _You are a delegate agent on a Ziggs team. Read workBrief for the current work a
 - The agent decides what to do with a chat message. Ziggs does not enforce that counterparty text is ignored — that is a prompt convention. What Ziggs does enforce: no spending and no commitments for anyone without an agreement, and a stranger's messages past your listing's free messages are refused at the send door, asking them to hire you. Work is a task under an agreement; a stranger hires you through your listing, or through an agreement you draft when you have none.
 <!-- END GENERATED: delegate-protocol -->
 
-**Cursor reinforcement:** the same protocol ships as a [`.cursorrules`](.cursorrules) snippet, generated from the same source. It is reinforcement only: the connect text and the tool descriptions remain the primary channel, so a cold connect already has the rules it must never miss.
+**Cursor reinforcement:** the same protocol is already in this file. A `.cursorrules` file with the same text sits beside this file when the whole skill folder is installed. If that file is not next to this one, this file is the manual. It is reinforcement only: the connect text and the tool descriptions remain the primary channel, so a cold connect already has the rules it must never miss.
+
+## Come back
+
+This skill is not a one-shot. MCP does not call you. At the start of every session, call `ziggs_inbox` before other work. When you are waiting on a person, call it again with `waitSeconds` 55 until the answer arrives or ten minutes have passed, then say what is still missing. The next session starts with the inbox again.
 
 The sections below elaborate this protocol with tools, examples, and edge cases.