@ziggs-ai/ziggs-mcp 0.37.19 → 0.37.20

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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`.

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/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

@@ -27,5 +27,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

@@ -55,6 +55,11 @@ 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}`,
@@ -63,5 +68,6 @@ export function renderConnectText(door, options = {}) {
         ...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

@@ -43,6 +43,14 @@ export declare const NATIVE_TOOLS: readonly string[];
 export declare const CATALOG_TOOLS: readonly string[];
 /** Per-tool how-to-call, derived from NATIVE_TOOLS and the annotations. */
 export declare function callLine(entry: CatalogEntry): string;
+/**
+ * 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;
 /**
  * Narrow `tools/list` to the native set, then register the tools that make the
  * rest reachable: the catalog, and one dispatcher per annotation lane.

package/dist/surface.js

@@ -131,6 +131,36 @@ function listOnly(server, listed) {
         };
     });
 }
+/**
+ * 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 function listWithoutSchemaDialect(server) {
+    const inner = server.server;
+    const built = inner._requestHandlers?.get('tools/list');
+    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.map((tool) => ({
+                ...tool,
+                inputSchema: strip(tool.inputSchema),
+                ...(tool.outputSchema ? { outputSchema: strip(tool.outputSchema) } : {}),
+            })),
+        };
+    });
+}
 /**
  * One dispatcher: reaches every catalog tool of its lane by name, validates the
  * arguments against that tool's own strict schema, and runs its stored handler.

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.20",
   "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"