@ziggs-ai/ziggs-mcp 0.36.1 → 0.36.3

package/dist/config.d.ts

@@ -30,6 +30,17 @@ declare const envSchema: z.ZodObject<{
      * its process is its host.
      */
     ZIGGS_INSTANCE_ID: z.ZodOptional<z.ZodString>;
+    /**
+     * Workspaces this window reads, comma-separated org ids. Sent as
+     * `X-Ziggs-Workspaces`. Unset reads everything the assistant may read.
+     * A hosted connection sets the header on the MCP request instead; this
+     * process serves every window, so it must not take the list from the env.
+     */
+    ZIGGS_WORKSPACES: z.ZodOptional<z.ZodString>;
+    /** Label on the assistant page, such as "Claude Code". */
+    ZIGGS_APP: z.ZodOptional<z.ZodString>;
+    /** Person-readable window name. Unset becomes the app plus the time. */
+    ZIGGS_SESSION_NAME: z.ZodOptional<z.ZodString>;
     /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.ZodOptional<z.ZodString>;
     /**
@@ -47,6 +58,9 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_OWNER_USER_ID?: string | undefined;
     ZIGGS_LANE_ID?: string | undefined;
     ZIGGS_INSTANCE_ID?: string | undefined;
+    ZIGGS_WORKSPACES?: string | undefined;
+    ZIGGS_APP?: string | undefined;
+    ZIGGS_SESSION_NAME?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }, {
@@ -58,6 +72,9 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_OWNER_USER_ID?: string | undefined;
     ZIGGS_LANE_ID?: string | undefined;
     ZIGGS_INSTANCE_ID?: string | undefined;
+    ZIGGS_WORKSPACES?: string | undefined;
+    ZIGGS_APP?: string | undefined;
+    ZIGGS_SESSION_NAME?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }>;

package/dist/config.js

@@ -32,6 +32,17 @@ const envSchema = z.object({
      * its process is its host.
      */
     ZIGGS_INSTANCE_ID: z.string().optional(),
+    /**
+     * Workspaces this window reads, comma-separated org ids. Sent as
+     * `X-Ziggs-Workspaces`. Unset reads everything the assistant may read.
+     * A hosted connection sets the header on the MCP request instead; this
+     * process serves every window, so it must not take the list from the env.
+     */
+    ZIGGS_WORKSPACES: z.string().optional(),
+    /** Label on the assistant page, such as "Claude Code". */
+    ZIGGS_APP: z.string().optional(),
+    /** Person-readable window name. Unset becomes the app plus the time. */
+    ZIGGS_SESSION_NAME: z.string().optional(),
     /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.string().optional(),
     /**
@@ -59,6 +70,9 @@ export function loadConfig() {
         ZIGGS_OWNER_USER_ID: process.env.ZIGGS_OWNER_USER_ID,
         ZIGGS_LANE_ID: process.env.ZIGGS_LANE_ID,
         ZIGGS_INSTANCE_ID: process.env.ZIGGS_INSTANCE_ID,
+        ZIGGS_WORKSPACES: process.env.ZIGGS_WORKSPACES,
+        ZIGGS_APP: process.env.ZIGGS_APP,
+        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,
     };

package/dist/connectionCreds.d.ts

@@ -10,7 +10,12 @@ export declare function parseBearerAuthorization(header: string | string[] | und
  * a person who pasted their key, wrong for a delegate holding grants its
  * customer gave.
  */
-export declare function connectionFromBearer(bearer: string, httpBaseUrl: string, ownerUserId?: string, laneId?: string): {
+export declare function connectionFromBearer(bearer: string, httpBaseUrl: string, ownerUserId?: string, laneId?: string, session?: {
+    clientSessionId?: string;
+    workspaceIds?: string;
+    app?: string;
+    sessionName?: string;
+}): {
     creds: Creds;
     cfg: ZiggsMcpConfig;
 };

package/dist/connectionCreds.js

@@ -20,7 +20,7 @@ export function parseBearerAuthorization(header) {
  * a person who pasted their key, wrong for a delegate holding grants its
  * customer gave.
  */
-export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId, laneId) {
+export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId, laneId, session) {
     const resolvedAgentId = resolveDelegateAgentId(bearer, undefined);
     if (httpBaseUrl) {
         process.env.HTTP_URL = httpBaseUrl;
@@ -61,6 +61,10 @@ export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId, laneId) {
             agentId: resolvedAgentId,
             ...(laneId ? { laneId } : {}),
             ...(instanceId ? { instanceId } : {}),
+            ...(session?.clientSessionId ? { clientSessionId: session.clientSessionId } : {}),
+            ...(session?.workspaceIds ? { workspaceIds: session.workspaceIds } : {}),
+            ...(session?.app ? { app: session.app } : {}),
+            ...(session?.sessionName ? { sessionName: session.sessionName } : {}),
         },
         cfg,
     };

package/dist/creds.js

@@ -10,5 +10,8 @@ export function credsFromConfig(cfg) {
         // stays up and wrong for one a scheduler respawns per run — that one pins
         // ZIGGS_INSTANCE_ID so every run is the same host.
         ...(cfg.ZIGGS_INSTANCE_ID ? { instanceId: cfg.ZIGGS_INSTANCE_ID } : {}),
+        ...(cfg.ZIGGS_WORKSPACES ? { workspaceIds: cfg.ZIGGS_WORKSPACES } : {}),
+        ...(cfg.ZIGGS_APP ? { app: cfg.ZIGGS_APP } : {}),
+        ...(cfg.ZIGGS_SESSION_NAME ? { sessionName: cfg.ZIGGS_SESSION_NAME } : {}),
     };
 }

package/dist/inboxCompact.d.ts

@@ -17,7 +17,10 @@
  *   which `ziggs_auth_status` returns in full;
  * - a read step's `why` that only restates its tool and args, and the ack
  *   step's long one, whose ids are the step's own args;
- * - an `outOfReach` entry's scope and remedy, which its delivery row carries.
+ * - an `outOfReach` entry's scope and remedy, which its delivery row carries;
+ * - `sessionCardHint` ("the card is not in this response") when the card is.
+ *   Both doors assemble the session start from the long-poll result plus the
+ *   card, and the long-poll half's hint said the opposite of what followed.
  *
  * Acknowledgement stays exact: every `ackTo` — the envelope's, each row's and
  * the ack step's — is passed through byte for byte.

package/dist/inboxCompact.js

@@ -17,7 +17,10 @@
  *   which `ziggs_auth_status` returns in full;
  * - a read step's `why` that only restates its tool and args, and the ack
  *   step's long one, whose ids are the step's own args;
- * - an `outOfReach` entry's scope and remedy, which its delivery row carries.
+ * - an `outOfReach` entry's scope and remedy, which its delivery row carries;
+ * - `sessionCardHint` ("the card is not in this response") when the card is.
+ *   Both doors assemble the session start from the long-poll result plus the
+ *   card, and the long-poll half's hint said the opposite of what followed.
  *
  * Acknowledgement stays exact: every `ackTo` — the envelope's, each row's and
  * the ack step's — is passed through byte for byte.
@@ -92,6 +95,8 @@ export function compactInboxResult(result) {
             if (isRecord(s))
                 kindOfParty.set(String(s.partyId), s.partyKind);
     const out = { ...result };
+    if (typeof result.sessionChatCard === 'string' && result.sessionChatCard)
+        delete out.sessionCardHint;
     if (Array.isArray(result.deliveries)) {
         const usual = usualPartyOf(result.deliveries);
         if (usual !== undefined)
@@ -149,13 +154,16 @@ export function windowNote(deliveries, selfAgentIds, outOfReach) {
     const mine = rows.filter((d) => selfAgentIds.includes(String(d.assigneeId))).length;
     const person = rows.filter((d) => !d.assigneeId && d.needsHuman === true).length;
     const others = rows.filter((d) => d.assigneeId && !selfAgentIds.includes(String(d.assigneeId))).length;
+    // Rows nobody is asked to handle (no assignee, not the person's) are context.
+    const context = rows.length - mine - person - others;
     const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
     const parts = [n(mine, 'is assigned to you', 'are assigned to you')];
     if (person)
         parts.push(`${person} ${person === 1 ? 'needs' : 'need'} your person`);
     if (others)
         parts.push(`${others} ${others === 1 ? 'is' : 'are'} for other assistants`);
-    if (outOfReach)
-        parts.push(`${outOfReach} out of reach`);
-    return `Those counts are decisions and tasks, not messages. This window has ${n(rows.length, 'delivery', 'deliveries')}: ${parts.join(', ')}.`;
+    if (context)
+        parts.push(`${context} ${context === 1 ? 'is' : 'are'} context`);
+    const reach = outOfReach ? ` ${outOfReach} of them ${outOfReach === 1 ? 'is' : 'are'} out of reach.` : '';
+    return `Those counts are decisions and tasks, not messages. This window has ${n(rows.length, 'delivery', 'deliveries')}: ${parts.join(', ')}.${reach}`;
 }

package/dist/protocol/connectText.d.ts

@@ -18,4 +18,10 @@
  * .cursorrules, which a client loads when it chooses to.
  */
 export type ConnectDoor = 'directory' | 'compact';
+/**
+ * The rules a directory client must see even when it never shows the model
+ * the server's instructions (claude.ai does not). Carried on the session-start
+ * inbox read, the first call an agent makes, in the same words as above.
+ */
+export declare function sessionRules(door: ConnectDoor): string[];
 export declare function renderConnectText(door: ConnectDoor): string;

package/dist/protocol/connectText.js

@@ -32,6 +32,14 @@ const RULES = [
     'A send refused with WORK_SELECTION_REQUIRED lists choices: set conversationAgreementId to one of them; never guess.',
     'Agreement and task writes can reserve or settle points. After an uncertain write, read the record, then retry with the same idempotencyKey.',
 ];
+/**
+ * The rules a directory client must see even when it never shows the model
+ * the server's instructions (claude.ai does not). Carried on the session-start
+ * inbox read, the first call an agent makes, in the same words as above.
+ */
+export function sessionRules(door) {
+    return [DATA, INBOX[door]];
+}
 const CATALOG = 'Only the everyday tools are loaded. ziggs_tools lists the rest; call them through ziggs_tool_read or ziggs_tool_write.';
 export function renderConnectText(door) {
     return [

package/dist/strictParams.d.ts

@@ -13,6 +13,8 @@ import type { TitledAnnotations } from './toolAnnotations.js';
  * against. So every tool schema is built strict, and the rejection names both
  * the offending key and the params the tool actually accepts.
  */
+/** The workspace parameter the router adds to a tool that acts in one. */
+export declare const WORKSPACE_PARAM = "Workspace orgId, when more than one fits.";
 export type StrictShape<S extends ZodRawShape> = ZodObject<S, 'strict', z.ZodTypeAny>;
 export declare function strictParams<S extends ZodRawShape>(toolName: string, shape: S): StrictShape<S>;
 /**

package/dist/strictParams.js

@@ -4,6 +4,20 @@ import { workspaceRouter } from './workspaceRouting.js';
 import { mcpDescription } from '@ziggs-ai/api-client';
 import { z } from 'zod';
 import { recordCatalogEntry } from './toolCatalog.js';
+/**
+ * registering a tool with a plain `ZodRawShape` lets the MCP SDK
+ * wrap it in a default `z.object()`, which *strips* unknown keys instead of
+ * rejecting them. A misspelled param (`nweChat` for `newChat`) was therefore
+ * dropped and the call ran anyway, reporting success for the opposite of what
+ * the caller asked for.
+ *
+ * A human typing that into a form gets a red field; an agent got silence, and
+ * silence reads as confirmation — there was no feedback loop to self-correct
+ * against. So every tool schema is built strict, and the rejection names both
+ * the offending key and the params the tool actually accepts.
+ */
+/** The workspace parameter the router adds to a tool that acts in one. */
+export const WORKSPACE_PARAM = 'Workspace orgId, when more than one fits.';
 export function strictParams(toolName, shape) {
     const accepted = Object.keys(shape);
     return z
@@ -58,8 +72,11 @@ export function registerStrictTool(server, name, shape, annotations, cb) {
     const router = workspaceRouter(server);
     const nativeOrgId = !!shape.orgId;
     if (router) {
+        // Said once per tool and kept short: it rides on most of the surface. Which
+        // workspace to use is taught where it matters — the refusal for a call that
+        // needs one lists the choices and says to ask the person.
         if (router.acceptsWorkspace(name))
-            shape = { ...shape, orgId: shape.orgId?.optional() ?? z.string().optional().describe('Workspace named by your human. Required for new actions when more than one workspace fits.') };
+            shape = { ...shape, orgId: shape.orgId?.optional() ?? z.string().optional().describe(WORKSPACE_PARAM) };
         cb = router.wrap(name, annotations.readOnlyHint === true, cb, nativeOrgId);
     }
     const routed = cb;

package/dist/tools.js

@@ -7,6 +7,7 @@ import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { compactTextResult, windowNote } from './inboxCompact.js';
+import { sessionRules } from './protocol/connectText.js';
 import { agreementAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
 import { resolveMcpConnectionTarget, withMcpGatewayClient, } from './mcpConnectionTools.js';
 import { readOnly, write, destructive } from './toolAnnotations.js';
@@ -236,6 +237,14 @@ function registerConnectionTools(server, creds, cfg) {
     });
     registerCapability(server, requestConnectionCapability, creds);
 }
+function inboxFor(creds) {
+    return new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId, {
+        clientSessionId: creds.clientSessionId,
+        workspaceIds: creds.workspaceIds,
+        app: creds.app,
+        sessionName: creds.sessionName,
+    });
+}
 export function registerZiggsTools(server, creds, cfg) {
     // A binding check and nothing else. This used to also report the
     // pending/active counts and point at a separate decisions tool for the card,
@@ -547,7 +556,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .describe('Hold up to this many seconds (the server clamps a hold at about 110) and return as soon as assigned mail exists. Omit for an immediate count. Still does not take the lease. To wait for a reply your person asked about, call ziggs_inbox with waitSeconds: 55 instead, since only the full read returns the mail.'),
     }, readOnly('Peek inbox count without taking the mailbox'), async ({ waitSeconds }) => {
         try {
-            const client = new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId);
+            const client = inboxFor(creds);
             const [bindingSettled, readsSettled, peekSettled] = await Promise.allSettled([
                 loadSessionBinding(creds, cfg),
                 loadSessionReads(creds),
@@ -608,7 +617,7 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             // Unset on stdio: that process IS the host, and a scheduler that
             // respawns it per run pins ZIGGS_INSTANCE_ID instead.
-            const client = new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId);
+            const client = inboxFor(creds);
             // A cold call is the session start, and its extra reads — the binding
             // and the active-task rows — take nothing from the envelope. Started
             // here, they ride the same wave as the inbox fetch
@@ -676,6 +685,9 @@ export function registerZiggsTools(server, creds, cfg) {
                 ...news,
                 session,
                 ...actions,
+                // A directory host may never show the model the server's
+                // instructions; the session-start read is the one place it looks.
+                ...(isDirectorySurface(server) ? { rules: sessionRules('directory') } : {}),
                 ...(note && typeof actions.notice === 'string'
                     ? { notice: `${actions.notice} ${note}` }
                     : {}),
@@ -703,7 +715,7 @@ export function registerZiggsTools(server, creds, cfg) {
     if (isDirectorySurface(server)) {
         registerStrictTool(server, 'ziggs_inbox_claim', {}, destructive('Claim the inbox for this worker'), async () => {
             try {
-                const client = new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId);
+                const client = inboxFor(creds);
                 return compactTextResult(await client.getInbox());
             }
             catch (e) {
@@ -728,7 +740,7 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             // Same host identity as the read: acking renews an owner, and only a
             // read acquires one.
-            const client = new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId);
+            const client = inboxFor(creds);
             const acked = await client.ackOrTakeHost(ack, {
                 handledResourceIds: handledResourceIds ?? [],
             });

package/dist/workspaceRouting.js

@@ -3,6 +3,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { AssistantConnectionClient, withAssistantRequest, decodeOperatorKeyClaims, } from '@ziggs-ai/api-client';
 import { formatInboxToolResult } from './inboxToolResult.js';
 import { compactTextResult, windowNote } from './inboxCompact.js';
+import { sessionRules } from './protocol/connectText.js';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin } from './pendingDecisions.js';
 const routers = new WeakMap();
 /** The catalog and its dispatchers: they reach other tools, which route themselves. */
@@ -207,6 +208,7 @@ export class WorkspaceRouter {
                 return compactTextResult({
                     ...news,
                     ...pending,
+                    ...(name === 'ziggs_inbox' && args.waitSeconds == null ? { rules: sessionRules('directory') } : {}),
                     ...(note && typeof pending.notice === 'string' ? { notice: `${pending.notice} ${note}` } : {}),
                     session: { workspaces },
                     instruction: `Assigned to any of agentIds is your work. ${ASK_YOUR_HUMAN}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.36.1",
+  "version": "0.36.3",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "rm -rf dist && npm run build",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
@@ -39,7 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.36.0",
+    "@ziggs-ai/api-client": "0.36.1",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"