@ziggs-ai/ziggs-mcp 0.37.19 → 0.37.21

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.37.21
+
+- The inbox card reports its size to the host. Without it a host left the frame at zero height, so the card was drawn but never seen.
+- A key-based (operator key) connection now lists every tool by name, like the OAuth connection, instead of the everyday set behind a catalog. `ziggs_tools`, `ziggs_tool_read` and `ziggs_tool_write` stay listed and work as before, so a client that mounts only an allow-list still reaches the rest.
+
+## 0.37.20
+
+- Set `ZIGGS_MCP_CHANNEL=1` to make the local server a Claude Code channel: an open Claude Code session hears new mail within seconds. Mail already waiting becomes one event, and each new delivery one more. Events carry ids only, never what the mail says; read it with `ziggs_inbox`. Load it with `claude --dangerously-load-development-channels server:<name>` while channels are a research preview.
+- `tools/list` no longer carries the `$schema` line in every input schema.
+- Shorter parameter text on the agreement verbs, `ziggs_task_create` and `ziggs_artifact_record`. Every rule stays.
+
 ## 0.37.19
 
 - New read-only `ziggs_inbox_show`: what is waiting on the person and their work in hand, as an MCP Apps card in hosts that draw one (Claude, ChatGPT, Cursor) and as the usual text everywhere else. The card's buttons only open the Ziggs website; it changes nothing itself. The view is served at `ui://ziggs/inbox-card`.

package/dist/config.d.ts

