@ziggs-ai/ziggs-mcp 0.31.0 → 0.32.1

package/dist/inboxToolResult.d.ts

@@ -116,6 +116,7 @@ self?: DecisionSelfIds): Record<string, unknown>;
 /** The caller's own ids, for the rows this result marks as the caller's. */
 export interface DecisionSelfIds {
     agentId: string;
+    agentIds?: string[];
     ownerUserId?: string | null;
 }
 export {};

package/dist/inboxToolResult.js

@@ -108,7 +108,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
      * as its own, which is the old behaviour: the plan then holds one list and
      * the ack rides on all of it fitting, exactly as before.
      */
-    const isMine = (d) => self.agentId === '' || d.assigneeId === self.agentId;
+    const isMine = (d) => self.agentIds?.includes(d.assigneeId ?? '') || (!self.agentIds && self.agentId === '') || d.assigneeId === self.agentId;
     // Reads — one call per place mail actually landed. The delivery names the
     // chat, agreement or task directly, so nothing has to be inferred from a scope.
     //
@@ -211,6 +211,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // is safe, because the newer tail is past ackTo.
     const ack = planInboxAck(inbox, {
         ownAgentId: self.agentId || undefined,
+        ownAgentIds: self.agentIds,
     });
     // One checkpoint ack, after the FIRST assigned step.
     //
@@ -233,6 +234,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const checkpoint = settledFirst.length > 0
         ? planPartialInboxAck(inbox, new Set(settledFirst), {
             ownAgentId: self.agentId || undefined,
+            ownAgentIds: self.agentIds,
         })
         : null;
     // Never the same mark as the final ack — that is a wasted call and a second

package/dist/mcpConnectionTools.js

@@ -1,3 +1,4 @@
+import { assistantRequestHeaders, decodeOperatorKeyClaims } from '@ziggs-ai/api-client';
 /**
  * Call a brokered MCP connection from the ziggs-mcp surface.
  *
@@ -16,13 +17,14 @@ export function resolveMcpGatewayTarget(opts) {
         throw new Error('grantId is required');
     if (!opts.operatorKey)
         throw new Error('operatorKey is required');
-    if (!opts.agentId)
+    if (!opts.agentId && !decodeOperatorKeyClaims(opts.operatorKey)?.connectionClientId)
         throw new Error('agentId is required');
     const baseUrl = (opts.baseUrl || getBackendUrl()).replace(/\/$/, '');
     return {
         url: new URL(`${baseUrl}/connections/${encodeURIComponent(opts.connectionId)}/mcp`),
         headers: {
             authorization: `Bearer ${opts.operatorKey}`,
+            ...assistantRequestHeaders(),
             'x-agent-id': opts.agentId,
             'x-grant-id': opts.grantId,
             // one helper for the lane, shared with every other door.
@@ -35,7 +37,7 @@ export async function resolveMcpConnectionTarget(creds, connectionId, grantId) {
         return { connectionId, grantId };
     if (!creds.operatorKey)
         throw new Error('operatorKey is required');
-    if (!creds.agentId)
+    if (!creds.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
         throw new Error('agentId is required');
     // The lane matters here too: since the grant list answers for the party the
     // wake acts for, a lane-less list comes back spanning every customer this
@@ -84,7 +86,7 @@ export function setMcpGatewayRunnerForTests(runner) {
     gatewayRunner = runner ?? defaultRunner;
 }
 export async function withMcpGatewayClient(creds, connectionId, grantId, run) {
-    if (!creds.operatorKey || !creds.agentId) {
+    if (!creds.operatorKey || (!creds.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)) {
         throw new Error('operatorKey and agentId are required');
     }
     const target = resolveMcpGatewayTarget({

package/dist/operatorKey.js

@@ -18,6 +18,8 @@ export function resolveDelegateAgentId(operatorKey, envAgentId) {
     if (isOperatorKeyExpired(claims)) {
         throw new Error(`ziggs-mcp: operator key expired (keyId=${claims?.keyId ?? 'unknown'}). ${MINT_KEY_HELP}`);
     }
+    if (claims?.connectionClientId)
+        return '';
     const bound = claims?.boundAgentId?.trim() || '';
     const env = envAgentId?.trim() || '';
     if (bound && env && bound !== env) {

package/dist/pendingDecisions.js

@@ -1,6 +1,6 @@
 import { agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
 export { resolveWebAppOrigin, agreementAppUrl, agreementsListAppUrl, connectionsSettingsAppUrl, walletAppUrl } from '@ziggs-ai/api-client';
-import { decisionWords, partySideIds, } from '@ziggs-ai/api-client';
+import { decisionWords, partySideIds, speakableActor, } from '@ziggs-ai/api-client';
 /**
  * The artifact a decision row is about, when the row names it. Today's row
  * does not (the artifact lives on the agreement's grant request), so this
@@ -53,7 +53,7 @@ export function buildDecidedForMeItems(inbox) {
         items.push({
             agreementId,
             outcome: words.outcome,
-            by: d.actorId ?? null,
+            by: speakableActor(d.actorId),
             at: d.ts,
             sentence: words.sentence,
             ...(artifactId ? { artifactId } : {}),

package/dist/protocol/delegateProtocol.d.ts

@@ -23,7 +23,7 @@ export declare const PROTOCOL: {
      */
     readonly surface: "Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=[\"<name>\"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.";
     /** The working loop, as the `ziggs_inbox` description phrases it. */
