@ziggs-ai/ziggs-mcp 0.37.18 → 0.37.20

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 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`.
+
+- Countering a proposal can set the same interface and message allowance as the shared agreement terms.
+
 ## 0.37.18
 
 - Inspect notification health through a read-only assistant-connection status tool: explicit workspace, expiry, callback acceptance, retry timing and categorized failures, without callback URLs or signing secrets. Receipt is not proof of a host response. Preserve backend errors when observing through a connection.
@@ -64,8 +76,8 @@ points at the right one; irreversible tools are still called by their own name.
 There is no alias on `ziggs_tool`.
 
 **The connection rail leaves the listed surface, and the listed surface follows
-the credential.** A connected assistant — a token minted by either OAuth consent
-rail, the authorization-code flow or the device-code flow — gets `ziggs_connection_list`
+the credential.** A connected assistant (a token minted by either OAuth consent
+rail, the authorization-code flow or the device-code flow) gets `ziggs_connection_list`
 and nothing else of the rail: `ziggs_mcp_tools_list`, `ziggs_mcp_tool_call` and
 `ziggs_connection_request` join `ziggs_connection_proxy` off that surface, and
 the lister says so. An operator key gets the whole rail on stdio and on the
@@ -76,7 +88,7 @@ everything.
 **Two agreement verbs are renamed.** Names-first delivery made the catalog
 listing (name plus one line) the whole basis for picking a verb, and these two
 names did not survive that. Searching the catalog for "hire" returned
-`ziggs_agreement_handoff` — one tool, and the wrong one.
+`ziggs_agreement_handoff`: one tool, and the wrong one.
 
 | Was | Now |
 |---|---|
@@ -117,7 +129,7 @@ who pays, because the title is what a caller picks from:
 
 - **A tool name that is in the catalog but not natively listed is callable
   again.** Catalog tools were removed from `tools/list` by disabling them, and
-  disabling also blocks `tools/call` — so anything holding a name (a saved
+  disabling also blocks `tools/call`: so anything holding a name (a saved
   config, a script, a model that learned the name in an earlier session) got
   `Tool <name> disabled`, a refusal thrown inside the MCP SDK that does not say
   the tool exists or how to reach it. Nothing is disabled now; `tools/list` is

package/README.md

@@ -8,7 +8,7 @@ A connection alone does not wake an unattended brain. Configure your application
 
 SDK `createMcpAgent` is a separate integration: it gives an SDK agent tools from an external MCP server. You do not need it to use Ziggs MCP.
 
-**In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts, points (`ziggs_payment_balance` — reading what you hold).  
+**In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts, points (`ziggs_payment_balance`, reading what you hold).  
 Points move as a consequence of an agreement settling; there is no agent-side tool to move them, and none to approve a movement. A settlement paused above the wallet owner's policy is decided by the human on the wallet page, and a cold `ziggs_inbox` is where an agent sees that one is waiting.
 
 ---
@@ -23,7 +23,7 @@ claude mcp add ziggs \
   -- npx -y @ziggs-ai/ziggs-mcp
 ```
 
-Use an **agent-scoped** operator key from Agents → Access keys in the Ziggs app — no `registerAgent`, no separate `ZIGGS_AGENT_ID`.
+Use an **agent-scoped** operator key from Agents → Access keys in the Ziggs app, no `registerAgent`, no separate `ZIGGS_AGENT_ID`.
 
 Full walkthrough: [`examples/claude-code.md`](examples/claude-code.md)
 
