@ziggs-ai/ziggs-mcp 0.16.0 → 0.17.1

package/dist/config.d.ts

@@ -10,6 +10,26 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_AGENT_ID: z.ZodOptional<z.ZodString>;
     /** Human user id for payer-side proposals — defaults the payer on propose/publish tools. */
     ZIGGS_OWNER_USER_ID: z.ZodOptional<z.ZodString>;
+    /**
+     * The lane this server's calls belong to — a chat id, or `agrn-<agreementId>`.
+     * Sent as `X-Ziggs-Lane` on every fenced call. Unset means the agent acts for
+     * itself, which is right for a person who configured this server with their
+     * own key, and wrong for a delegate that has been hired: that one holds
+     * grants its CUSTOMER gave, and the server refuses those to a wake that
+     * states no lane.
+     */
+    ZIGGS_LANE_ID: z.ZodOptional<z.ZodString>;
+    /**
+     * Pins this server's inbox host identity (`X-Ziggs-Instance`).
+     *
+     * One host owns an agent's inbox and a second is refused for 330 seconds, so
+     * a stdio server that a SCHEDULER respawns per run — the NanoClaw
+     * one-minute task starting `npx @ziggs-ai/ziggs-mcp` — is a new host every
+     * run and is refused by the previous run's lease. Set this to the same value
+     * on every run and they are one host. A server that stays up needs nothing:
+     * its process is its host.
+     */
+    ZIGGS_INSTANCE_ID: z.ZodOptional<z.ZodString>;
     /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.ZodOptional<z.ZodString>;
     /**
@@ -25,6 +45,8 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_WEB_URL?: string | undefined;
     ZIGGS_AGENT_ID?: string | undefined;
     ZIGGS_OWNER_USER_ID?: string | undefined;
+    ZIGGS_LANE_ID?: string | undefined;
+    ZIGGS_INSTANCE_ID?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }, {
@@ -34,6 +56,8 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_WEB_URL?: string | undefined;
     ZIGGS_AGENT_ID?: string | undefined;
     ZIGGS_OWNER_USER_ID?: string | undefined;
+    ZIGGS_LANE_ID?: string | undefined;
+    ZIGGS_INSTANCE_ID?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
     ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }>;

package/dist/config.js

@@ -12,6 +12,26 @@ const envSchema = z.object({
     ZIGGS_AGENT_ID: z.string().optional(),
     /** Human user id for payer-side proposals — defaults the payer on propose/publish tools. */
     ZIGGS_OWNER_USER_ID: z.string().optional(),