-    readonly loop: "Flow: inbox → read → act → ack.";
+    readonly loop: "Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.";
     /**
      * Watermark discipline — reading is side-effect-free; ack is explicit.
      *
@@ -31,7 +31,7 @@ export declare const PROTOCOL: {
      * to make with them, so it teaches at the moment it matters; pre-empting it
      * here would cost context on every other turn.
      */
-    readonly ack: "Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.";
+    readonly ack: "Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.";
     readonly neverRewind: "Never rewind an ack to an older value.";
     /** Tasks are the unit of work. */
     readonly task: "Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).";

package/dist/protocol/delegateProtocol.js

@@ -23,7 +23,7 @@ export const PROTOCOL = {
      */
     surface: 'Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.',
     /** The working loop, as the `ziggs_inbox` description phrases it. */
-    loop: 'Flow: inbox → read → act → ack.',
+    loop: "Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.",
     /**
      * Watermark discipline — reading is side-effect-free; ack is explicit.
      *
@@ -31,7 +31,7 @@ export const PROTOCOL = {
      * to make with them, so it teaches at the moment it matters; pre-empting it
      * here would cost context on every other turn.
      */
-    ack: 'Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.',
+    ack: 'Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.',
     neverRewind: 'Never rewind an ack to an older value.',
     /** Tasks are the unit of work. */
     task: 'Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).',

package/dist/server.js

@@ -1,7 +1,8 @@
+import { installWorkspaceRouting } from './workspaceRouting.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createRequire } from 'node:module';
-import { InboxClient } from '@ziggs-ai/api-client';
+import { AssistantConnectionClient, decodeOperatorKeyClaims, InboxClient } from '@ziggs-ai/api-client';
 import { loadConfig } from './config.js';
 import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
@@ -23,7 +24,8 @@ export function createZiggsMcpServer(creds, cfg) {
         // since both build the server through this factory.
         instructions: renderInstructions(),
     });
-    registerZiggsTools(server, creds, cfg);
+    const routedCreds = installWorkspaceRouting(server, creds);
+    registerZiggsTools(server, routedCreds, cfg);
     // Decide what a caller loads natively and what it reaches through
     // the catalog. Runs after registration because the catalog is built by it.
     applySurfacePolicy(server, { pickTool: backendToolPick(creds) });