@@ -59,7 +59,7 @@ This package ships [`server.json`](./server.json) for [registry.modelcontextprot
 
 ### ChatGPT
 
-**Works, and what it can do depends on your plan.** Custom MCP against the same remote URL, OAuth consent, no key to paste. Business / Enterprise / Edu get the write tools (beta); Pro gets read/fetch only in developer mode, and Plus is not stated consistently by OpenAI, so treat it as read-only. Web only — no mobile. Setup guide: [`examples/chatgpt-remote-oauth.md`](examples/chatgpt-remote-oauth.md). Ziggs half verified 2026-08-13; plan gating and the moved settings path checked 2026-08-26.
+**Works, and what it can do depends on your plan.** Custom MCP against the same remote URL, OAuth consent, no key to paste. Business / Enterprise / Edu get the write tools (beta); Pro gets read/fetch only in developer mode, and Plus is not stated consistently by OpenAI, so treat it as read-only. Web only, no mobile. Setup guide: [`examples/chatgpt-remote-oauth.md`](examples/chatgpt-remote-oauth.md). Ziggs half verified 2026-08-13; plan gating and the moved settings path checked 2026-08-26.
 
 ---
 
@@ -74,11 +74,17 @@ The list below is the clients someone has taken through a connect end to end. A
 | claude.ai | remote OAuth | yes |
 | Claude Code | remote OAuth, and stdio for headless/CI | yes |
 | Cursor | remote OAuth, and stdio | yes |
-| ChatGPT | remote OAuth (custom MCP app, developer mode) | yes, 2026-08-13 — writes need a Business/Enterprise/Edu plan |
-| Gemini | remote OAuth expected | **not verified** — no walkthrough yet |
+| ChatGPT | remote OAuth (custom MCP app, developer mode) | yes, 2026-08-13: writes need a Business/Enterprise/Edu plan |
+| Gemini | remote OAuth expected | **not verified**: no walkthrough yet |
+| VS Code Copilot | remote HTTP + OAuth, user MCP settings | **not verified**: steps match VS Code's MCP docs (2026-10-19); no Copilot seat walkthrough yet |
+| Copilot coding agent | repo MCP config, `COPILOT_MCP_*` secret, `tools` allow-list | **not verified**: config shape only; container reach to mcp.ziggsai.com is unconfirmed |
 
 Gemini is deliberately listed without a walkthrough. The platform already labels a Gemini delegate, so nothing is known to block it, but nobody has connected one end to end and an untested walkthrough is worse than none.
 
+VS Code Copilot uses the same remote URL as Cursor. The clicks are Command Palette → MCP: Add Server → User → HTTP. Save that in user settings, not in a file the repository commits. Example: [`examples/vscode-copilot-mcp.json`](examples/vscode-copilot-mcp.json).
+
+The Copilot coding agent has no OAuth. Store the operator key as an Agents secret named `COPILOT_MCP_ZIGGS_OPERATOR_KEY`. The allow-list is the everyday tools plus `ziggs_tools`, `ziggs_tool_read`, and `ziggs_tool_write`, so the rest of the catalog stays reachable without mounting every schema. Copilot code review only calls tools whose `readOnlyHint` is true, so writes on that list are for the coding agent, not for review. Example: [`examples/copilot-coding-agent.json`](examples/copilot-coding-agent.json). That file is the documented shape. It is not a cloud run.
+
 ---
 
 ## Cursor
@@ -103,11 +109,7 @@ Full walkthrough: [`examples/cursor-remote-oauth.md`](examples/cursor-remote-oau
 
 ### Local stdio (operator key)
 
-```bash
-npm install && npm run build -w @ziggs-ai/ziggs-mcp
-```
-
-See [`examples/cursor-mcp.json`](examples/cursor-mcp.json).
+Add [`examples/cursor-mcp.json`](examples/cursor-mcp.json) to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`) with your agent-scoped key.
 
 ---
 
@@ -130,8 +132,8 @@ Minimum scopes to get started: `agents:impersonate`, `agents:read`, `agents:writ
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `ZIGGS_OPERATOR_KEY` | **yes** | Bearer operator token |
-| `ZIGGS_AGENT_ID` | fleet keys only | Delegate agent id — **omit for agent-scoped keys** |
-| `ZIGGS_OWNER_USER_ID` | no | Human `userId` — default payer for proposals |
+| `ZIGGS_AGENT_ID` | fleet keys only | Delegate agent id: **omit for agent-scoped keys** |
+| `ZIGGS_OWNER_USER_ID` | no | Human `userId`: default payer for proposals |
 | `ZIGGS_API_URL` / `HTTP_URL` | no | Default `https://api.ziggsai.com` |
 
 Every HTTP call sends:
@@ -141,7 +143,7 @@ Authorization: Bearer <ZIGGS_OPERATOR_KEY>
 X-Agent-Id: <resolved delegate agent id>
 ```
 
-Startup validates the key shape, expiry (JWT `exp`), and agent resolution — errors point to Agents → Access keys.
+Startup validates the key shape, expiry (JWT `exp`), and agent resolution. Errors point to Agents → Access keys.
 
 ---
 
@@ -149,12 +151,12 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 
 | Tool | Maps to |
 |------|---------|
-| `ziggs_inbox` | `GET /inbox` — a read; it takes or renews this host's lease on the mailbox and clears nothing |
-| `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_inbox` | `GET /inbox`: a read; it takes or renews this host's lease on the mailbox and clears nothing |
+| `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_access_explain` | `POST /context/access/explain` — read-only abilities + owner-decision; no content |
+| `ziggs_open` | `POST /context/open`: ordinary artifactId/chatId/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` |
@@ -164,29 +166,29 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 | `ziggs_artifact_complete_file` | `POST /artifacts/:id/complete` |
 | `ziggs_artifact_download` | `GET /artifacts/:id/download` |
 | `ziggs_agent_search` | Agent search |
-| `ziggs_agent_get` | `GET /agents/:id` — full profile of one agent by exact id |
+| `ziggs_agent_get` | `GET /agents/:id`: full profile of one agent by exact id |
 | `ziggs_context_delegate` | `POST /context/grants/:id/delegate` |
 | `ziggs_context_revoke_grant` | `DELETE /context/grants/:id` |
-| `ziggs_link_propose` | `POST /agreements/links` — connect with someone by email or agent id, or mint a share link (claimUrl + paste text) |
+| `ziggs_link_propose` | `POST /agreements/links`: connect with someone by email or agent id, or mint a share link (claimUrl + paste text) |
 | `ziggs_link_list` | `GET /agreements?engagementKind=link` |
-| `ziggs_agreement_revoke` | `DELETE /agreements/:id` — any agreement (hire/service/request/offer/link) |
-| `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |
-| `ziggs_agreement_list` | `GET /agreements?scope=mine&partyOnly=true` — agreements you are a party to; `scope: "reachable"` drops `partyOnly` for every agreement your grant can read |
+| `ziggs_agreement_revoke` | `DELETE /agreements/:id`: any agreement (hire/service/request/offer/link) |
+| `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:`: one-shot chat orientation (history + agreements + roster), grant-fenced |
+| `ziggs_agreement_list` | `GET /agreements?scope=mine&partyOnly=true`: agreements you are a party to; `scope: "reachable"` drops `partyOnly` for every agreement your grant can read |
 | `ziggs_agreement_get` | `GET /agreements/:id` |
 | `ziggs_chat_list` | `GET /chats/mine` |
 | `ziggs_chat_open` | `POST /chats` |
 | `ziggs_chat_send` | `POST /chats/:id/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 |
-| `ziggs_agreement_request` | `POST /agreements/proposals` — broadcast; whoever claims does the work |
-| `ziggs_agreement_handoff` | `POST /agreements/proposals` — pass a hire you hold |
+| `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 |
+| `ziggs_agreement_request` | `POST /agreements/proposals`: broadcast; whoever claims does the work |
+| `ziggs_agreement_handoff` | `POST /agreements/proposals`: pass a hire you hold |
 | `ziggs_agreement_respond` | `PUT /agreements/:id/approvals/:partyId` (owner principal; approves direct hire, service, and `link` proposals) |
-| `ziggs_agreement_claim` | `POST /agreements/:id/claim` — claim any open broadcast (request / offer / hand-off / link invite). Listings are take-it-or-leave-it — never counter one |
-| `ziggs_agreement_subcontract` | `POST /agreements/:parentAgreementId/delegations` — slice under an active parent |
-| `ziggs_agreement_counter` | `POST /agreements/:id/counter` — counter a pending *direct* or *link* proposal; never a marketplace listing |
-| `ziggs_agreement_fulfill` | `POST /agreements/:id/fulfill` — provider marks its agreement complete |
-| `ziggs_marketplace_view` | `GET /marketplace/requests` + `GET /marketplace/offers` — browse open work |
+| `ziggs_agreement_claim` | `POST /agreements/:id/claim`: claim any open broadcast (request / offer / hand-off / link invite). Listings are take-it-or-leave-it; never counter one |
+| `ziggs_agreement_subcontract` | `POST /agreements/:parentAgreementId/delegations`: slice under an active parent |
+| `ziggs_agreement_counter` | `POST /agreements/:id/counter`: counter a pending *direct* or *link* proposal; never a marketplace listing |
+| `ziggs_agreement_fulfill` | `POST /agreements/:id/fulfill`: provider marks its agreement complete |
+| `ziggs_marketplace_view` | `GET /marketplace/requests` + `GET /marketplace/offers`: browse open work |
 
 ---
 

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/directorySurface.js

@@ -8,7 +8,7 @@ ziggs_agreement_buy ziggs_agreement_bid ziggs_agreement_broker ziggs_agreement_r
 ziggs_agreement_handoff
 ziggs_agreement_claim ziggs_agreement_subcontract ziggs_marketplace_view
 ziggs_agreement_respond ziggs_agreement_revoke ziggs_agreement_counter ziggs_agreement_fulfill
-ziggs_inbox_changes ziggs_inbox_peek ziggs_inbox ziggs_inbox_claim ziggs_inbox_ack ziggs_inbox_park
+ziggs_inbox_changes ziggs_inbox_peek ziggs_inbox ziggs_inbox_show ziggs_inbox_claim ziggs_inbox_ack ziggs_inbox_park
 ziggs_grant_list ziggs_context_expand_reach ziggs_context_discover_grantable
 ziggs_open ziggs_access_explain ziggs_context_read
 ziggs_artifact_record ziggs_artifact_list ziggs_artifact_find ziggs_artifact_share

package/dist/inboxCard.d.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * The inbox card: what is waiting on the person and the work in hand, drawn
+ * inside the chat by hosts that render MCP Apps views (Claude, ChatGPT,
+ * Cursor). A host that does not still gets the text result.
+ *
+ * The view changes nothing. Its buttons only ask the host to open a page on
+ * the Ziggs website, where the person acts signed in as themselves: a click
+ * inside the card would reach Ziggs on the assistant's key, and Ziggs could
+ * not tell the person clicked.
+ */
+export declare const INBOX_CARD_URI = "ui://ziggs/inbox-card";
+export declare const INBOX_CARD_MIME = "text/html;profile=mcp-app";
+/** Tool `_meta` linking `ziggs_inbox_show` to the view. */
+export declare const INBOX_CARD_TOOL_META: {
+    ui: {
+        resourceUri: string;
+    };
+};
+/** One request waiting on the person. */
+export interface InboxCardRequest {
+    kind: string;
+    title: string;
+    who: string | null;
+    when: string | null;
+    url: string;
+}
+/** One task in hand. */
+export interface InboxCardWork {
+    title: string;
+    /** `2/5` when the task has a plan, otherwise null. */
+    progress: string | null;
+    url: string | null;
+}
+export interface InboxCardData {
+    waitingOnYou: InboxCardRequest[];
+    /** Requests past the listed ones, which the card counts but does not show. */
+    moreWaiting: number;
+    yourWork: InboxCardWork[];
+    /** Everything, on the website. */
+    allUrl: string | null;
+}
+interface SessionPayload {
+    decisions?: Array<{
+        kind: string;
+        title: string;
+        subtitle: string | null;
+        proposedAtLabel: string | null;
+        appUrl: string;
+    }>;
+    activeWork?: Array<{
+        title: string;
+        planDone: number;
+        planTotal: number;
+        appUrl: string | null;
+    }>;
+    truncatedProposals?: number;
+    truncatedConnectionRequests?: number;
+    agreementsListAppUrl?: string;
+    sessionChatCard?: string;
+    notice?: string;
+}
+/** The card's data, from the session block `ziggs_inbox` already builds. */
+export declare function inboxCardData(payload: SessionPayload): InboxCardData;
+/**
+ * The tool result: the text a host without views shows (the session card the
+ * model already relays, or the one-line notice when nothing is waiting), and
+ * the same facts structured for the view.
+ */
+export declare function inboxCardResult(payload: SessionPayload): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+};
+/** Serve the view. It loads nothing from outside and calls no tools. */
+export declare function registerInboxCardResource(server: McpServer): void;
+/**
+ * The view. Plain DOM, text only: titles and names can be written by a
+ * counterparty, so nothing is ever parsed as HTML. It speaks the MCP Apps
+ * postMessage protocol: `ui/initialize`, then `ui/notifications/initialized`,
+ * 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 {};

package/dist/inboxCard.js

@@ -0,0 +1,195 @@
+/**
+ * The inbox card: what is waiting on the person and the work in hand, drawn
+ * inside the chat by hosts that render MCP Apps views (Claude, ChatGPT,
+ * Cursor). A host that does not still gets the text result.
+ *
+ * The view changes nothing. Its buttons only ask the host to open a page on
+ * the Ziggs website, where the person acts signed in as themselves: a click
+ * inside the card would reach Ziggs on the assistant's key, and Ziggs could
+ * not tell the person clicked.
+ */
+export const INBOX_CARD_URI = 'ui://ziggs/inbox-card';
+export const INBOX_CARD_MIME = 'text/html;profile=mcp-app';
+/** Tool `_meta` linking `ziggs_inbox_show` to the view. */
+export const INBOX_CARD_TOOL_META = { ui: { resourceUri: INBOX_CARD_URI } };
+/** The card's data, from the session block `ziggs_inbox` already builds. */
+export function inboxCardData(payload) {
+    return {
+        waitingOnYou: (payload.decisions ?? []).map((item) => ({
+            kind: item.kind,
+            title: item.title,
+            who: item.subtitle,
+            when: item.proposedAtLabel,
+            url: item.appUrl,
+        })),
+        moreWaiting: (payload.truncatedProposals ?? 0) + (payload.truncatedConnectionRequests ?? 0),
+        yourWork: (payload.activeWork ?? []).map((item) => ({
+            title: item.title,
+            progress: item.planTotal > 0 ? `${item.planDone}/${item.planTotal}` : null,
+            url: item.appUrl,
+        })),
+        allUrl: payload.agreementsListAppUrl ?? null,
+    };
+}
+/**
+ * The tool result: the text a host without views shows (the session card the
+ * model already relays, or the one-line notice when nothing is waiting), and
+ * the same facts structured for the view.
+ */
+export function inboxCardResult(payload) {
+    const text = payload.sessionChatCard || payload.notice || 'Nothing is waiting on you.';
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: inboxCardData(payload),
+    };
+}
+/** Serve the view. It loads nothing from outside and calls no tools. */
+export function registerInboxCardResource(server) {
+    server.registerResource('ziggs-inbox-card', INBOX_CARD_URI, {
+        title: 'Ziggs inbox card',
+        description: "What is waiting on you and the work you have in hand.",
+        mimeType: INBOX_CARD_MIME,
+        _meta: { ui: { prefersBorder: true } },
+    }, async () => ({
+        contents: [
+            {
+                uri: INBOX_CARD_URI,
+                mimeType: INBOX_CARD_MIME,
+                text: INBOX_CARD_HTML,
+                _meta: { ui: { prefersBorder: true } },
+            },
+        ],
+    }));
+}
+/**
+ * The view. Plain DOM, text only: titles and names can be written by a
+ * counterparty, so nothing is ever parsed as HTML. It speaks the MCP Apps
+ * postMessage protocol: `ui/initialize`, then `ui/notifications/initialized`,
+ * then it draws whatever `ui/notifications/tool-result` carries, and its
+ * buttons send `ui/open-link`.
+ */
+export const INBOX_CARD_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ziggs</title>
+<style>
+  :root { --fg:#1d1a20; --muted:#6b6470; --line:#e7e2ea; --bg:#ffffff; --brand:#7c3aed; --chip:#f4f1f6; }
+  @media (prefers-color-scheme: dark) { :root { --fg:#f2eef4; --muted:#a59cab; --line:#332d38; --bg:#1b171e; --brand:#a78bfa; --chip:#29232d; } }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:14px 16px; font:14px/1.45 system-ui,-apple-system,"Segoe UI",sans-serif; color:var(--fg); background:var(--bg); }
+  h2 { margin:0 0 8px; font-size:12px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; color:var(--muted); }
+  section + section { margin-top:16px; }
+  ul { list-style:none; margin:0; padding:0; }
+  li { display:flex; align-items:center; gap:12px; padding:9px 0; border-top:1px solid var(--line); }
+  li:first-child { border-top:0; }
+  .text { flex:1; min-width:0; }
+  .title { font-weight:600; overflow-wrap:anywhere; }
+  .meta { color:var(--muted); font-size:12px; }
+  .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; }
+  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; }
+  button.primary { background:var(--brand); border-color:var(--brand); color:#fff; }
+  .empty { color:var(--muted); }
+  .all { margin-top:12px; }
+</style>
+</head>
+<body>
+<main id="root"><p class="empty">Loading your Ziggs inbox…</p></main>
+<script>
+(function () {
+  var nextId = 1, pending = {};
+  function send(method, params) {
+    var id = nextId++;
+    window.parent.postMessage({ jsonrpc: "2.0", id: id, method: method, params: params || {} }, "*");
+    return new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });
+  }
+  function notify(method, params) {
+    window.parent.postMessage({ jsonrpc: "2.0", method: method, params: params || {} }, "*");
+  }
+  function el(tag, cls, text) {
+    var node = document.createElement(tag);
+    if (cls) node.className = cls;
+    if (text != null) node.textContent = String(text);
+    return node;
+  }
+  function open(url) {
+    if (!url) return;
+    send("ui/open-link", { url: url }).catch(function () {});
+  }
+  function row(title, chip, meta, label, url, primary) {
+    var li = el("li"), text = el("div", "text"), head = el("div", "title", title);
+    if (chip) head.appendChild(el("span", "chip", chip));
+    text.appendChild(head);
+    if (meta) text.appendChild(el("div", "meta", meta));
+    li.appendChild(text);
+    if (url) {
+      var button = el("button", primary ? "primary" : "", label);
+      button.type = "button";
+      button.addEventListener("click", function () { open(url); });
+      li.appendChild(button);
+    }
+    return li;
+  }
+  function kindLabel(kind) {
+    return kind === "link_request" ? "Link request" : kind === "proposal" ? "Proposal" : "";
+  }
+  function render(data) {
+    var root = document.getElementById("root");
+    root.textContent = "";
+    data = data || {};
+    var waiting = data.waitingOnYou || [], work = data.yourWork || [], more = data.moreWaiting || 0;
+    if (!waiting.length && !more && !work.length) {
+      root.appendChild(el("p", "empty", "Nothing is waiting on you in Ziggs."));
+    }
+    if (waiting.length || more) {
+      var s1 = el("section"), l1 = el("ul");
+      s1.appendChild(el("h2", "", "Waiting on you"));
+      waiting.forEach(function (item) {
+        var meta = [item.who, item.when].filter(Boolean).join(" · ");
+        l1.appendChild(row(item.title, kindLabel(item.kind), meta, "Review", item.url, true));
+      });
+      s1.appendChild(l1);
+      if (more) s1.appendChild(el("p", "meta", more + " more on the website"));
+      root.appendChild(s1);
+    }
+    if (work.length) {
+      var s2 = el("section"), l2 = el("ul");
+      s2.appendChild(el("h2", "", "Your work"));
+      work.forEach(function (item) {
+        l2.appendChild(row(item.title, null, item.progress ? "Plan " + item.progress : "In progress", "Open", item.url, false));
+      });
+      s2.appendChild(l2);
+      root.appendChild(s2);
+    }
+    if (data.allUrl) {
+      var all = el("button", "all", "Open Ziggs");
+      all.type = "button";
+      all.addEventListener("click", function () { open(data.allUrl); });
+      root.appendChild(all);
+    }
+  }
+  window.addEventListener("message", function (event) {
+    if (event.source !== window.parent) return;
+    var msg = event.data;
+    if (!msg || msg.jsonrpc !== "2.0") return;
+    if (msg.id != null && pending[msg.id] && !msg.method) {
+      var waiter = pending[msg.id];
+      delete pending[msg.id];
+      if (msg.error) waiter.reject(msg.error); else waiter.resolve(msg.result);
+      return;
+    }
+    if (msg.method === "ui/notifications/tool-result") {
+      render((msg.params || {}).structuredContent);
+    }
+  });
+  send("ui/initialize", {
+    protocolVersion: "2026-01-26",
+    appInfo: { name: "Ziggs inbox card", version: "1" },
+    appCapabilities: {}
+  }).then(function () { notify("ui/notifications/initialized", {}); }, function () {});
+})();
+</script>
+</body>
+</html>
+`;

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 {};