+    /**
+     * The lane this server's calls belong to — a chat id, or `agrn-<agreementId>`.
+     * Sent as `X-Ziggs-Lane` on every fenced call. Unset means the agent acts for
+     * itself, which is right for a person who configured this server with their
+     * own key, and wrong for a delegate that has been hired: that one holds
+     * grants its CUSTOMER gave, and the server refuses those to a wake that
+     * states no lane.
+     */
+    ZIGGS_LANE_ID: z.string().optional(),
+    /**
+     * Pins this server's inbox host identity (`X-Ziggs-Instance`).
+     *
+     * One host owns an agent's inbox and a second is refused for 330 seconds, so
+     * a stdio server that a SCHEDULER respawns per run — the NanoClaw
+     * one-minute task starting `npx @ziggs-ai/ziggs-mcp` — is a new host every
+     * run and is refused by the previous run's lease. Set this to the same value
+     * on every run and they are one host. A server that stays up needs nothing:
+     * its process is its host.
+     */
+    ZIGGS_INSTANCE_ID: z.string().optional(),
     /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.string().optional(),
     /**
@@ -37,6 +57,8 @@ export function loadConfig() {
         ZIGGS_OPERATOR_KEY: process.env.ZIGGS_OPERATOR_KEY,
         ZIGGS_AGENT_ID: process.env.ZIGGS_AGENT_ID,
         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_MCP_DEBUG: process.env.ZIGGS_MCP_DEBUG,
         ZIGGS_MCP_CORE_ONLY: process.env.ZIGGS_MCP_CORE_ONLY,
     };

package/dist/connectionCreds.d.ts

@@ -1,8 +1,16 @@
 import { type Creds } from '@ziggs-ai/api-client';
 import type { ZiggsMcpConfig } from './config.js';
 export declare function parseBearerAuthorization(header: string | string[] | undefined): string;
-/** Per-connection credentials from HTTP Authorization. */
-export declare function connectionFromBearer(bearer: string, httpBaseUrl: string, ownerUserId?: string): {
+/**
+ * Per-connection credentials from HTTP Authorization.
+ *
+ * `laneId` is the wake's lane, read off `X-Ziggs-Lane` by the caller that
+ * mounts this server, exactly as `ownerUserId` is read off its own header. A
+ * connection that states none is fenced to the agent's own estate — right for
+ * 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): {
     creds: Creds;
     cfg: ZiggsMcpConfig;
 };

package/dist/connectionCreds.js

@@ -1,4 +1,4 @@
-import { configureApiClient } from '@ziggs-ai/api-client';
+import { configureApiClient, mcpConnectionIdentity, } from '@ziggs-ai/api-client';
 import { MINT_KEY_HELP, decodeOperatorKeyClaims, isDirectoryBoarded, resolveDelegateAgentId, } from './operatorKey.js';
 export function parseBearerAuthorization(header) {
     const raw = Array.isArray(header) ? header[0] : header;
@@ -11,8 +11,16 @@ export function parseBearerAuthorization(header) {
     }
     return token;
 }
-/** Per-connection credentials from HTTP Authorization. */
-export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
+/**
+ * Per-connection credentials from HTTP Authorization.
+ *
+ * `laneId` is the wake's lane, read off `X-Ziggs-Lane` by the caller that
+ * mounts this server, exactly as `ownerUserId` is read off its own header. A
+ * connection that states none is fenced to the agent's own estate — right for
+ * a person who pasted their key, wrong for a delegate holding grants its
+ * customer gave.
+ */
+export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId, laneId) {
     const resolvedAgentId = resolveDelegateAgentId(bearer, undefined);
     if (httpBaseUrl) {
         process.env.HTTP_URL = httpBaseUrl;
@@ -26,6 +34,7 @@ export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
         HTTP_URL: httpBaseUrl,
         ZIGGS_AGENT_ID: undefined,
         ZIGGS_OWNER_USER_ID: ownerUserId,
+        ZIGGS_LANE_ID: laneId,
         resolvedAgentId,
         debugTools: false,
         coreOnly: false,
@@ -35,8 +44,24 @@ export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
         // ZiggsMcpConfig.directConnection.
         directConnection: !isDirectoryBoarded(decodeOperatorKeyClaims(bearer)),
     };
+    /**
+     * The inbox host is this CONNECTION, not the process serving it.
+     *
+     * This server also runs inside the API process, which serves every connected
+     * assistant and gets a new identity on every deploy. Stamping that made all
+     * of them one host and moved it under all of them at once, so a hosted
+     * `ziggs_inbox` read answered 409 for up to 330 seconds after each restart.
+     * The key is what stays put across both. Undefined only for a credential
+     * carrying no `keyId`, which then falls back to the process default.
+     */
+    const instanceId = mcpConnectionIdentity(bearer);
     return {
-        creds: { operatorKey: bearer, agentId: resolvedAgentId },
+        creds: {
+            operatorKey: bearer,
+            agentId: resolvedAgentId,
+            ...(laneId ? { laneId } : {}),
+            ...(instanceId ? { instanceId } : {}),
+        },
         cfg,
     };
 }

package/dist/creds.js

@@ -2,5 +2,13 @@ export function credsFromConfig(cfg) {
     return {
         operatorKey: cfg.ZIGGS_OPERATOR_KEY,
         agentId: cfg.resolvedAgentId,
+        // The lane, so a hired delegate can spend the grants its customer gave it.
+        // Every client in this package reads it off `Creds`, so leaving it unset
+        // here silently fences all of them to the agent's own estate.
+        ...(cfg.ZIGGS_LANE_ID ? { laneId: cfg.ZIGGS_LANE_ID } : {}),
+        // Unset means this process is the host, which is right for a server that
+        // 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 } : {}),
     };
 }

package/dist/mcpConnectionTools.js