@@ -32,6 +34,10 @@ export function createZiggsMcpServer(creds, cfg) {
 /** Drop this process's inbox host. Best-effort — shutdown must not fail on it. */
 export async function releaseStdioInboxHost(creds) {
     try {
+        if (decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId) {
+            await new AssistantConnectionClient(creds).request('inbox/release', {});
+            return;
+        }
         await new InboxClient(creds.operatorKey, creds.agentId, undefined, creds.instanceId).releaseHost();
     }
     catch {

package/dist/strictParams.js

@@ -1,3 +1,4 @@
+import { workspaceRouter } from './workspaceRouting.js';
 import { z } from 'zod';
 import { recordCatalogEntry } from './toolCatalog.js';
 export function strictParams(toolName, shape) {
@@ -43,6 +44,13 @@ export function registerStrictTool(server, name, description, shape, annotations
     // object, and the describe path lowers it to JSON Schema. Rebuilding it from
     // the shape at each of those calls produced an object that had not changed
     // since registration.
+    const router = workspaceRouter(server);
+    const nativeOrgId = !!shape.orgId;
+    if (router) {
+        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.') };
+        cb = router.wrap(name, annotations.readOnlyHint === true, cb, nativeOrgId);
+    }
     const params = strictParams(name, shape);
     const handle = server.registerTool(name, {
         title: annotations.title,

package/dist/toolError.d.ts

@@ -9,6 +9,13 @@ export interface ToolErrorShape {
     code: string;
     message: string;
     hint?: string;
+    /**
+     * What the caller may pick from, when the refusal is a choice: the
+     * agreements of WORK_SELECTION_REQUIRED, the workspaces of
+     * WORKSPACE_SELECTION_REQUIRED. Carried through verbatim so an assistant can
+     * ask its human instead of re-reading the message.
+     */
+    choices?: unknown[];
 }
 /**
  * Classify a thrown client error (or a plain string this layer raised) into a
@@ -23,6 +30,9 @@ export declare function classifyToolError(input: unknown): ToolErrorShape;
  * A plain string is still accepted for refusals this layer raises on its own.
  */
 export declare function toolError(input: unknown): {
+    structuredContent: {
+        error: ToolErrorShape;
+    };
     content: {
         type: "text";
         text: string;

package/dist/toolError.js

@@ -62,10 +62,10 @@ function codeForStatus(status) {
  */
 function thrownFields(err) {
     if (typeof err === 'string') {
-        return { message: err, status: null, code: null };
+        return { message: err, status: null, code: null, choices: null };
     }
     if (typeof err !== 'object' || err === null) {
-        return { message: String(err), status: null, code: null };
+        return { message: String(err), status: null, code: null, choices: null };
     }
     const o = err;
     const status = typeof o.status === 'number' && o.status >= 100 && o.status < 600
@@ -73,13 +73,32 @@ function thrownFields(err) {
         : null;
     const code = typeof o.code === 'string' && o.code ? o.code : null;
     const message = typeof o.message === 'string' && o.message ? o.message : String(err);
-    return { message, status, code };
+    return { message, status, code, choices: choicesIn(o.body) };
+}
+/** The `choices` list of a refusal body, when the server sent one. */
+function choicesIn(body) {
+    if (typeof body !== 'string' || !body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        return Array.isArray(parsed?.choices) && parsed.choices.length
+            ? parsed.choices
+            : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Classify a thrown client error (or a plain string this layer raised) into a
  * stable MCP shape.
  */
 export function classifyToolError(input) {
+    const shape = classify(input);
+    const { choices } = thrownFields(input);
+    return choices ? { ...shape, choices } : shape;
+}
+function classify(input) {
     const { message, status, code: machineCode } = thrownFields(input);
     if (machineCode === 'AGENT_LACKS_HUMAN_AUTHORITY') {
         return {
@@ -132,6 +151,9 @@ export function classifyToolError(input) {
 export function toolError(input) {
     const shape = classifyToolError(input);
     return {
+        // Keep the native structured result identical to the text payload so hosts
+        // do not need to infer an error category from isError or parse its prose.
+        structuredContent: { error: shape },
         content: [
             { type: 'text', text: JSON.stringify({ error: shape }, null, 2) },
         ],

package/dist/tools.js

@@ -130,7 +130,6 @@ async function loadSessionBinding(creds, cfg) {
     let actingOrgName = null;
     let actingOrgKind = null;
     let connected = false;
-    let switchOrgHint = null;
     try {
         // Claude OAuth delegates use self-hire access; hosted /
         // fleet impersonation must not hit that route (it lies / throws).
@@ -139,14 +138,9 @@ async function loadSessionBinding(creds, cfg) {
         actingOrgName = typeof access.orgName === 'string' ? access.orgName : null;
         actingOrgKind = typeof access.orgKind === 'string' ? access.orgKind : null;
         connected = access.connected === true;
-        switchOrgHint =
-            typeof access.switchOrgHint === 'string' ? access.switchOrgHint : null;
     }
     catch {
         // never leak raw fetch/network text into a hint.
-        switchOrgHint = isDelegate
-            ? 'Could not load runtime org — reconnect MCP OAuth and retry.'
-            : 'Could not load runtime org — check ZIGGS_OPERATOR_KEY / ZIGGS_AGENT_ID and API reachability.';
     }
     return {
         agentId: creds.agentId,
@@ -160,7 +154,6 @@ async function loadSessionBinding(creds, cfg) {
         orgId: actingOrgId,
         orgName: actingOrgName,
         orgKind: actingOrgKind,
-        orgBinding: actingOrgKind === 'personal' || !actingOrgId ? 'personal' : 'team',
         orgBindingNote: !connected
             ? isDelegate
                 ? 'Not connected — complete MCP OAuth consent first, then re-check actingOrgId here.'
@@ -170,12 +163,8 @@ async function loadSessionBinding(creds, cfg) {
                     ? `This MCP session acts in **${actingOrgName}** (${actingOrgId}). Runtime org comes from server-side delegate + self-hire — not the OAuth JWT.`
                     : `This MCP session acts in **${actingOrgName}** (${actingOrgId}). Runtime org is the hosted agent's home / key workspace.`
                 : isDelegate
-                    ? 'Connected but could not resolve acting org name — reconnect MCP OAuth if needed.'
+                    ? 'Could not read the workspace name. Retry the live workspace read.'
                     : 'Connected but could not resolve acting org name — check the agent home org on the key.',
-        switchOrgHint: switchOrgHint ??
-            (isDelegate
-                ? 'Org is fixed at OAuth consent. Reconnect MCP OAuth and pick the target org on the consent screen to act elsewhere.'
-                : 'Hosted agent session — acting org is the agent home / key workspace, not MCP OAuth consent.'),
         apiBase: getBackendUrl(),
         webAppOrigin: resolveWebAppOrigin(cfg.ZIGGS_WEB_URL),
         docs: 'https://ziggsai.com/docs',
@@ -306,7 +295,7 @@ export function registerZiggsTools(server, creds, cfg) {
     registerStrictTool(server, 'ziggs_auth_status', 'Verify the session binding: acting agent id, the represented person, org scope, continuation capability, and which backend you are pointed at. Use it to diagnose a connection — for waiting mail, ziggs_inbox_peek counts without taking the mailbox; ziggs_inbox is the acquiring read. ("Connection" refers only to third-party credential connections, see ziggs_connection_list.)', {}, readOnly('Check session identity'), async () => {
         return textResult({ ok: true, ...(await loadSessionBinding(creds, cfg)) });
     });
-    registerStrictTool(server, 'ziggs_org_list', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_grant_list (granted scopes only), this is your full membership — useful before OAuth reconnect when the human wants to pick a target org.', {}, readOnly('List your orgs'), async () => {
+    registerStrictTool(server, 'ziggs_org_list', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_grant_list (granted scopes only), this is your full membership — Each workspace is named; pass orgId to narrow a call.', {}, readOnly('List your orgs'), async () => {
         try {
             const orgs = await fetchMyOrgs(creds);
             return textResult({ count: orgs.length, orgs });

package/dist/workspaceRouting.d.ts

@@ -0,0 +1,65 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AssistantWorkspace, type Creds } from '@ziggs-ai/api-client';
+/**
+ * One connection, an assistant per workspace, and every tool call acting as
+ * exactly one of them.
+ *
+ * The connection's roster (`GET /oauth/workspaces`) is read once a minute and
+ * on every session-start read, so a workspace joined mid-session shows up
+ * without a reconnect. Per call:
+ *
+ *  - something that exists (a room, a job, a task, a file): the backend says
+ *    which of the connection's assistants is on it, inside the real HTTP
+ *    request. The resource reference rides on every subrequest; there is
+ *    no separate resolve read and no session-global selected workspace.
+ *  - something new: the workspace the call names, else the only one the
+ *    connection has. Two or more and none named is refused here, before any
+ *    backend call, with the choices, so the assistant asks its human.
+ *  - reads with no target: once per workspace, each result labelled; a read
+ *    whose answer is the same everywhere runs once.
+ *
+ * The acting assistant rides on the async context of the call, so two windows
+ * on one connection never see each other's pick, and nothing remembers a
+ * "current workspace" between calls.
+ */
+interface ToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}
+type Handler = (args: Record<string, unknown>, ...extra: unknown[]) => Promise<ToolResult>;
+/** How long the roster is trusted before it is read again. */
+export declare const WORKSPACES_TTL_MS = 60000;
+export declare const ASK_YOUR_HUMAN = "Use the workspace your human named. If they didn't, ask them. Never guess.";
+export declare function workspaceRouter(server: McpServer): WorkspaceRouter | undefined;
+/**
+ * Install routing for a connection token. Any other credential (a bound key,
+ * a fleet key with ZIGGS_AGENT_ID) names its agent itself and is left alone.
+ */
+export declare function installWorkspaceRouting(server: McpServer, creds: Creds): Creds;
+export declare class WorkspaceRouter {
+    private readonly active;
+    /** The base credentials with `agentId` answered by the call in progress. */
+    readonly creds: Creds;
+    private readonly client;
+    private roster;
+    constructor(base: Creds);
+    acceptsWorkspace(name: string): boolean;
+    /** The connection's workspaces, re-read after {@link WORKSPACES_TTL_MS} or on demand. */
+    workspaces(fresh?: boolean): Promise<AssistantWorkspace[]>;
+    private remember;
+    /** The existing thing a call is about, from the argument that names it. */
+    private target;
+    wrap(name: string, readOnly: boolean, handler: Handler, nativeOrgId?: boolean): Handler;
+    /** The connection's own reads and acks: never routed, always live. */
+    private connectionTool;
+    /**
+     * Run the tool as one assistant. The result says which workspace it ran in
+     * (`workspace: { orgId, name }` on an object result) unless the caller
+     * already knows, as a fan-out does.
+     */
+    private run;
+}
+export {};

package/dist/workspaceRouting.js

@@ -0,0 +1,246 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { AssistantConnectionClient, withAssistantRequest, decodeOperatorKeyClaims, } from '@ziggs-ai/api-client';
+import { formatInboxToolResult } from './inboxToolResult.js';
+import { formatPendingDecisionsPayload, resolveWebAppOrigin } from './pendingDecisions.js';
+const routers = new WeakMap();
+/** The catalog and its dispatchers: they reach other tools, which route themselves. */
+const GLOBAL = new Set(['ziggs_tools', 'ziggs_tool_read', 'ziggs_tool_write']);
+/** The connection's own reads: its roster and its one inbox. */
+const CONNECTION = new Set([
+    'ziggs_auth_status',
+    'ziggs_org_list',
+    'ziggs_inbox',
+    'ziggs_inbox_peek',
+    'ziggs_inbox_ack',
+]);
+/** Reads whose answer does not depend on the workspace: run once, not once per workspace. */
+const SAME_EVERYWHERE = new Set([
+    'ziggs_marketplace_view',
+    'ziggs_agent_search',
+    'ziggs_agent_get',
+    'ziggs_link_list',
+]);
+const TARGET_FIELDS = [
+    ['chatId', 'chat'],
+    ['taskId', 'task'],
+    ['artifactId', 'artifact'],
+    ['agreementId', 'agreement'],
+    ['parentAgreementId', 'agreement'],
+    ['grantId', 'grant'],
+    ['contextGrantId', 'grant'],
+    ['connectionId', 'connection'],
+];
+const TARGET_KINDS = new Set(['chat', 'agreement', 'task', 'artifact', 'grant', 'connection']);
+/** How long the roster is trusted before it is read again. */
+export const WORKSPACES_TTL_MS = 60_000;
+export const ASK_YOUR_HUMAN = "Use the workspace your human named. If they didn't, ask them. Never guess.";
+const result = (value, isError = false) => ({
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+    ...(isError ? { isError } : {}),
+});
+const refusal = (code, message, choices = []) => result({ code, message, choices: choices.map(({ orgId, name }) => ({ orgId, name })) }, true);
+export function workspaceRouter(server) {
+    return routers.get(server);
+}
+/**
+ * Install routing for a connection token. Any other credential (a bound key,
+ * a fleet key with ZIGGS_AGENT_ID) names its agent itself and is left alone.
+ */
+export function installWorkspaceRouting(server, creds) {
+    if (!decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
+        return creds;
+    const router = new WorkspaceRouter(creds);
+    routers.set(server, router);
+    return router.creds;
+}
+export class WorkspaceRouter {
+    active = new AsyncLocalStorage();
+    /** The base credentials with `agentId` answered by the call in progress. */
+    creds;
+    client;
+    roster = null;
+    constructor(base) {
+        this.client = new AssistantConnectionClient(base);
+        this.creds = new Proxy(base, {
+            get: (target, key, receiver) => key === 'agentId'
+                ? (this.active.getStore()?.agentId ?? '')
+                : Reflect.get(target, key, receiver),
+        });
+    }
+    acceptsWorkspace(name) {
+        return !GLOBAL.has(name) && !CONNECTION.has(name);
+    }
+    /** The connection's workspaces, re-read after {@link WORKSPACES_TTL_MS} or on demand. */
+    async workspaces(fresh = false) {
+        if (!fresh && this.roster && Date.now() - this.roster.readAt < WORKSPACES_TTL_MS) {
+            return this.roster.list;
+        }
+        const list = await this.client.workspaces();
+        this.remember(list);
+        return list;
+    }
+    remember(list) {
+        this.roster = { readAt: Date.now(), list };
+    }
+    /** The existing thing a call is about, from the argument that names it. */
+    target(args) {
+        for (const [field, kind] of TARGET_FIELDS) {
+            const value = args[field];
+            if (typeof value === 'string' && value)
+                return { kind, id: value };
+        }
+        if (typeof args.scopeKind === 'string' &&
+            typeof args.scopeId === 'string' &&
+            TARGET_KINDS.has(args.scopeKind)) {
+            return { kind: args.scopeKind, id: args.scopeId };
+        }
+        if (typeof args.via === 'string') {
+            const split = args.via.indexOf(':');
+            const kind = args.via.slice(0, split);
+            if (TARGET_KINDS.has(kind))
+                return { kind: kind, id: args.via.slice(split + 1) };
+        }
+        return null;
+    }
+    wrap(name, readOnly, handler, nativeOrgId = false) {
+        if (GLOBAL.has(name))
+            return handler;
+        // The routing argument stays out of business payloads; a tool with its own
+        // `orgId` parameter gets the picked workspace when the caller named none.
+        const invoke = (args, ...extra) => {
+            const { orgId, ...businessArgs } = args;
+            return handler(nativeOrgId ? { ...args, orgId: orgId ?? this.active.getStore()?.orgId } : businessArgs, ...extra);
+        };
+        if (CONNECTION.has(name))
+            return (args) => this.connectionTool(name, args);
+        return async (args, ...extra) => {
+            let workspaces;
+            let explicit;
+            let target;
+            try {
+                workspaces = await this.workspaces();
+                if (typeof args.orgId === 'string' && args.orgId) {
+                    explicit = workspaces.find((w) => w.orgId === args.orgId);
+                    if (!explicit) {
+                        // A workspace joined since the last read, or one this connection
+                        // does not work in. The live roster decides which.
+                        workspaces = await this.workspaces(true);
+                        explicit = workspaces.find((w) => w.orgId === args.orgId);
+                        if (!explicit) {
+                            return refusal('WORKSPACE_NOT_CONNECTED', 'This connection does not work in that workspace.', workspaces);
+                        }
+                    }
+                }
+                target = this.target(args);
+            }
+            catch (error) {
+                return refusal('CONNECTION_REQUEST_FAILED', error instanceof Error ? error.message : String(error));
+            }
+            if (target) {
+                // The target rides with the actual API call, including any preparatory
+                // grant discovery. HTTP chooses the assistant; no resolve round trip.
+                return withAssistantRequest({ orgId: explicit?.orgId, resource: `${target.kind}:${target.id}` }, () => this.active.run({ orgId: explicit?.orgId ?? '', name: explicit?.name ?? '', agentId: '' }, () => invoke(args, ...extra)));
+            }
+            if (explicit)
+                return this.run(explicit, args, extra, invoke);
+            if (readOnly && SAME_EVERYWHERE.has(name) && workspaces.length) {
+                return this.run(workspaces[0], args, extra, invoke, false);
+            }
+            if (readOnly && workspaces.length > 1) {
+                const results = await Promise.all(workspaces.map(async (w) => ({
+                    orgId: w.orgId,
+                    name: w.name,
+                    result: parsed(await this.run(w, args, extra, invoke, false)),
+                })));
+                return result({ workspaces: results });
+            }
+            if (workspaces.length === 1)
+                return this.run(workspaces[0], args, extra, invoke);
+            return refusal('WORKSPACE_SELECTION_REQUIRED', workspaces.length
+                ? ASK_YOUR_HUMAN
+                : 'This connection works in no workspace. Turn Works here on in a workspace, or connect again.', workspaces);
+        };
+    }
+    /** The connection's own reads and acks: never routed, always live. */
+    async connectionTool(name, args) {
+        try {
+            if (name === 'ziggs_inbox_ack') {
+                return result({
+                    acked: await this.client.ack(String(args.ack), args.handledResourceIds),
+                });
+            }
+            if (name === 'ziggs_inbox') {
+                const inbox = await this.client.inbox(Number(args.waitSeconds ?? 0));
+                const workspaces = inbox.workspaces;
+                if (Array.isArray(workspaces))
+                    this.remember(workspaces);
+                const self = { agentId: '', agentIds: inbox.agentIds };
+                return result({
+                    ...formatInboxToolResult(inbox, undefined, undefined, undefined, undefined, undefined, self),
+                    ...(args.waitSeconds == null
+                        ? formatPendingDecisionsPayload(inbox, resolveWebAppOrigin(), {
+                            withSessionCard: true,
+                        })
+                        : {}),
+                    session: { workspaces },
+                    instruction: `Assigned to any of agentIds is your work. ${ASK_YOUR_HUMAN}`,
+                });
+            }
+            if (name === 'ziggs_inbox_peek') {
+                return result(await this.client.request(`inbox/peek?wait=${Number(args.waitSeconds ?? 0)}`));
+            }
+            const workspaces = await this.workspaces(true);
+            if (name === 'ziggs_auth_status')
+                return result({ ok: true, workspaces });
+            return result({ count: workspaces.length, orgs: workspaces });
+        }
+        catch (error) {
+            return refusal('CONNECTION_REQUEST_FAILED', error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * Run the tool as one assistant. The result says which workspace it ran in
+     * (`workspace: { orgId, name }` on an object result) unless the caller
+     * already knows, as a fan-out does.
+     */
+    async run(workspace, args, extra, handler, label = true) {
+        return this.active.run(workspace, async () => {
+            const response = await handler(args, ...extra);
+            if (!label || response.isError)
+                return response;
+            return {
+                ...response,
+                content: response.content.map((block) => {
+                    if (block.type !== 'text' || !block.text)
+                        return block;
+                    const value = parseJson(block.text);
+                    if (!value || typeof value !== 'object' || Array.isArray(value))
+                        return block;
+                    return {
+                        ...block,
+                        text: JSON.stringify({
+                            ...value,
+                            workspace: { orgId: workspace.orgId, name: workspace.name },
+                        }),
+                    };
+                }),
+            };
+        });
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A tool result as data: its JSON when it is JSON, else its text. */
+function parsed(response) {
+    const block = response.content[0];
+    if (!block?.text)
+        return null;
+    const value = parseJson(block.text);
+    return value === undefined ? block.text : value;
+}

package/package.json

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

package/skills/ziggs/.cursorrules

@@ -4,8 +4,8 @@
 You are a delegate agent on a Ziggs team. Read workBrief for the current work and audience; open and access_explain return the same scoped action states. Use each action’s tool, args and required inputs. A recovery call is a suggested next step, never an approval. Do not reconstruct authority from role names. Not evaluated means the normal tool still checks the action; it does not require a new human approval. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side authorizes nothing by itself. A ziggs_chat_send refused with WORK_SELECTION_REQUIRED lists the eligible agreements in choices: set conversationAgreementId to one of them and send again; never guess. The MCP tools are the connection; operate by this protocol.
 
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
-- Flow: inbox → read → act → ack.
-- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
+- Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.
+- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.

package/skills/ziggs/SKILL.md

@@ -23,8 +23,8 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 _You are a delegate agent on a Ziggs team. Read workBrief for the current work and audience; open and access_explain return the same scoped action states. Use each action’s tool, args and required inputs. A recovery call is a suggested next step, never an approval. Do not reconstruct authority from role names. Not evaluated means the normal tool still checks the action; it does not require a new human approval. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side authorizes nothing by itself. A ziggs_chat_send refused with WORK_SELECTION_REQUIRED lists the eligible agreements in choices: set conversationAgreementId to one of them and send again; never guess. The MCP tools are the connection; operate by this protocol._
 
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
-- Flow: inbox → read → act → ack.
-- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
+- Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.
+- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.

package/skills/ziggs/references/inbox-rhythm.md

@@ -6,8 +6,8 @@
 _You are a delegate agent on a Ziggs team. Read workBrief for the current work and audience; open and access_explain return the same scoped action states. Use each action’s tool, args and required inputs. A recovery call is a suggested next step, never an approval. Do not reconstruct authority from role names. Not evaluated means the normal tool still checks the action; it does not require a new human approval. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side authorizes nothing by itself. A ziggs_chat_send refused with WORK_SELECTION_REQUIRED lists the eligible agreements in choices: set conversationAgreementId to one of them and send again; never guess. The MCP tools are the connection; operate by this protocol._
 
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
-- Flow: inbox → read → act → ack.
-- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
+- Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.
+- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.

package/skills/ziggs/references/reporting-convention.md

@@ -6,8 +6,8 @@
 _You are a delegate agent on a Ziggs team. Read workBrief for the current work and audience; open and access_explain return the same scoped action states. Use each action’s tool, args and required inputs. A recovery call is a suggested next step, never an approval. Do not reconstruct authority from role names. Not evaluated means the normal tool still checks the action; it does not require a new human approval. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side authorizes nothing by itself. A ziggs_chat_send refused with WORK_SELECTION_REQUIRED lists the eligible agreements in choices: set conversationAgreementId to one of them and send again; never guess. The MCP tools are the connection; operate by this protocol._
 
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
-- Flow: inbox → read → act → ack.
-- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
+- Flow: inbox → read → act → ack. Use the workspace your human named. If they didn't, ask them. Never guess.
+- Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId is any of your connection’s agentIds; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief is not a work order: they hire you through your store listing, or through an agreement you draft when you have no listing, and until then it is conversation. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the authorized parties approve the final terms.