@@ -49,6 +49,12 @@ declare const envSchema: z.ZodObject<{
      * cut cold-start deferred-loading (#7). Unset = all tools register.
      */
     ZIGGS_MCP_CORE_ONLY: z.ZodOptional<z.ZodString>;
+    /**
+     * Set to 1/true/yes to ring an open Claude Code session when new mail
+     * arrives (a Claude Code channel). Claude Code must also load this server
+     * as a channel; see `inboxChannel.ts`.
+     */
+    ZIGGS_MCP_CHANNEL: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     ZIGGS_OPERATOR_KEY: string;
     ZIGGS_API_URL?: string | undefined;
@@ -63,6 +69,7 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_SESSION_NAME?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
+    ZIGGS_MCP_CHANNEL?: string | undefined;
 }, {
     ZIGGS_OPERATOR_KEY: string;
     ZIGGS_API_URL?: string | undefined;
@@ -77,6 +84,7 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_SESSION_NAME?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
+    ZIGGS_MCP_CHANNEL?: string | undefined;
 }>;
 type EnvConfig = z.infer<typeof envSchema>;
 export interface ZiggsMcpConfig extends EnvConfig {
@@ -114,6 +122,11 @@ export interface ZiggsMcpConfig extends EnvConfig {
      * connect text, inside that text's budget.
      */
     eventsEnabled?: boolean;
+    /**
+     * Local only: declare the Claude Code channel and ring the session for new
+     * mail. Adds one line to the compact door's connect text.
+     */
+    channel?: boolean;
 }
 /** Load delegate credentials from the environment. */
 export declare function loadConfig(): ZiggsMcpConfig;

package/dist/config.js

@@ -51,6 +51,12 @@ const envSchema = z.object({
      * cut cold-start deferred-loading (#7). Unset = all tools register.
      */
     ZIGGS_MCP_CORE_ONLY: z.string().optional(),
+    /**
+     * Set to 1/true/yes to ring an open Claude Code session when new mail
+     * arrives (a Claude Code channel). Claude Code must also load this server
+     * as a channel; see `inboxChannel.ts`.
+     */
+    ZIGGS_MCP_CHANNEL: z.string().optional(),
 });
 /** Parse a truthy env flag (1/true/yes) — shared by ZIGGS_MCP_DEBUG and ZIGGS_MCP_CORE_ONLY. */
 function parseBoolFlag(raw) {
@@ -75,6 +81,7 @@ export function loadConfig() {
         ZIGGS_SESSION_NAME: process.env.ZIGGS_SESSION_NAME,
         ZIGGS_MCP_DEBUG: process.env.ZIGGS_MCP_DEBUG,
         ZIGGS_MCP_CORE_ONLY: process.env.ZIGGS_MCP_CORE_ONLY,
+        ZIGGS_MCP_CHANNEL: process.env.ZIGGS_MCP_CHANNEL,
     };
     const parsed = envSchema.safeParse(raw);
     if (!parsed.success) {
@@ -108,6 +115,7 @@ export function loadConfig() {
         resolvedAgentId,
         debugTools: parseBoolFlag(parsed.data.ZIGGS_MCP_DEBUG),
         coreOnly: parseBoolFlag(parsed.data.ZIGGS_MCP_CORE_ONLY),
+        channel: parseBoolFlag(parsed.data.ZIGGS_MCP_CHANNEL),
         directConnection: !isDirectoryBoarded(decodeOperatorKeyClaims(parsed.data.ZIGGS_OPERATOR_KEY)),
     };
 }

package/dist/inboxCard.d.ts

@@ -83,5 +83,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 = {};\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  }\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  send(\"ui/initialize\", {\n    protocolVersion: \"2026-01-26\",\n    appInfo: { name: \"Ziggs inbox card\", version: \"1\" },\n    appCapabilities: {}\n  }).then(function () { notify(\"ui/notifications/initialized\", {}); }, 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\" : \"\";\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

@@ -98,7 +98,7 @@ export const INBOX_CARD_HTML = `<!doctype html>
 <main id="root"><p class="empty">Loading your Ziggs inbox…</p></main>
 <script>
 (function () {
-  var nextId = 1, pending = {};
+  var nextId = 1, pending = {}, remeasure = null;
   function send(method, params) {
     var id = nextId++;
     window.parent.postMessage({ jsonrpc: "2.0", id: id, method: method, params: params || {} }, "*");
@@ -168,6 +168,7 @@ export const INBOX_CARD_HTML = `<!doctype html>
       all.addEventListener("click", function () { open(data.allUrl); });
       root.appendChild(all);
     }
+    if (remeasure) remeasure();
   }
   window.addEventListener("message", function (event) {
     if (event.source !== window.parent) return;
@@ -183,11 +184,42 @@ export const INBOX_CARD_HTML = `<!doctype html>
       render((msg.params || {}).structuredContent);
     }
   });
+  // A host sizes the frame from what the view reports. Without a report the
+  // frame stays at zero height and the card is drawn but never seen.
+  function reportSize() {
+    var lastWidth = 0, lastHeight = 0, queued = false;
+    function measure() {
+      if (queued) return;
+      queued = true;
+      var next = typeof requestAnimationFrame === "function" ? requestAnimationFrame : function (fn) { setTimeout(fn, 16); };
+      next(function () {
+        queued = false;
+        var doc = document.documentElement, previous = doc.style.height;
+        doc.style.height = "max-content";
+        var height = Math.ceil(doc.getBoundingClientRect().height);
+        doc.style.height = previous;
+        var width = Math.ceil(window.innerWidth);
+        if (width === lastWidth && height === lastHeight) return;
+        lastWidth = width; lastHeight = height;
+        notify("ui/notifications/size-changed", { width: width, height: height });
+      });
+    }
+    remeasure = measure;
+    measure();
+    if (typeof ResizeObserver === "function") {
+      var observer = new ResizeObserver(measure);
+      observer.observe(document.documentElement);
+      observer.observe(document.body);
+    }
+  }
   send("ui/initialize", {
     protocolVersion: "2026-01-26",
     appInfo: { name: "Ziggs inbox card", version: "1" },
     appCapabilities: {}
-  }).then(function () { notify("ui/notifications/initialized", {}); }, function () {});
+  }).then(function () {
+    notify("ui/notifications/initialized", {});
+    reportSize();
+  }, function () {});
 })();
 </script>
 </body>

package/dist/inboxChannel.d.ts

@@ -0,0 +1,51 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InboxClient, type Creds } from '@ziggs-ai/api-client';
+export type InboxChangesOptions = NonNullable<Parameters<InboxClient['getChanges']>[0]>;
+export type InboxChangesResult = Awaited<ReturnType<InboxClient['getChanges']>>;
+/**
+ * The Claude Code channel: an open Claude Code session hears new Ziggs mail
+ * within seconds, without polling a tool.
+ *
+ * A local (stdio) server that declares `experimental['claude/channel']` may
+ * push `notifications/claude/channel`; Claude Code puts each one in front of
+ * the model as a `<channel>` tag. The server holds the inbox observation
+ * long-poll (`/inbox/changes`) and rings once per new delivery.
+ *
+ * It rings, it does not deliver. An event carries references only (kind and
+ * ids), never message text: what a counterparty wrote would otherwise land in
+ * the session as if the person had typed it. The model reads the mail through
+ * the inbox tools, so claiming, acknowledging and who handles the work stay
+ * exactly where they are. Observation itself never claims or acknowledges.
+ *
+ * Off unless `ZIGGS_MCP_CHANNEL` is set, and Claude Code also has to load the
+ * server as a channel (`--dangerously-load-development-channels server:<name>`
+ * while channels are a research preview). Without that, Claude Code drops the
+ * events and the long-poll costs no tokens.
+ */
+export declare const CHANNEL_CAPABILITY: {
+    'claude/channel': {};
+};
+export declare const CHANNEL_NOTIFICATION = "notifications/claude/channel";
+type Delivery = InboxChangesResult['deliveries'][number];
+type Observe = (options: InboxChangesOptions) => Promise<InboxChangesResult>;
+export interface ChannelEvent {
+    content: string;
+    meta: Record<string, string>;
+}
+/** The observation read for these credentials: the agent's, or the connection's. */
+export declare function observeFor(creds: Creds): Observe;
+/** One delivery as a channel event: what arrived and where, never what it says. */
+export declare function channelEvent(delivery: Delivery, agentId?: string): ChannelEvent;
+/** Mail that was already waiting when the session started, as one event. */
+export declare function backlogEvent(count: number): ChannelEvent;
+/**
+ * Watch the inbox and ring the session for each new delivery. Starts by
+ * folding whatever was already waiting into one event, so a session does not
+ * open to a wall of tags. Returns a stop function.
+ */
+export declare function startInboxChannel(server: McpServer, observe: Observe, options?: {
+    agentId?: string;
+    holdSeconds?: number;
+    log?: (line: string) => void;
+}): () => void;
+export {};

package/dist/inboxChannel.js

@@ -0,0 +1,133 @@
+import { AssistantConnectionClient, decodeOperatorKeyClaims, InboxClient, } from '@ziggs-ai/api-client';
+/**
+ * The Claude Code channel: an open Claude Code session hears new Ziggs mail
+ * within seconds, without polling a tool.
+ *
+ * A local (stdio) server that declares `experimental['claude/channel']` may
+ * push `notifications/claude/channel`; Claude Code puts each one in front of
+ * the model as a `<channel>` tag. The server holds the inbox observation
+ * long-poll (`/inbox/changes`) and rings once per new delivery.
+ *
+ * It rings, it does not deliver. An event carries references only (kind and
+ * ids), never message text: what a counterparty wrote would otherwise land in
+ * the session as if the person had typed it. The model reads the mail through
+ * the inbox tools, so claiming, acknowledging and who handles the work stay
+ * exactly where they are. Observation itself never claims or acknowledges.
+ *
+ * Off unless `ZIGGS_MCP_CHANNEL` is set, and Claude Code also has to load the
+ * server as a channel (`--dangerously-load-development-channels server:<name>`
+ * while channels are a research preview). Without that, Claude Code drops the
+ * events and the long-poll costs no tokens.
+ */
+export const CHANNEL_CAPABILITY = { 'claude/channel': {} };
+export const CHANNEL_NOTIFICATION = 'notifications/claude/channel';
+/** The longest hold `/inbox/changes` grants. */
+const HOLD_SECONDS = 110;
+const RETRY_MS = [1_000, 5_000, 15_000, 60_000];
+/** The observation read for these credentials: the agent's, or the connection's. */
+export function observeFor(creds) {
+    if (decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId) {
+        const client = new AssistantConnectionClient(creds);
+        return (options) => client.getChanges(options);
+    }
+    const inbox = new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId, {
+        clientSessionId: creds.clientSessionId,
+        workspaceIds: creds.workspaceIds,
+        app: creds.app,
+        sessionName: creds.sessionName,
+    });
+    return (options) => inbox.getChanges(options);
+}
+/** One delivery as a channel event: what arrived and where, never what it says. */
+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.taskId)
+        meta.task_id = delivery.taskId;
+    if (delivery.agreementId)
+        meta.agreement_id = delivery.agreementId;
+    if (delivery.orgId)
+        meta.org_id = delivery.orgId;
+    if (forYou)
+        meta.for_you = 'true';
+    if (delivery.needsHuman)
+        meta.needs_human = 'true';
+    const who = forYou ? ' It is assigned to you.' : delivery.needsHuman ? ' It asks for your person.' : '';
+    return {
+        content: `New Ziggs mail (${delivery.kind.replace(/_/g, ' ')}).${who} Read it with ziggs_inbox and follow its rules.`,
+        meta,
+    };
+}
+/** Mail that was already waiting when the session started, as one event. */
+export function backlogEvent(count) {
+    return {
+        content: `${count} ${count === 1 ? 'item was' : 'items were'} already waiting in Ziggs when this session started. Read them with ziggs_inbox when you are free.`,
+        meta: { kind: 'backlog', count: String(count) },
+    };
+}
+function apiStatus(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : undefined;
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+});
+/**
+ * Watch the inbox and ring the session for each new delivery. Starts by
+ * folding whatever was already waiting into one event, so a session does not
+ * open to a wall of tags. Returns a stop function.
+ */
+export function startInboxChannel(server, observe, options = {}) {
+    const stop = new AbortController();
+    const signal = stop.signal;
+    const hold = options.holdSeconds ?? HOLD_SECONDS;
+    const log = options.log ?? ((line) => process.stderr.write(`[ziggs-mcp channel] ${line}\n`));
+    const ring = (event) => server.server.notification({ method: CHANNEL_NOTIFICATION, params: { ...event } });
+    void (async () => {
+        let cursor;
+        let failures = 0;
+        while (!signal.aborted) {
+            try {
+                if (cursor === undefined) {
+                    // Catch up without a hold: what is retained now is the backlog.
+                    let waiting = 0;
+                    let page;
+                    do {
+                        page = await observe({ cursor, signal });
+                        cursor = page.cursor;
+                        waiting += page.deliveries.length;
+                    } while (page.hasMore && !signal.aborted);
+                    if (waiting > 0 && !signal.aborted)
+                        await ring(backlogEvent(waiting));
+                }
+                const page = await observe({ cursor, waitSeconds: hold, signal });
+                cursor = page.cursor;
+                failures = 0;
+                for (const delivery of page.deliveries) {
+                    if (signal.aborted)
+                        break;
+                    await ring(channelEvent(delivery, options.agentId));
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                // An expired cursor starts over from what is retained.
+                if (apiStatus(error) === 410) {
+                    cursor = undefined;
+                    continue;
+                }
+                const wait = RETRY_MS[Math.min(failures, RETRY_MS.length - 1)];
+                failures += 1;
+                log(`inbox watch failed (${error?.message ?? String(error)}); retrying in ${wait / 1000}s`);
+                await sleep(wait, signal);
+            }
+        }
+    })();
+    return () => stop.abort();
+}

package/dist/protocol/connectText.d.ts

@@ -10,8 +10,7 @@
  *
  * The same text for every client. The two doors differ only where their tools
  * do: the directory door's inbox read observes and a claim takes the lease,
- * while the compact door's full read takes it and the rest of the surface is
- * reached through the catalog. Everything else an agent needs is said where it
+ * while the compact door's full read takes it. Everything else an agent needs is said where it
  * applies — in the description of the tool it is about, as a fact about that
  * tool, or in the refusal that teaches it at the moment it matters. The long
  * protocol (`delegateProtocol.ts`) stays the source for SKILL.md and
@@ -27,5 +26,7 @@ export declare function sessionRules(door: ConnectDoor): string[];
 export interface ConnectTextOptions {
     /** The serving backend delivers `ziggs.inbox.updated` events. */
     events?: boolean;
+    /** The local server rings a Claude Code session through a channel. */
+    channel?: boolean;
 }
 export declare function renderConnectText(door: ConnectDoor, options?: ConnectTextOptions): string;

package/dist/protocol/connectText.js

@@ -10,8 +10,7 @@
  *
  * The same text for every client. The two doors differ only where their tools
  * do: the directory door's inbox read observes and a claim takes the lease,
- * while the compact door's full read takes it and the rest of the surface is
- * reached through the catalog. Everything else an agent needs is said where it
+ * while the compact door's full read takes it. Everything else an agent needs is said where it
  * applies — in the description of the tool it is about, as a fact about that
  * tool, or in the refusal that teaches it at the moment it matters. The long
  * protocol (`delegateProtocol.ts`) stays the source for SKILL.md and
@@ -46,7 +45,6 @@ const RULES = [
 export function sessionRules(door) {
     return [DATA, INBOX[door], WAIT, ACCESS, REPLY, GROUNDING];
 }
-const CATALOG = 'Only the everyday tools are loaded. ziggs_tools lists the rest; call them through ziggs_tool_read or ziggs_tool_write.';
 /**
  * Directory door only: inbox events ride the connection key that door is
  * minted for. Said only when the serving backend has events on, so a host is
@@ -55,13 +53,18 @@ const CATALOG = 'Only the everyday tools are loaded. ziggs_tools lists the rest;
  * text was already sized: that append is what cut the text mid-word.
  */
 const EVENTS = 'Inbox events: a host may subscribe to ziggs.inbox.updated per workspace; promise alerts only once it confirms. An event carries only orgId: read that inbox and follow its rules.';
+/**
+ * Compact door only, when the local server rings a Claude Code session. The
+ * event says that mail arrived, never what it says.
+ */
+const CHANNEL = 'A <channel> event from Ziggs means new mail (ids only): read it with ziggs_inbox and follow its rules.';
 export function renderConnectText(door, options = {}) {
     return [
         `- ${DATA}`,
         `- ${SESSION}`,
         `- ${INBOX[door]}`,
         ...RULES.map((r) => `- ${r}`),
-        ...(door === 'compact' ? [`- ${CATALOG}`] : []),
         ...(door === 'directory' && options.events ? [`- ${EVENTS}`] : []),
+        ...(door === 'compact' && options.channel ? [`- ${CHANNEL}`] : []),
     ].join('\n');
 }

package/dist/server.js

@@ -8,9 +8,10 @@ import { AssistantConnectionClient, decodeOperatorKeyClaims, InboxClient } from
 import { loadConfig } from './config.js';
 import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
-import { applySurfacePolicy } from './surface.js';
+import { applySurfacePolicy, listWithoutSchemaDialect } from './surface.js';
 import { backendToolPick } from './toolPick.js';
 import { renderConnectText } from './protocol/connectText.js';
+import { CHANNEL_CAPABILITY, observeFor, startInboxChannel } from './inboxChannel.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 /** Shared MCP server factory — stdio (local) and remote HTTP (backend) reuse this. */
@@ -25,8 +26,11 @@ export function createZiggsMcpServer(creds, cfg) {
         // stdio and remote HTTP alike, since both build the server here.
         instructions: renderConnectText(cfg.directConnection === false ? 'directory' : 'compact', {
             events: cfg.eventsEnabled === true,
+            channel: cfg.channel === true && cfg.directConnection !== false,
         }),
     });
+    if (cfg.channel === true && cfg.directConnection !== false)
+        server.server.registerCapabilities({ experimental: CHANNEL_CAPABILITY });
     if (cfg.directConnection === false)
         installDirectorySurface(server);
     installConnectionNotices(server, creds, version);
@@ -37,6 +41,7 @@ export function createZiggsMcpServer(creds, cfg) {
     // catalog remains only for self-configured operator-key clients.
     if (cfg.directConnection !== false)
         applySurfacePolicy(server, { pickTool: backendToolPick(creds) });
+    listWithoutSchemaDialect(server);
     return server;
 }
 /** Drop this process's inbox host. Best-effort — shutdown must not fail on it. */
@@ -74,4 +79,6 @@ export async function startStdioServer() {
     installStdioInboxHostRelease(creds);
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    if (cfg.channel)
+        startInboxChannel(server, observeFor(creds), { agentId: creds.agentId });
 }

package/dist/surface.d.ts

@@ -41,27 +41,23 @@ export declare const NATIVE_TOOLS: readonly string[];
  * when it refuses.
  */
 export declare const CATALOG_TOOLS: readonly string[];
-/** Per-tool how-to-call, derived from NATIVE_TOOLS and the annotations. */
+/** Per-tool how-to-call: every tool is listed, so by name, or through its lane's dispatcher. */
 export declare function callLine(entry: CatalogEntry): string;
 /**
- * Narrow `tools/list` to the native set, then register the tools that make the
- * rest reachable: the catalog, and one dispatcher per annotation lane.
- *
- * Narrowing by `.disable()` would be the shorter way to do this, and it is the
- * wrong one: disabling takes a tool out of `tools/list` AND out of
- * `tools/call`. The SDK answers a direct call on a disabled tool with
- * `Tool <name> disabled`, thrown from inside its own handler where we cannot
- * reword it — so a caller holding a name (a saved config, a script, a model
- * that learned the name in an earlier session) hits a wall that does not say
- * the tool exists, where it went, or how to reach it.
- *
- * So every tool stays ENABLED, and the listing is narrowed instead. A name is
- * always callable; the list is still the native set plus the catalog tools.
+ * Drop the `$schema` line the SDK writes into every tool's input and output
+ * schema. It names a JSON Schema dialect no MCP client reads, and on the
+ * directory door it was the same 52 characters 64 times in every
+ * `tools/list`. Wraps whatever handler is installed last, so call it after
+ * every other `tools/list` filter.
+ */
+export declare function listWithoutSchemaDialect(server: McpServer): void;
+/**
+ * Register the catalog and one dispatcher per annotation lane, next to every
+ * tool listed by name.
  *
- * The listing delegates to the handler the SDK installed rather than rebuilding
- * one: the SDK owns how a registered tool becomes a `tools/list` entry, and
- * hand-building that response would risk a schema-shape difference on exactly
- * the tools every caller loads. We filter its output and change nothing else.
+ * The catalog answers by search and by plain-sentence need, and the
+ * dispatchers reach any tool by name, so a client that mounts only part of
+ * the list (an allow-list) still reaches the rest.
  */
 export declare function applySurfacePolicy(server: McpServer, opts?: {
     /** Answers `ziggs_tools need=`. Absent: `need` falls back to the full list. */

package/dist/surface.js

@@ -63,7 +63,6 @@ export const CATALOG_TOOLS = [
     TOOL_READ_NAME,
     TOOL_WRITE_NAME,
 ];
-const CATALOG_TOOL_NAMES = new Set(CATALOG_TOOLS);
 /**
  * A tool that takes a freeform target and payload has to say which API it
  * reaches; a store reviewer cannot otherwise tell what it does.
@@ -77,21 +76,15 @@ const TOOL_WRITE_DESCRIPTION = `Call a Ziggs tool that creates or changes someth
     'This reaches every writing tool ziggs_tools lists, native or not. Read-only tools are refused here and pointed at ziggs_tool_read. Most writes cannot be taken back (a sent message, a taken decision, an overwritten plan), so a call through here may ask the human first. ' +
     'Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. ' +
     'The result is exactly what the tool itself returns.';
-function isNative(name) {
-    return NATIVE_TOOLS.includes(name);
-}
-/** Per-tool how-to-call, derived from NATIVE_TOOLS and the annotations. */
+/** Per-tool how-to-call: every tool is listed, so by name, or through its lane's dispatcher. */
 export function callLine(entry) {
-    const dispatcher = laneOf(entry);
-    if (isNative(entry.name)) {
-        return `call it by name: ${entry.name}; ${dispatcher} { tool: "${entry.name}", args } also works`;
-    }
-    return `call via ${dispatcher} { tool, args }`;
+    return `call it by name: ${entry.name}; ${laneOf(entry)} { tool: "${entry.name}", args } also works`;
 }
 function withCall(entry, base) {
     return {
         ...base,
-        ...(isNative(entry.name) ? { native: true } : {}),
+        // Every tool is listed by name now, so every row is native.
+        native: true,
         call: callLine(entry),
     };
 }
@@ -103,31 +96,32 @@ function laneOf(entry) {
     return entry.annotations.readOnlyHint ? TOOL_READ_NAME : TOOL_WRITE_NAME;
 }
 /**
- * Keep `tools/list` to `listed` (plus the catalog tools, registered after this
- * runs) by filtering the response the SDK's own handler builds.
- *
- * The handler is read back off the underlying `Server` so the SDK stays the
- * author of every entry. That map is internal, so this asserts rather than
- * degrades: if a future SDK stops keeping handlers there, the server refuses to
- * start and says why. A silent fallback would ship the whole 58-tool surface to
- * every caller — the regression this policy exists to prevent — and it would
- * look like it worked.
+ * Drop the `$schema` line the SDK writes into every tool's input and output
+ * schema. It names a JSON Schema dialect no MCP client reads, and on the
+ * directory door it was the same 52 characters 64 times in every
+ * `tools/list`. Wraps whatever handler is installed last, so call it after
+ * every other `tools/list` filter.
  */
-function listOnly(server, listed) {
+export function listWithoutSchemaDialect(server) {
     const inner = server.server;
     const built = inner._requestHandlers?.get('tools/list');
-    if (!built) {
-        throw new Error('ziggs-mcp: the MCP SDK no longer exposes its tools/list handler at ' +
-            "server._requestHandlers.get('tools/list'), so the surface cannot be " +
-            'narrowed to the native set. Fix surface.ts before shipping: without ' +
-            'this filter every tool is listed and a cold connection pays for the ' +
-            'whole catalog.');
-    }
+    if (!built)
+        return;
+    const strip = (schema) => {
+        if (!schema || typeof schema !== 'object')
+            return schema;
+        const { $schema: _dialect, ...rest } = schema;
+        return rest;
+    };
     server.server.setRequestHandler(ListToolsRequestSchema, async (req, extra) => {
         const all = await built(req, extra);
         return {
             ...all,
-            tools: all.tools.filter((t) => listed.has(t.name) || CATALOG_TOOL_NAMES.has(t.name)),
+            tools: all.tools.map((tool) => ({
+                ...tool,
+                inputSchema: strip(tool.inputSchema),
+                ...(tool.outputSchema ? { outputSchema: strip(tool.outputSchema) } : {}),
+            })),
         };
     });
 }
@@ -180,28 +174,20 @@ function registerDispatcher(server, lane) {
     });
 }
 /**
- * Narrow `tools/list` to the native set, then register the tools that make the
- * rest reachable: the catalog, and one dispatcher per annotation lane.
- *
- * Narrowing by `.disable()` would be the shorter way to do this, and it is the
- * wrong one: disabling takes a tool out of `tools/list` AND out of
- * `tools/call`. The SDK answers a direct call on a disabled tool with
- * `Tool <name> disabled`, thrown from inside its own handler where we cannot
- * reword it — so a caller holding a name (a saved config, a script, a model
- * that learned the name in an earlier session) hits a wall that does not say
- * the tool exists, where it went, or how to reach it.
- *
- * So every tool stays ENABLED, and the listing is narrowed instead. A name is
- * always callable; the list is still the native set plus the catalog tools.
+ * Register the catalog and one dispatcher per annotation lane, next to every
+ * tool listed by name.
  *
- * The listing delegates to the handler the SDK installed rather than rebuilding
- * one: the SDK owns how a registered tool becomes a `tools/list` entry, and
- * hand-building that response would risk a schema-shape difference on exactly
- * the tools every caller loads. We filter its output and change nothing else.
+ * The catalog answers by search and by plain-sentence need, and the
+ * dispatchers reach any tool by name, so a client that mounts only part of
+ * the list (an allow-list) still reaches the rest.
  */
 export function applySurfacePolicy(server, opts = {}) {
-    const native = new Set(NATIVE_TOOLS);
-    listOnly(server, native);
+    // Every tool is listed, as on the directory door. Listing everything costs
+    // the same or less per task, because a tool outside the everyday set no
+    // longer needs a catalog call first, and a host's permission prompt names
+    // the real tool.
+    // The catalog stays listed for clients that mount only an allow-list (the
+    // Copilot coding agent) and reach the rest through it.
     registerStrictTool(server, TOOLS_CATALOG_NAME, {
         describe: z
             .array(z.string())

package/dist/tools.js

@@ -927,12 +927,12 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .max(80)
             .optional()
-            .describe('Short label for list rows, around 60 characters. Omit and the task lists under a trimmed description, which is a wall of prose at a glance. Set it whenever this task will be one row among many.'),
+            .describe('Short list label, around 60 characters. Set it when this is one of many tasks; otherwise the list shows the description.'),
         parentTaskId: z.string().optional().describe('Parent task id for sub-tasks'),
         assigneeId: z
             .string()
             .optional()
-            .describe('Agent or user ID to explicitly assign this task to — must hold a grant on the agreement, so you can only hand work to someone that contract already reaches'),
+            .describe('Agent or user to assign it to; they must already hold a grant on the agreement.'),
         inputArtifactIds: z
             .array(z.string())
             .optional()
@@ -940,7 +940,7 @@ export function registerZiggsTools(server, creds, cfg) {
         waitsOn: z
             .array(z.string())
             .optional()
-            .describe('Task ids this task waits for. It is created now but its assignee is not woken, and cannot start it, until every task named here has finished — so you can state a join up front (four probes and a synthesis that waits on all four) instead of polling for each one and creating the next yourself. Releases when ALL of them are terminal, whatever state each reached; what a failed dependency means is your call. You must be able to read a task to name it here.'),
+            .describe('Task ids to wait for: created now, but its assignee is not woken until all of them end, in any state. States a join up front instead of polling. Name only tasks you can read.'),
         closesBy: z
             .enum(['result', 'children'])
             .optional()
@@ -965,7 +965,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .min(1)
             .max(100)
             .optional()
-            .describe('Children created with this task, all or none. waitsOn names sibling names. The answer maps each name to its task id. This task\'s inputArtifactIds go to children that wait on nothing; planReviewTiming before_execution holds every child until this task\'s plan is acknowledged. runIf makes a child conditional on what the children before it found.'),
+            .describe('Children created with this task, all or none; waitsOn names sibling names, and the answer maps each name to its task id. Children that wait on nothing get this task\'s inputArtifactIds. before_execution holds every child until the plan is acknowledged.'),
         // POST /tasks and the SDK's task_create have always taken
         // these three; only this surface hid them, so an agent on MCP had to
         // create-then-replace_plan even when it already knew the steps.
@@ -1021,7 +1021,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 .describe('Total reminders allowed per person asked, after the first ask. Then the holder stops and reports.'),
         })
             .optional()
-            .describe('How often the holder may remind, and how many times at most. Both halves are required together: a cadence with no budget is refused, because one reminder is one wake and a rule that never says stop is an open-ended loop. Omit entirely for a task nobody needs reminding about.'),
+            .describe('How often the holder may remind and how many times at most; both are required. Omit for a task nobody needs reminding about.'),
         sources: sourcesField(),
     }, write('Create a task'), async ({ agreementId, description, title, parentTaskId, assigneeId, inputArtifactIds, waitsOn, closesBy, children, plan, planReviewTiming, requireMidWorkPlanAck, dueAt, checkBack, sources, }) => {
         try {

package/package.json

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