@@ -8,7 +8,7 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectionsClient, getBackendUrl, } from '@ziggs-ai/api-client';
+import { ConnectionsClient, getBackendUrl, laneHeader, } from '@ziggs-ai/api-client';
 export function resolveMcpGatewayTarget(opts) {
     if (!opts.connectionId)
         throw new Error('connectionId is required');
@@ -25,7 +25,8 @@ export function resolveMcpGatewayTarget(opts) {
             authorization: `Bearer ${opts.operatorKey}`,
             'x-agent-id': opts.agentId,
             'x-grant-id': opts.grantId,
-            ...(opts.laneId ? { 'x-ziggs-lane': opts.laneId } : {}),
+            // one helper for the lane, shared with every other door.
+            ...laneHeader(opts.laneId),
         },
     };
 }

package/dist/tools.js

@@ -68,7 +68,7 @@ function loadSessionReads(creds) {
     // #4 — tasks and payments are independent; overlap them.
     return Promise.allSettled([
         listTasks({ state: 'active', limit: 20 }, creds),
-        new PaymentsClient(creds.operatorKey, creds.agentId).approvals({
+        new PaymentsClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).approvals({
             status: 'pending',
         }),
     ]);
@@ -207,7 +207,7 @@ function registerConnectionTools(server, creds, cfg) {
             ? 'How to use a row: provider "mcp" → ziggs_mcp_tools_list / ziggs_mcp_tool_call; named connectors (github, jira, …) → ziggs_connection_proxy.'
             : 'Rows are readable here but not callable over this connection: using a connection (an MCP server or a named connector such as github or jira) is only on a self-configured Ziggs MCP connection with an operator key.'), {}, readOnly('List connections you can use'), async () => {
         try {
-            const connections = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
+            const connections = await new ConnectionsClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).listForHolder();
             return textResult({ connections });
         }
         catch (e) {
@@ -321,7 +321,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 let snapshot = null;
                 const firstChatId = chats[0]?.chatId;
                 if (firstChatId) {
-                    const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+                    const client = new ContextReadClient(creds.operatorKey, creds.agentId, undefined, firstChatId);
                     snapshot = await client.snapshot(firstChatId, { maxMessages: 5 });
                 }
                 return textResult({
@@ -345,7 +345,11 @@ export function registerZiggsTools(server, creds, cfg) {
             .describe('Optional grant id when reading under a context grant'),
     }, readOnly('Catch up on a chat'), async ({ chatId, maxMessages, contextGrantId }) => {
         try {
-            const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+            // The chat being read IS the lane: a snapshot of someone else's room
+            // is a call inside that engagement, and stating it is what lets a hired
+            // delegate read the room it was hired into. Falls back to the
+            // connection's lane when no chat is named.
+            const client = new ContextReadClient(creds.operatorKey, creds.agentId, undefined, chatId || creds.laneId);
             const result = await client.snapshot(chatId, {
                 maxMessages,
                 contextGrantId,
@@ -601,7 +605,9 @@ export function registerZiggsTools(server, creds, cfg) {
             .describe('Long-poll: hold up to this many seconds (server-clamped, ~110 max) and return as soon as something new arrives — same response shape, no busy re-polling. Omit for an immediate snapshot.'),
     }, readOnly('Check your inbox'), async ({ ack, handledResourceIds, waitSeconds }) => {
         try {
-            const client = new InboxClient(creds.operatorKey, creds.agentId);
+            // 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);
             // Ack-before-fetch is load-bearing; everything else is independent of
             // the envelope until we know whether there are deliveries to tag.
             const acked = ack
@@ -633,7 +639,7 @@ export function registerZiggsTools(server, creds, cfg) {
                     // own held context grants. Best-effort — the inbox still works
                     // untagged. All pages of live grants only (GET /grants also returns
                     // expired/revoked and paginates).
-                    reach = await new GrantsClient(creds.operatorKey, creds.agentId).listAllGrants({
+                    reach = await new GrantsClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).listAllGrants({
                         // Every context scope kind — a literal subset here is how the CLI
                         // silently dropped a whole kind when `artifact` was added.
                         scopeKind: [...CONTEXT_GRANT_SCOPE_KINDS],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.16.0",
+    "@ziggs-ai/api-client": "0.17.1",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"