@ziggs-ai/ziggs-mcp 0.5.0 → 0.5.1

package/dist/protocol/delegateProtocol.d.ts

@@ -18,7 +18,7 @@ export declare const PROTOCOL: {
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     readonly loop: "Flow: inbox → read → act → ack.";
     /** Watermark discipline — reading is side-effect-free; ack is explicit. */
-    readonly ack: "Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.";
+    readonly ack: "Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it.";
     readonly neverRewind: "Never rewind an ack to an older timestamp.";
     /** Tasks are the unit of work. */
     readonly task: "Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.";

package/dist/protocol/delegateProtocol.js

@@ -18,7 +18,7 @@ export const PROTOCOL = {
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     loop: 'Flow: inbox → read → act → ack.',
     /** Watermark discipline — reading is side-effect-free; ack is explicit. */
-    ack: "Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.",
+    ack: "Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it.",
     neverRewind: 'Never rewind an ack to an older timestamp.',
     /** Tasks are the unit of work. */
     task: 'Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.',

package/dist/tools.js

@@ -22,13 +22,12 @@ import { registerCapability, registerCapabilities, textResult, } from './capabil
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
 // from the shared const so this description can't drift from SKILL / server
 // instructions / .cursorrules.
-const ZIGGS_INBOX_DESCRIPTION = "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. " +
-    'For org/agreement scopes each entry includes a `chats` breakdown (chatId + per-chat counts) so you can open the conversations behind the count — read them with ziggs_read_context (type=messages, via=chat:<chatId>). ' +
-    'When grants overlap on the same chat (chat + agreement + org), news is attributed to exactly one scope — narrowest wins (chat, then agreement, then org); ack that scope to clear it (covering wider scopes advance too). ' +
+const ZIGGS_INBOX_DESCRIPTION = "What's addressed to you since your last ack — references only, never content: `deliveries` (newest first) with a per-chat `chats` fold, plus assigned open tasks and agreement proposals awaiting your response. " +
+    'Open the conversations behind the references with ziggs_read_context (type=messages, via=chat:<chatId>). ' +
     `${PROTOCOL.humanAttention} ${PROTOCOL.pendingDecisions} ` +
     'When hasActionable the response carries the pending/active counts and points to ziggs_pending_decisions for the sessionChatCard to paste (that tool owns the card; it is not duplicated here). ' +
-    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each scope and ack; when the plan overflows, `readPlanTruncated` counts the reads it dropped (the ack call is always kept). ' +
-    'Each scope also carries the covering `grant` (grantId, temporal, watermarkAt, expiresAt), and readPlan reads come pre-pinned with that contextGrantId, so no separate ziggs_list_grants call is needed. ' +
+    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each chat and ack; when the plan overflows, `readPlanTruncated` counts the reads it dropped (the ack call is always kept). ' +
+    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_list_grants call is needed. ' +
     `${PROTOCOL.loop} ${PROTOCOL.ack}`;
 const ZIGGS_PENDING_DECISIONS_DESCRIPTION = 'Session start summary: approve/reject decisions AND active tasks assigned to your delegate. ' +
     'Call at session start in Cursor/Claude — pull-only MCP has no notification tray. ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {

package/skills/ziggs/.cursorrules

@@ -4,7 +4,7 @@
 You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).

package/skills/ziggs/SKILL.md

@@ -23,7 +23,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
@@ -41,11 +41,11 @@ The sections below elaborate this protocol with tools, examples, and edge cases.
 1. Call **`ziggs_auth_status`** after OAuth connect — check **`actingOrgId`** / **`actingOrgName`** (runtime org, not JWT). Org is fixed at consent (ZIG-852).
 2. To act in another org: **reconnect MCP OAuth** and pick that org on the consent screen, then re-check **`ziggs_auth_status`**. Use **`ziggs_list_my_orgs`** to help the human choose a target org name before reconnecting.
 3. Call **`ziggs_pending_decisions`** — if `pendingCount > 0`, **paste `decisionChatCard` for the human** before anything else. Wait for explicit approve/reject; then `ziggs_respond_to_agreement`.
-3. Call **`ziggs_inbox`** (optionally pass **`ack`** for scopes you already handled in the prior turn).
-4. Read the envelope: scope news counts, `humanAttention`, and **`decisionChatCard`** when present.
-5. Do **not** pull full scope history “just in case.” Only read scopes that show news or that you must act on.
+3. Call **`ziggs_inbox`** (optionally pass **`ack`** — the prior envelope's `ackTo` — once that turn's items are handled).
+4. Read the envelope: `deliveries` + per-chat `chats` fold, assigned tasks, `humanAttention`, and **`decisionChatCard`** when present.
+5. Do **not** pull full chat history “just in case.” Only read the chats the envelope names or work you must act on.
 
-If `ziggs_inbox` is unavailable, fall back to **`ziggs_list_grants`** (scopeKind: chat/agreement/org) to list reachable scopes, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
+If `ziggs_inbox` is unavailable, fall back to **`ziggs_list_grants`** (scopeKind: chat/agreement/org) to list what you can reach, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
 
 ## The working loop
 
@@ -58,7 +58,7 @@ inbox → read (delta) → act → ack
 | Doorbell | `ziggs_inbox` | References and counts only — never content |
 | Read | `ziggs_read_context` | One type at a time (`messages`, `artifacts`, …); use `via`, `after` / `cursor`, `limit` |
 | Act | `ziggs_send_message`, agreement tools, artifacts, grants | Side effects only after you understand the delta |
-| Ack | `ziggs_inbox` with `ack` | Pass each handled scope’s `latestAt` as `upTo`; ack **after** act, not before |
+| Ack | `ziggs_inbox` with `ack` | Pass the envelope’s `ackTo`; ack **after** act, not before |
 
 **Watermark discipline:** reading does not advance delivery state. Ack only what you finished processing. Never rewind an ack to an older timestamp.
 
@@ -66,8 +66,8 @@ inbox → read (delta) → act → ack
 
 - Prefer **forward deltas** (`after` + small `limit`) over full history.
 - When `hasMore` is true, continue with `nextCursor` — do not widen to “read everything.”
-- Match **`via`** to the scope kind from inbox (`chat:…`, `agreement:…`, `task:…`).
-- Pin reads with **`contextGrantId`** when the tool accepts it and you know which grant covers the scope.
+- Match **`via`** to the reference from inbox (`chat:…`, `agreement:…`, `task:…`).
+- Pin reads with **`contextGrantId`** when the tool accepts it and you know which grant covers the read.
 
 See [references/inbox-rhythm.md](references/inbox-rhythm.md) for a full catch-up example.
 
@@ -96,7 +96,7 @@ When coordinating with another org’s delegate:
 1. Inbox → read new messages in the shared chat.
 2. Reply with **`ziggs_send_message`** or drive **`ziggs_propose_agreement`** / **`ziggs_respond_to_agreement`** as appropriate.
 3. If trust is missing, **`ziggs_search_agents`** → human picks counterparty → **`ziggs_issue_grant`** (with approval) before reading their context.
-4. Ack handled scopes before ending the turn.
+4. Ack the handled envelope (`ackTo`) before ending the turn.
 
 ## Boarding checklist (cold session)
 

package/skills/ziggs/references/inbox-rhythm.md

@@ -6,7 +6,7 @@
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
@@ -17,43 +17,56 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 
 ## Mental model
 
-- **Inbox** = doorbell (references + counts since last ack).
-- **Read** = door (content, one scope and type at a time).
-- **Push** (if the host supports it) = optional hint — still run inbox on every session start and after reconnect.
+- **Inbox** = doorbell (references addressed to you since your last ack — never content).
+- **Read** = door (content, fenced by your grants when you open it).
+- The envelope has two kinds of channel:
+  - **Deliveries** — things addressed to you (`deliveries`, folded by chat in
+    `chats`). Cleared by acking `ackTo`.
+  - **Standing state** — open tasks assigned to you and proposals awaiting your
+    response. These appear on every read until the task closes or the proposal
+    is answered; acking does not clear them, finishing the work does.
 
 ## Catch-up example
 
 Counterparty sent 3 chat messages and 1 agreement proposal while you were offline.
 
-1. **`ziggs_inbox`** (no ack yet)  
-   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`, and **`humanAttention.promptUser`** when proposals await the human. No message bodies in the response. **Surface `humanAttention` to the human before reading or acting.**
+1. **`ziggs_inbox`** (no ack yet)
+   Expect: `chats: [{ chatId, count: 3, latestAt }]`, the same three references
+   in `deliveries`, one proposal in `proposalsAwaitingMe`, an `ackTo`, and
+   **`humanAttention.promptUser`** when proposals await the human. No message
+   bodies in the response. **Surface `humanAttention` to the human before
+   reading or acting.** The response's `readPlan` carries these exact calls
+   pre-filled — you can run it verbatim instead of assembling them.
 
-2. **`ziggs_read_context`**  
-   - `type: messages`, `via: chat:<id>`, `after: <scope.since from inbox>`, reasonable `limit`  
+2. **`ziggs_read_context`**
+   - `type: messages`, `via: chat:<chatId>` from the `chats` fold, reasonable `limit`
    - Read in pages until you have the three new messages.
 
-3. **Act**  
+3. **Act**
    - Reply via `ziggs_send_message`, or respond to the proposal via `ziggs_respond_to_agreement`.
 
-4. **`ziggs_inbox`** with `ack: [{ kind, id, upTo: latestAt }]` for each scope you finished.  
-   Use each scope entry’s **`latestAt`** as `upTo`.
+4. **`ziggs_inbox`** with `ack: <ackTo from step 1>`.
+   One watermark covers everything the envelope carried. Ack after acting, not
+   after reading — a crash in between redelivers instead of losing the item.
 
-5. **`ziggs_inbox`** again — scoped news for handled chat should be empty. Proposals clear when responded, not on ack alone.
+5. **`ziggs_inbox`** again — `deliveries` should be empty. Proposals clear when
+   responded, open tasks when they close; neither clears on ack alone.
 
-## Org / agreement scopes — which chats?
+## Which chat is the news in?
 
-A `chat` scope's id *is* the chatId. For an **org** or **agreement** scope the
-count spans many chats, so the entry includes a **`chats`** breakdown:
+Every delivery names its `chatId` (or `agreementId`/`taskId` for non-chat
+events), and the `chats` fold groups them:
 
 ```
-{ scope: { kind: "org", id: "<orgId>" }, newMessages: 12, chats: [
-    { chatId: "<id>", newMessages: 5, newArtifacts: 0, latestAt: "…" }, … ] }
+{ deliveries: [{ kind: "message", chatId: "<id>", ts: "…" }, …],
+  chats: [{ chatId: "<id>", count: 5, latestAt: "…" }, …],
+  ackTo: "…" }
 ```
 
 Open each conversation by its `chatId` with `ziggs_read_context`
-(`type: messages, via: chat:<chatId>`). Your org/scope grant covers those
-chats without explicit membership. If **`truncatedChats`** is set, more chats
-have news than are listed — handle and ack the listed ones, then re-run inbox.
+(`type: messages, via: chat:<chatId>`). Being addressed does not widen what
+you may read — the read is still fenced by your grants, so a reference you
+cannot open (revoked grant, deleted chat) is safe to skip and ack past.
 
 ## Deduping push + inbox
 
@@ -64,4 +77,7 @@ If the host delivers a push notification and you also poll inbox:
 
 ## Rate and bounds
 
-- Inbox scopes and counts are capped; respect **`truncatedScopes`** / **`truncatedProposals`** — fetch again or narrow focus rather than assuming completeness when truncated flags are set.
+- The envelope is capped: when `deliveriesCapped` is true there is more mail
+  than one envelope carries — ack what you handled and read again; the tail
+  stays unacked and follows. Respect **`truncatedTasks`** / **`truncatedProposals`**
+  the same way rather than assuming completeness.

package/skills/ziggs/references/reporting-convention.md

@@ -6,7 +6,7 @@
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).