@ziggs-ai/ziggs-mcp 0.38.2 → 0.39.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.39.0
+
+- Task result calls use the narrowed update-state contract and expose the canonical success confirmation. Cancellation remains on `ziggs_task_cancel`.
+
+- `ziggs_session_hold` works again: its own `executionContextId` is the execution it holds, not the selected execution, and keeps its required, described param.
+- `ziggs_context_snapshot` with only `agreementId` or `taskId` reads that scope and no longer builds an address from the id.
+
+- Expose conversation read/send and exact roomless inbox read plans carrying execution context.
+- Shorter `ziggs_conversation_read` and `ziggs_conversation_send` descriptions, so the directory door's tool list fits its budget again.
+
+## 0.38.3
+
+- A plan waiting on your acknowledgement shows under Waiting on you, with Review, in the inbox card and the session card. The same task is no longer also listed as your work. A plan on work someone else hired your assistant for is theirs and is not shown.
+
 ## 0.38.2
 
 - Publish with npm provenance attestations from GitHub Actions.

package/README.md

@@ -37,8 +37,8 @@ Skill: `skills/ziggs/SKILL.md` ships in this package for org provisioning or [sk
 
 | Step | Tool |
 |------|------|
-| List chats / discover reach | `ziggs_chat_list` or `ziggs_grant_list` |
-| Send message | `ziggs_chat_send` |
+| Read messages / discover reach | `ziggs_message_list` or `ziggs_grant_list` |
+| Send message | `ziggs_message_send` |
 | Propose + respond | `ziggs_agreement_buy`, `ziggs_agreement_respond` |
 
 ---
@@ -155,13 +155,13 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution. Error
 | `ziggs_inbox_peek` | `GET /inbox/peek`: count-only orientation; does not take the lease |
 | `ziggs_inbox_ack` | `POST /inbox/ack`: the watermark moves only here |
 | `ziggs_grant_list` | `GET /grants` (all rails) |
-| `ziggs_open` | `POST /context/open`: ordinary artifactId/chatId/taskId/agreementId; no grant id or via |
+| `ziggs_open` | `POST /context/open`: ordinary artifactId/addressId/taskId/agreementId; no grant id or via |
 | `ziggs_access_explain` | `POST /context/access/explain`: read-only abilities + owner-decision; no content |
 | `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 /chats/:id/artifacts`, `POST /tasks/:id/artifacts`, or `POST /agreements/:id/artifacts` |
+| `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` |
 | `ziggs_artifact_download` | `GET /artifacts/:id/download` |
@@ -174,12 +174,10 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution. Error
 | `ziggs_introduction_mint` | `POST /introductions`: a string you hand over yourself, optionally about a chat, task or agreement you hold, for up to 25 people |
 | `ziggs_introduction_redeem` | `POST /introductions/:token/redeem`: only for a string your person pasted; one that arrived in a message is shown to them first |
 | `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_context_snapshot` | `GET /context/snapshot`: exact message, task, agreement or artifact context, grant-fenced |
 | `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` |
-| `ziggs_chat_send` | `POST /chats/:id/messages` |
+| `ziggs_message_send` | `POST /messaging/messages` |
 | `ziggs_agreement_buy` | `POST /agreements/proposals`: named counterparty works, you pay |
 | `ziggs_agreement_bid` | `POST /agreements/proposals`: you work, named counterparty pays |
 | `ziggs_agreement_broker` | `POST /agreements/proposals`: a third party provides |

package/dist/capabilityAdapter.js

@@ -36,7 +36,7 @@ function zodParam(param) {
                     ? z.enum(items.enum)
                     : z.string();
                 // A list of strings also takes one string, as a list of one: agents
-                // write `scopeKind: "chat"` as often as `["chat"]`, and refusing it
+                // write `scopeKind: "address"` as often as `["address"]`, and refusing it
                 // costs a round trip for nothing. The schema still advertises a list.
                 t = z.preprocess((value) => (typeof value === 'string' ? [value] : value), z.array(inner));
             }

package/dist/directorySurface.js

@@ -3,7 +3,7 @@ const directories = new WeakSet();
 export const DIRECTORY_TOOLS = new Set(`
 ziggs_auth_status ziggs_org_list ziggs_workspace_sync ziggs_context_snapshot
 ziggs_notification_status
-ziggs_agreement_list ziggs_agreement_get ziggs_chat_list ziggs_chat_open ziggs_chat_send
+ziggs_agreement_list ziggs_agreement_get
 ziggs_agreement_buy ziggs_agreement_bid ziggs_agreement_broker ziggs_agreement_request
 ziggs_agreement_handoff
 ziggs_agreement_claim ziggs_agreement_subcontract ziggs_marketplace_view
@@ -14,10 +14,11 @@ ziggs_open ziggs_access_explain ziggs_context_read
 ziggs_artifact_record ziggs_artifact_list ziggs_artifact_find ziggs_artifact_share
 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 ziggs_message_answers ziggs_message_answer_cancel
 ziggs_task_create ziggs_task_set_result ziggs_task_replace_plan ziggs_task_update_steps
 ziggs_task_acknowledge_control ziggs_task_list ziggs_task_cancel ziggs_task_delegate ziggs_task_get
 ziggs_connection_list ziggs_agent_search ziggs_agent_get
-ziggs_context_delegate ziggs_access_request
+ziggs_message_send ziggs_context_delegate ziggs_access_request
 ziggs_link_propose ziggs_link_list ziggs_introduction_mint ziggs_introduction_redeem
 ziggs_introduction_list ziggs_introduction_revoke ziggs_context_revoke_grant ziggs_payment_balance
 `.trim().split(/\s+/));
@@ -33,8 +34,8 @@ 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_chat_open ziggs_chat_send ziggs_artifact_share ziggs_artifact_attach ziggs_artifact_contribute
-ziggs_context_delegate ziggs_access_request
+ziggs_task_delegate ziggs_artifact_share 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+/));
 export function installDirectorySurface(server) {

package/dist/inboxCard.d.ts

@@ -56,6 +56,7 @@ interface SessionPayload {
     }>;
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedPlanAcks?: number;
     agreementsListAppUrl?: string;
     sessionChatCard?: string;
     notice?: string;
@@ -83,5 +84,5 @@ export declare function registerInboxCardResource(server: McpServer): void;
  * then it draws whatever `ui/notifications/tool-result` carries, and its
  * buttons send `ui/open-link`.
  */
-export declare const INBOX_CARD_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Ziggs</title>\n<style>\n  :root { --fg:#1d1a20; --muted:#6b6470; --line:#e7e2ea; --bg:#ffffff; --brand:#7c3aed; --chip:#f4f1f6; }\n  @media (prefers-color-scheme: dark) { :root { --fg:#f2eef4; --muted:#a59cab; --line:#332d38; --bg:#1b171e; --brand:#a78bfa; --chip:#29232d; } }\n  * { box-sizing: border-box; }\n  body { margin:0; padding:14px 16px; font:14px/1.45 system-ui,-apple-system,\"Segoe UI\",sans-serif; color:var(--fg); background:var(--bg); }\n  h2 { margin:0 0 8px; font-size:12px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; color:var(--muted); }\n  section + section { margin-top:16px; }\n  ul { list-style:none; margin:0; padding:0; }\n  li { display:flex; align-items:center; gap:12px; padding:9px 0; border-top:1px solid var(--line); }\n  li:first-child { border-top:0; }\n  .text { flex:1; min-width:0; }\n  .title { font-weight:600; overflow-wrap:anywhere; }\n  .meta { color:var(--muted); font-size:12px; }\n  .chip { display:inline-block; padding:1px 7px; border-radius:999px; background:var(--chip); color:var(--muted); font-size:11px; margin-left:6px; font-weight:500; }\n  button { flex:none; min-height:32px; padding:0 12px; border-radius:8px; border:1px solid var(--line); background:transparent; color:var(--fg); font:inherit; font-size:13px; cursor:pointer; }\n  button.primary { background:var(--brand); border-color:var(--brand); color:#fff; }\n  .empty { color:var(--muted); }\n  .all { margin-top:12px; }\n</style>\n</head>\n<body>\n<main id=\"root\"><p class=\"empty\">Loading your Ziggs inbox\u2026</p></main>\n<script>\n(function () {\n  var nextId = 1, pending = {}, remeasure = null;\n  function send(method, params) {\n    var id = nextId++;\n    window.parent.postMessage({ jsonrpc: \"2.0\", id: id, method: method, params: params || {} }, \"*\");\n    return new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });\n  }\n  function notify(method, params) {\n    window.parent.postMessage({ jsonrpc: \"2.0\", method: method, params: params || {} }, \"*\");\n  }\n  function el(tag, cls, text) {\n    var node = document.createElement(tag);\n    if (cls) node.className = cls;\n    if (text != null) node.textContent = String(text);\n    return node;\n  }\n  function open(url) {\n    if (!url) return;\n    send(\"ui/open-link\", { url: url }).catch(function () {});\n  }\n  function row(title, chip, meta, label, url, primary) {\n    var li = el(\"li\"), text = el(\"div\", \"text\"), head = el(\"div\", \"title\", title);\n    if (chip) head.appendChild(el(\"span\", \"chip\", chip));\n    text.appendChild(head);\n    if (meta) text.appendChild(el(\"div\", \"meta\", meta));\n    li.appendChild(text);\n    if (url) {\n      var button = el(\"button\", primary ? \"primary\" : \"\", label);\n      button.type = \"button\";\n      button.addEventListener(\"click\", function () { open(url); });\n      li.appendChild(button);\n    }\n    return li;\n  }\n  function kindLabel(kind) {\n    return kind === \"link_request\" ? \"Link request\" : kind === \"proposal\" ? \"Proposal\" : \"\";\n  }\n  function render(data) {\n    var root = document.getElementById(\"root\");\n    root.textContent = \"\";\n    data = data || {};\n    var waiting = data.waitingOnYou || [], work = data.yourWork || [], more = data.moreWaiting || 0;\n    if (!waiting.length && !more && !work.length) {\n      root.appendChild(el(\"p\", \"empty\", \"Nothing is waiting on you in Ziggs.\"));\n    }\n    if (waiting.length || more) {\n      var s1 = el(\"section\"), l1 = el(\"ul\");\n      s1.appendChild(el(\"h2\", \"\", \"Waiting on you\"));\n      waiting.forEach(function (item) {\n        var meta = [item.who, item.when].filter(Boolean).join(\" \u00B7 \");\n        l1.appendChild(row(item.title, kindLabel(item.kind), meta, \"Review\", item.url, true));\n      });\n      s1.appendChild(l1);\n      if (more) s1.appendChild(el(\"p\", \"meta\", more + \" more on the website\"));\n      root.appendChild(s1);\n    }\n    if (work.length) {\n      var s2 = el(\"section\"), l2 = el(\"ul\");\n      s2.appendChild(el(\"h2\", \"\", \"Your work\"));\n      work.forEach(function (item) {\n        l2.appendChild(row(item.title, null, item.progress ? \"Plan \" + item.progress : \"In progress\", \"Open\", item.url, false));\n      });\n      s2.appendChild(l2);\n      root.appendChild(s2);\n    }\n    if (data.allUrl) {\n      var all = el(\"button\", \"all\", \"Open Ziggs\");\n      all.type = \"button\";\n      all.addEventListener(\"click\", function () { open(data.allUrl); });\n      root.appendChild(all);\n    }\n    if (remeasure) remeasure();\n  }\n  window.addEventListener(\"message\", function (event) {\n    if (event.source !== window.parent) return;\n    var msg = event.data;\n    if (!msg || msg.jsonrpc !== \"2.0\") return;\n    if (msg.id != null && pending[msg.id] && !msg.method) {\n      var waiter = pending[msg.id];\n      delete pending[msg.id];\n      if (msg.error) waiter.reject(msg.error); else waiter.resolve(msg.result);\n      return;\n    }\n    if (msg.method === \"ui/notifications/tool-result\") {\n      render((msg.params || {}).structuredContent);\n    }\n  });\n  // A host sizes the frame from what the view reports. Without a report the\n  // frame stays at zero height and the card is drawn but never seen.\n  function reportSize() {\n    var lastWidth = 0, lastHeight = 0, queued = false;\n    function measure() {\n      if (queued) return;\n      queued = true;\n      var next = typeof requestAnimationFrame === \"function\" ? requestAnimationFrame : function (fn) { setTimeout(fn, 16); };\n      next(function () {\n        queued = false;\n        var doc = document.documentElement, previous = doc.style.height;\n        doc.style.height = \"max-content\";\n        var height = Math.ceil(doc.getBoundingClientRect().height);\n        doc.style.height = previous;\n        var width = Math.ceil(window.innerWidth);\n        if (width === lastWidth && height === lastHeight) return;\n        lastWidth = width; lastHeight = height;\n        notify(\"ui/notifications/size-changed\", { width: width, height: height });\n      });\n    }\n    remeasure = measure;\n    measure();\n    if (typeof ResizeObserver === \"function\") {\n      var observer = new ResizeObserver(measure);\n      observer.observe(document.documentElement);\n      observer.observe(document.body);\n    }\n  }\n  send(\"ui/initialize\", {\n    protocolVersion: \"2026-01-26\",\n    appInfo: { name: \"Ziggs inbox card\", version: \"1\" },\n    appCapabilities: {}\n  }).then(function () {\n    notify(\"ui/notifications/initialized\", {});\n    reportSize();\n  }, function () {});\n})();\n</script>\n</body>\n</html>\n";
+export declare const INBOX_CARD_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Ziggs</title>\n<style>\n  :root { --fg:#1d1a20; --muted:#6b6470; --line:#e7e2ea; --bg:#ffffff; --brand:#7c3aed; --chip:#f4f1f6; }\n  @media (prefers-color-scheme: dark) { :root { --fg:#f2eef4; --muted:#a59cab; --line:#332d38; --bg:#1b171e; --brand:#a78bfa; --chip:#29232d; } }\n  * { box-sizing: border-box; }\n  body { margin:0; padding:14px 16px; font:14px/1.45 system-ui,-apple-system,\"Segoe UI\",sans-serif; color:var(--fg); background:var(--bg); }\n  h2 { margin:0 0 8px; font-size:12px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; color:var(--muted); }\n  section + section { margin-top:16px; }\n  ul { list-style:none; margin:0; padding:0; }\n  li { display:flex; align-items:center; gap:12px; padding:9px 0; border-top:1px solid var(--line); }\n  li:first-child { border-top:0; }\n  .text { flex:1; min-width:0; }\n  .title { font-weight:600; overflow-wrap:anywhere; }\n  .meta { color:var(--muted); font-size:12px; }\n  .chip { display:inline-block; padding:1px 7px; border-radius:999px; background:var(--chip); color:var(--muted); font-size:11px; margin-left:6px; font-weight:500; }\n  button { flex:none; min-height:32px; padding:0 12px; border-radius:8px; border:1px solid var(--line); background:transparent; color:var(--fg); font:inherit; font-size:13px; cursor:pointer; }\n  button.primary { background:var(--brand); border-color:var(--brand); color:#fff; }\n  .empty { color:var(--muted); }\n  .all { margin-top:12px; }\n</style>\n</head>\n<body>\n<main id=\"root\"><p class=\"empty\">Loading your Ziggs inbox\u2026</p></main>\n<script>\n(function () {\n  var nextId = 1, pending = {}, remeasure = null;\n  function send(method, params) {\n    var id = nextId++;\n    window.parent.postMessage({ jsonrpc: \"2.0\", id: id, method: method, params: params || {} }, \"*\");\n    return new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });\n  }\n  function notify(method, params) {\n    window.parent.postMessage({ jsonrpc: \"2.0\", method: method, params: params || {} }, \"*\");\n  }\n  function el(tag, cls, text) {\n    var node = document.createElement(tag);\n    if (cls) node.className = cls;\n    if (text != null) node.textContent = String(text);\n    return node;\n  }\n  function open(url) {\n    if (!url) return;\n    send(\"ui/open-link\", { url: url }).catch(function () {});\n  }\n  function row(title, chip, meta, label, url, primary) {\n    var li = el(\"li\"), text = el(\"div\", \"text\"), head = el(\"div\", \"title\", title);\n    if (chip) head.appendChild(el(\"span\", \"chip\", chip));\n    text.appendChild(head);\n    if (meta) text.appendChild(el(\"div\", \"meta\", meta));\n    li.appendChild(text);\n    if (url) {\n      var button = el(\"button\", primary ? \"primary\" : \"\", label);\n      button.type = \"button\";\n      button.addEventListener(\"click\", function () { open(url); });\n      li.appendChild(button);\n    }\n    return li;\n  }\n  function kindLabel(kind) {\n    return kind === \"link_request\" ? \"Link request\" : kind === \"proposal\" ? \"Proposal\" : kind === \"plan_ack\" ? \"Plan\" : \"\";\n  }\n  function render(data) {\n    var root = document.getElementById(\"root\");\n    root.textContent = \"\";\n    data = data || {};\n    var waiting = data.waitingOnYou || [], work = data.yourWork || [], more = data.moreWaiting || 0;\n    if (!waiting.length && !more && !work.length) {\n      root.appendChild(el(\"p\", \"empty\", \"Nothing is waiting on you in Ziggs.\"));\n    }\n    if (waiting.length || more) {\n      var s1 = el(\"section\"), l1 = el(\"ul\");\n      s1.appendChild(el(\"h2\", \"\", \"Waiting on you\"));\n      waiting.forEach(function (item) {\n        var meta = [item.who, item.when].filter(Boolean).join(\" \u00B7 \");\n        l1.appendChild(row(item.title, kindLabel(item.kind), meta, \"Review\", item.url, true));\n      });\n      s1.appendChild(l1);\n      if (more) s1.appendChild(el(\"p\", \"meta\", more + \" more on the website\"));\n      root.appendChild(s1);\n    }\n    if (work.length) {\n      var s2 = el(\"section\"), l2 = el(\"ul\");\n      s2.appendChild(el(\"h2\", \"\", \"Your work\"));\n      work.forEach(function (item) {\n        l2.appendChild(row(item.title, null, item.progress ? \"Plan \" + item.progress : \"In progress\", \"Open\", item.url, false));\n      });\n      s2.appendChild(l2);\n      root.appendChild(s2);\n    }\n    if (data.allUrl) {\n      var all = el(\"button\", \"all\", \"Open Ziggs\");\n      all.type = \"button\";\n      all.addEventListener(\"click\", function () { open(data.allUrl); });\n      root.appendChild(all);\n    }\n    if (remeasure) remeasure();\n  }\n  window.addEventListener(\"message\", function (event) {\n    if (event.source !== window.parent) return;\n    var msg = event.data;\n    if (!msg || msg.jsonrpc !== \"2.0\") return;\n    if (msg.id != null && pending[msg.id] && !msg.method) {\n      var waiter = pending[msg.id];\n      delete pending[msg.id];\n      if (msg.error) waiter.reject(msg.error); else waiter.resolve(msg.result);\n      return;\n    }\n    if (msg.method === \"ui/notifications/tool-result\") {\n      render((msg.params || {}).structuredContent);\n    }\n  });\n  // A host sizes the frame from what the view reports. Without a report the\n  // frame stays at zero height and the card is drawn but never seen.\n  function reportSize() {\n    var lastWidth = 0, lastHeight = 0, queued = false;\n    function measure() {\n      if (queued) return;\n      queued = true;\n      var next = typeof requestAnimationFrame === \"function\" ? requestAnimationFrame : function (fn) { setTimeout(fn, 16); };\n      next(function () {\n        queued = false;\n        var doc = document.documentElement, previous = doc.style.height;\n        doc.style.height = \"max-content\";\n        var height = Math.ceil(doc.getBoundingClientRect().height);\n        doc.style.height = previous;\n        var width = Math.ceil(window.innerWidth);\n        if (width === lastWidth && height === lastHeight) return;\n        lastWidth = width; lastHeight = height;\n        notify(\"ui/notifications/size-changed\", { width: width, height: height });\n      });\n    }\n    remeasure = measure;\n    measure();\n    if (typeof ResizeObserver === \"function\") {\n      var observer = new ResizeObserver(measure);\n      observer.observe(document.documentElement);\n      observer.observe(document.body);\n    }\n  }\n  send(\"ui/initialize\", {\n    protocolVersion: \"2026-01-26\",\n    appInfo: { name: \"Ziggs inbox card\", version: \"1\" },\n    appCapabilities: {}\n  }).then(function () {\n    notify(\"ui/notifications/initialized\", {});\n    reportSize();\n  }, function () {});\n})();\n</script>\n</body>\n</html>\n";
 export {};

package/dist/inboxCard.js

@@ -22,7 +22,9 @@ export function inboxCardData(payload) {
             when: item.proposedAtLabel,
             url: item.appUrl,
         })),
-        moreWaiting: (payload.truncatedProposals ?? 0) + (payload.truncatedConnectionRequests ?? 0),
+        moreWaiting: (payload.truncatedProposals ?? 0) +
+            (payload.truncatedConnectionRequests ?? 0) +
+            (payload.truncatedPlanAcks ?? 0),
         yourWork: (payload.activeWork ?? []).map((item) => ({
             title: item.title,
             progress: item.planTotal > 0 ? `${item.planDone}/${item.planTotal}` : null,
@@ -132,7 +134,7 @@ export const INBOX_CARD_HTML = `<!doctype html>
     return li;
   }
   function kindLabel(kind) {
-    return kind === "link_request" ? "Link request" : kind === "proposal" ? "Proposal" : "";
+    return kind === "link_request" ? "Link request" : kind === "proposal" ? "Proposal" : kind === "plan_ack" ? "Plan" : "";
   }
   function render(data) {
     var root = document.getElementById("root");

package/dist/inboxChannel.js

@@ -42,8 +42,8 @@ export function observeFor(creds) {
 export function channelEvent(delivery, agentId) {
     const forYou = !!agentId && delivery.assigneeId === agentId;
     const meta = { kind: delivery.kind, resource_id: delivery.resourceId };
-    if (delivery.chatId)
-        meta.chat_id = delivery.chatId;
+    if (delivery.addressId)
+        meta.chat_id = delivery.addressId;
     if (delivery.taskId)
         meta.task_id = delivery.taskId;
     if (delivery.agreementId)

package/dist/inboxCompact.js

@@ -117,8 +117,8 @@ export function sectionOf(row, agentIds) {
 }
 /** What a row is about: its chat, else its task, else its agreement, else itself. */
 function anchorOf(row) {
-    if (row.chatId)
-        return ['chatId', String(row.chatId)];
+    if (row.addressId)
+        return ['addressId', String(row.addressId)];
     if (row.taskId)
         return ['taskId', String(row.taskId)];
     if (row.agreementId)

package/dist/inboxToolResult.d.ts

@@ -53,7 +53,7 @@ interface OutOfReachNote {
     requestReplyAccess?: AccessRequestCall<'reply'>;
 }
 /** What to do with rows marked `outOfReach`, said once per inbox read. */
-export declare const OUT_OF_REACH_NOTE = "Rows with outOfReach: true are in rooms or resources you cannot read. ziggs_chat_list with readable: false shows each room you may list and the read request to file; for anything else, ziggs_open on it returns the request to make.";
+export declare const OUT_OF_REACH_NOTE = "Rows with outOfReach: true name resources you cannot read. Use ziggs_open on the exact returned resource to inspect its available access request. A receipt grants no access.";
 /**
  * replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop

package/dist/inboxToolResult.js

@@ -3,7 +3,7 @@ import { buildDecidedForMeItems, formatPendingDecisionsPayload, humanAttentionFo
 /** Keep the plan bounded; the full deliveries array still carries everything. */
 const MAX_READ_PLAN = 12;
 /** What to do with rows marked `outOfReach`, said once per inbox read. */
-export const OUT_OF_REACH_NOTE = 'Rows with outOfReach: true are in rooms or resources you cannot read. ziggs_chat_list with readable: false shows each room you may list and the read request to file; for anything else, ziggs_open on it returns the request to make.';
+export const OUT_OF_REACH_NOTE = 'Rows with outOfReach: true name resources you cannot read. Use ziggs_open on the exact returned resource to inspect its available access request. A receipt grants no access.';
 function outOfReachOf(d) {
     const note = d.outOfReach;
     if (!note || typeof note !== 'object')
@@ -48,8 +48,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
     const deliveries = inbox.deliveries ?? [];
-    // dedup by call signature so the same (type, via) can't appear
-    // twice when several deliveries land in one chat. Collect candidates
+    // Deduplicate repeated receipts or resource calls. Collect candidates
     // uncapped; the cap is applied once, after the ack is reserved, so the ack
     // step always survives.
     //
@@ -65,12 +64,11 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const seen = new Set();
     // Which assigned rows each candidate step settles, so a checkpoint ack can
     // name what is finished once that step is done. Keyed by the step's own
-    // dedup key, because one read covers every row that landed in its chat.
+    // dedup key. Message responsibilities each keep their own execution.
     const settledBy = new Map();
     const candidateKeys = [];
     const add = (key, call, mine = true, settles) => {
-        // Recorded before the dedup return: the second row landing in a chat adds
-        // no step, but the one step there already covers it.
+        // Record every receipt covered by an identical resource call before deduplication.
         if (settles) {
             const rows = settledBy.get(key);
             if (rows)
@@ -107,8 +105,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
      * the ack rides on all of it fitting, exactly as before.
      */
     const isMine = (d) => self.agentIds?.includes(d.assigneeId ?? '') || (!self.agentIds && self.agentId === '') || d.assigneeId === self.agentId;
-    // Reads — one call per place mail actually landed. The delivery names the
-    // chat, agreement or task directly, so nothing has to be inferred from a scope.
+    // Read the exact delivered resource. History and navigation are optional.
     //
     // Total over BOTH axes, and that is the whole point of this shape:
     //
@@ -117,7 +114,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     //   - over the anchor, so is an artifact carrying none of chat/agreement/task
     // — it is read as `artifact:<id>`, the entry added for that case.
     //
-    // The first is history: while this looked at chatId/agreementId only, a
+    // The first is history: while this looked at addressId/agreementId only, a
     // task-bound deliverable produced an envelope whose plan was the ack and
     // nothing else, and an agent following the plan acked work it never read. The
     // second is that hole closed ahead of an emitter — nothing writes an
@@ -140,13 +137,13 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
         const note = outOfReachOf(d);
         if (note) {
             unreadable.push({ resourceId: d.resourceId, ...note,
-                ...(['chat', 'agreement', 'task', 'artifact'].includes(note.scopeKind) ? {
-                    requestAccess: { tool: 'ziggs_access_request', args: { scopeKind: note.scopeKind, scopeId: note.scopeId, permission: 'read', temporal: 'from-start' }, requiredInput: note.scopeKind === 'artifact' ? ['reason', 'recipientId', 'chatId'] : ['reason', 'recipientId'], effect: 'request_only' },
+                ...(['address', 'agreement', 'task', 'artifact'].includes(note.scopeKind) ? {
+                    requestAccess: { tool: 'ziggs_access_request', args: { scopeKind: note.scopeKind, scopeId: note.scopeId, permission: 'read', temporal: 'from-start' }, requiredInput: ['reason', 'recipientId'], effect: 'request_only' },
                 } : {}),
-                ...(note.scopeKind === 'chat' ? {
+                ...(note.scopeKind === 'address' ? {
                     requestReplyAccess: {
                         tool: 'ziggs_access_request',
-                        args: { scopeKind: 'chat', scopeId: note.scopeId, permission: 'reply', temporal: 'from-start' },
+                        args: { scopeKind: 'address', scopeId: note.scopeId, permission: 'reply', temporal: 'from-start' },
                         requiredInput: ['reason', 'recipientId'],
                         effect: 'request_only',
                     },
@@ -155,24 +152,27 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
             continue;
         }
         const mine = isMine(d);
-        if (mine && d.executionContext && d.responsibilityId) {
-            const ref = d.kind === 'message' ? d.chatId : d.resourceId;
+        if (d.kind === 'message') {
+            add(`message:${d.receiptId ?? d.resourceId}`, {
+                tool: 'ziggs_message_read',
+                args: { messageId: d.resourceId, ...(d.executionContext ? { executionContextId: d.executionContext.contextId } : {}) },
+                why: 'Read the exact message. Keep executions separate; reading does not handle the receipt.',
+            }, mine, mine ? d.receiptId : undefined);
+            continue;
+        }
+        if (mine && d.executionContext && d.receiptId) {
+            const ref = d.resourceId;
             if (ref)
-                add(`execution:${d.responsibilityId}`, {
+                add(`execution:${d.receiptId}`, {
                     tool: 'ziggs_open', args: { ref, executionContextId: d.executionContext.contextId },
                     why: `Handle this responsibility as ${d.executionContext.position}. Carry executionContextId on subsequent calls. Use separate model context for different execution contexts.`,
-                }, true, d.responsibilityId);
+                }, true, d.receiptId);
             continue;
         }
         switch (d.kind) {
-            case 'message':
-                // A message always lands in a chat; open the ordinary chat id.
-                if (d.chatId)
-                    open('chat', d.chatId, mine, mine ? d.responsibilityId : undefined);
-                break;
             case 'artifact':
                 // The delivery's resourceId is the artifact. Do not reconstruct via.
-                open('artifact', d.resourceId, mine, mine ? d.responsibilityId : undefined);
+                open('artifact', d.resourceId, mine, mine ? d.receiptId : undefined);
                 break;
             case 'agreement': {
                 // An agreement row whose reason names a decision on a request this
@@ -192,7 +192,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                     surface: 'mcp',
                 });
                 if (words) {
-                    add(`open:agreement:${agreementId}`, { tool: 'ziggs_open', args: { ref: agreementId }, why: words.sentence }, mine, mine ? d.responsibilityId : undefined);
+                    add(`open:agreement:${agreementId}`, { tool: 'ziggs_open', args: { ref: agreementId }, why: words.sentence }, mine, mine ? d.receiptId : undefined);
                 }
                 break;
             }
@@ -294,7 +294,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                     'Reads of rows assigned to others never count; skip them freely. '
                 : 'no row in this window is assigned to you; acking only moves your mark past context that other windows handle. ') +
                 'Pass ackTo back VERBATIM (it is opaque). ' +
-                'Handled only some? Pass the same ackTo with only their responsibilityIds in handledDeliveryIds; the rest stays pending',
+                'Handled only some? Pass the same ackTo with only their receiptIds in handledDeliveryIds; the rest stays pending',
         });
     }
     return { plan, truncated, unreadable };
@@ -413,7 +413,7 @@ self = { agentId: '' }) {
         }
         : {};
     const blockedAssignments = [
-        ...(inbox.deliveries ?? []).filter(d => d.executionBlocked).map(d => ({ resourceId: d.resourceId, responsibilityId: d.responsibilityId, ...d.executionBlocked })),
+        ...(inbox.deliveries ?? []).filter(d => d.executionBlocked).map(d => ({ resourceId: d.resourceId, receiptId: d.receiptId, ...d.executionBlocked })),
         ...(inbox.tasksAwaitingMe ?? []).filter(t => t.executionBlocked).map(t => ({ resourceId: t.taskId, ...t.executionBlocked })),
         ...(inbox.proposalsAwaitingMe ?? []).filter(p => p.executionBlocked).map(p => ({ resourceId: p.agreementId, ...p.executionBlocked })),
     ];

package/dist/pendingDecisions.d.ts

@@ -1,7 +1,7 @@
 export { resolveWebAppOrigin, agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
 import { type DecisionOutcome, type InboxEnvelope, type InboxHumanAttention, type InboxTaskRef, type Task } from '@ziggs-ai/api-client';
 import type { ReadPlanCall } from './inboxToolResult.js';
-export type PendingDecisionKind = 'proposal' | 'link_request';
+export type PendingDecisionKind = 'proposal' | 'link_request' | 'plan_ack';
 /**
  * A reference to a decision somebody is waiting on. Who may answer it is not
  * known here: the inbox lists slots, and a slot is not authority. The
@@ -9,8 +9,12 @@ export type PendingDecisionKind = 'proposal' | 'link_request';
  */
 export interface PendingDecisionItem {
     kind: PendingDecisionKind;
-    /** Agreement id for proposals; requestId for link requests. */
+    /**
+     * Agreement id for proposals and plans; requestId for link requests.
+     */
     agreementId: string;
+    /** The task whose plan waits, on a `plan_ack`. */
+    taskId?: string;
     title: string;
     subtitle: string | null;
     proposedAt: string | null;
@@ -107,6 +111,7 @@ export declare function buildActiveWorkItemsFromInbox(refs: InboxTaskRef[], webO
 export declare function buildSessionChatCard(decisions: PendingDecisionItem[], work: ActiveWorkItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedPlanAcks?: number;
     agreementsListAppUrl?: string;
 }): string;
 /** Structured session payload for MCP tools ( + active work). */

package/dist/pendingDecisions.js

@@ -181,8 +181,27 @@ function linkToItem(c, origin) {
         proposedAt: c.requestedAt,
     }, origin);
 }
+/**
+ * A plan waiting on the person. The plan is acknowledged signed in on the
+ * agreement page, where the task and its plan are shown, so Review goes there.
+ */
+function planAckToItem(a, origin) {
+    return {
+        ...decisionToItem('plan_ack', a.agreementId, {
+            title: displayTitle(a.title?.trim() || '(untitled task)'),
+            subtitle: a.scope === 'mid_work'
+                ? 'The plan changed during the work.'
+                : 'Work starts once you acknowledge the plan.',
+            proposedAt: a.updatedAt,
+        }, origin),
+        taskId: a.taskId,
+    };
+}
 export function buildPendingDecisionItems(inbox, webOrigin) {
     const items = [];
+    for (const a of inbox.planAcksAwaitingMe ?? []) {
+        items.push(planAckToItem(a, webOrigin));
+    }
     for (const p of inbox.proposalsAwaitingMe ?? []) {
         items.push(proposalToItem(p, webOrigin));
     }
@@ -263,18 +282,24 @@ export function buildActiveWorkItemsFromInbox(refs, webOrigin) {
 function kindLabel(kind) {
     if (kind === 'proposal')
         return 'Agreement proposal';
+    if (kind === 'plan_ack')
+        return 'Plan to acknowledge';
     return 'Agent link request';
 }
 function kindHint(kind) {
     if (kind === 'proposal') {
         return 'Someone proposed work or terms — your approval opens or rejects it.';
     }
+    if (kind === 'plan_ack') {
+        return 'Work you are paying for has a plan waiting on you.';
+    }
     return 'Another agent wants to link — your approval enables cross-org reach.';
 }
 function buildDecisionSection(items, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedPlanAcks = opts.truncatedPlanAcks ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedPlanAcks;
     if (!items.length && truncated === 0)
         return [];
     const lines = [];
@@ -287,7 +312,7 @@ function buildDecisionSection(items, opts) {
         lines.push('');
         lines.push(`**${item.title}**`);
         lines.push('');
-        lines.push(`\`${item.agreementId}\`${item.proposedAtLabel ? ` · ${item.proposedAtLabel}` : ''}`);
+        lines.push(`\`${item.taskId ?? item.agreementId}\`${item.proposedAtLabel ? ` · ${item.proposedAtLabel}` : ''}`);
         lines.push('');
         lines.push(`_${kindHint(item.kind)}_`);
         if (item.subtitle) {
@@ -297,15 +322,20 @@ function buildDecisionSection(items, opts) {
         lines.push('');
         lines.push(`[Review in Ziggs →](${item.appUrl})`);
         lines.push('');
-        // No pre-filled respond call: a slot is not authority, and a call that
-        // 403s every time is worse than a line that says where the answer is.
-        lines.push('Review the terms here. The agent reads approvalAction on the agreement to check whether an existing grant lets it decide; otherwise the accountable party decides in Ziggs.');
+        if (item.kind === 'plan_ack') {
+            lines.push('The person acknowledges the plan in Ziggs, signed in as themselves.');
+        }
+        else {
+            // No pre-filled respond call: a slot is not authority, and a call that
+            // 403s every time is worse than a line that says where the answer is.
+            lines.push('Review the terms here. The agent reads approvalAction on the agreement to check whether an existing grant lets it decide; otherwise the accountable party decides in Ziggs.');
+        }
         lines.push('');
     }
     if (truncated > 0) {
         lines.push('---');
         lines.push('');
-        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s)) — not listed here._`);
+        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s)${truncatedPlanAcks ? `, ${truncatedPlanAcks} plan(s)` : ''}) — not listed here._`);
         lines.push('');
     }
     return lines;
@@ -352,7 +382,9 @@ function buildWorkSection(work, startIndex = 1) {
 export function buildSessionChatCard(decisions, work, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedPlanAcks = opts.truncatedPlanAcks ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedPlanAcks;
+    const planAckCount = decisions.filter((d) => d.kind === 'plan_ack').length;
     const decisionListed = decisions.length + truncated;
     const workCount = work.length;
     const total = decisionListed + workCount;
@@ -365,9 +397,14 @@ export function buildSessionChatCard(decisions, work, opts) {
         '|:--|--:|',
         ...(decisionListed > 0
             ? [
-                `| Approve / reject | **${decisionListed}** |`,
+                `| ${planAckCount + truncatedPlanAcks > 0 ? 'Approve / reject / acknowledge' : 'Approve / reject'} | **${decisionListed}** |`,
                 `| — proposals | ${decisions.filter((d) => d.kind === 'proposal').length}${truncatedProposals ? ` (+${truncatedProposals} hidden)` : ''} |`,
                 `| — link requests | ${decisions.filter((d) => d.kind === 'link_request').length}${truncatedConnectionRequests ? ` (+${truncatedConnectionRequests} hidden)` : ''} |`,
+                ...(planAckCount + truncatedPlanAcks > 0
+                    ? [
+                        `| — plans to acknowledge | ${planAckCount}${truncatedPlanAcks ? ` (+${truncatedPlanAcks} hidden)` : ''} |`,
+                    ]
+                    : []),
             ]
             : []),
         ...(workCount > 0 ? [`| Active tasks (your work) | **${workCount}** |`] : []),
@@ -393,18 +430,26 @@ export function buildSessionChatCard(decisions, work, opts) {
 export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const withSessionCard = opts?.withSessionCard !== false;
     const decisions = buildPendingDecisionItems(inbox, webOrigin);
-    const activeWork = opts?.activeTasks !== undefined
+    // A task whose plan waits on the person is theirs to acknowledge before it
+    // is anyone's work, so it is listed once, as the decision.
+    const waitingPlans = new Set((inbox.planAcksAwaitingMe ?? []).map((a) => a.taskId));
+    const activeWork = (opts?.activeTasks !== undefined
         ? buildActiveWorkItems(opts.activeTasks, webOrigin)
-        : buildActiveWorkItemsFromInbox(inbox.tasksAwaitingMe ?? [], webOrigin);
+        : buildActiveWorkItemsFromInbox(inbox.tasksAwaitingMe ?? [], webOrigin)).filter((w) => !waitingPlans.has(w.taskId));
     const truncatedProposals = inbox.truncatedProposals ?? 0;
     const truncatedConnectionRequests = inbox.truncatedConnectionRequests ?? 0;
-    const pendingCount = decisions.length + truncatedProposals + truncatedConnectionRequests;
+    const truncatedPlanAcks = inbox.truncatedPlanAcks ?? 0;
+    const pendingCount = decisions.length +
+        truncatedProposals +
+        truncatedConnectionRequests +
+        truncatedPlanAcks;
     const activeWorkCount = activeWork.length;
     const actionCount = pendingCount + activeWorkCount;
     const listUrl = agreementsListAppUrl(webOrigin);
     const cardOpts = {
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedPlanAcks,
         agreementsListAppUrl: listUrl,
     };
     // Only the session-start read ships it. The long-poll shape passes
@@ -415,6 +460,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         : null;
     const proposalCount = decisions.filter((d) => d.kind === 'proposal').length;
     const linkCount = decisions.filter((d) => d.kind === 'link_request').length;
+    const planAckCount = decisions.filter((d) => d.kind === 'plan_ack').length;
     // Decisions somebody made on requests this side made. Counted here and named
     // in the line the model reads; the entries themselves ride the news half of
     // the inbox result (`decidedForMe`), which the cold read already carries.
@@ -444,7 +490,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
             : 'No pending decisions or active tasks.');
     }
     else {
-        parts.push(`${count(pendingCount, 'pending decision', 'pending decisions')} (${count(proposalCount + truncatedProposals, 'proposal', 'proposals')}, ${count(linkCount + truncatedConnectionRequests, 'link request', 'link requests')}) and ${count(activeWorkCount, 'active task', 'active tasks')}.`);
+        parts.push(`${count(pendingCount, 'pending decision', 'pending decisions')} (${count(proposalCount + truncatedProposals, 'proposal', 'proposals')}, ${count(linkCount + truncatedConnectionRequests, 'link request', 'link requests')}${planAckCount + truncatedPlanAcks > 0 ? `, ${count(planAckCount + truncatedPlanAcks, 'plan to acknowledge', 'plans to acknowledge')}` : ''}) and ${count(activeWorkCount, 'active task', 'active tasks')}.`);
     }
     if (decidedNote)
         parts.push(decidedNote);
@@ -464,9 +510,10 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         summary: {
             proposals: proposalCount + truncatedProposals,
             linkRequests: linkCount + truncatedConnectionRequests,
+            planAcks: planAckCount + truncatedPlanAcks,
             activeTasks: activeWorkCount,
             listed: decisions.length,
-            truncated: truncatedProposals + truncatedConnectionRequests,
+            truncated: truncatedProposals + truncatedConnectionRequests + truncatedPlanAcks,
             decidedForMe: decidedForMe.filter((i) => i.outcome !== 'held').length,
             refusals: decidedForMe.filter((i) => i.outcome === 'rejected').length,
         },
@@ -474,6 +521,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         activeWork,
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedPlanAcks,
         agreementsListAppUrl: listUrl,
         connectionsSettingsAppUrl: connectionsSettingsAppUrl(webOrigin),
         // one card per session start. The owner (withSessionCard) embeds

package/dist/protocol/connectText.js

@@ -25,7 +25,7 @@ const INBOX = {
 };
 const WAIT = 'If finishing the request needs a reply or decision, keep checking ziggs_inbox with waitSeconds: 55; handle arrivals and continue. After ten minutes, report what is missing. Promise later updates only with a configured host wake or schedule.';
 const ACCESS = 'Missing access: use ziggs_access_request for that resource. Choose requestAccess for reading or requestReplyAccess/the reply recovery for answering; reply includes read. A request grants nothing until approved.';
-const REPLY = 'Reply in the original chatId using its reply action. Sending only to a person may select a different pair room; missing access does not move the conversation.';
+const REPLY = 'Reply in the original addressId using its reply action. Sending only to a person may select a different pair room; missing access does not move the conversation.';
 const GROUNDING = 'Ground summaries in source records: keep each date tied to its named milestone, and distinguish inquiries, approvals and completed actions. Verify before claiming completion.';
 const RULES = [
     WAIT,
@@ -34,7 +34,7 @@ const RULES = [
     ACCESS,
     REPLY,
     GROUNDING,
-    'A send refused with WORK_SELECTION_REQUIRED lists choices: set conversationAgreementId to one of them; never guess.',
+    'A send refused with WORK_SELECTION_REQUIRED lists choices: set workAgreementId to one of them; never guess.',
     'Agreement and task writes can reserve or settle points. After an uncertain write, read the record, then retry with the same idempotencyKey.',
 ];
 /**