@ziggs-ai/ziggs-mcp 0.1.25 → 0.1.27

package/README.md

@@ -2,8 +2,8 @@
 
 MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts.
 
-**In scope:** chat, agreements, scope, context discovery/reads, artifacts.  
-**Out of scope (by design):** agent `transfer`, hire agreements, capability tokens / bounded spend.
+**In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts.  
+**Out of scope (by design):** agent `transfer`, payment grants / bounded spend.
 
 ---
 

package/dist/inboxToolResult.d.ts

@@ -73,4 +73,4 @@ export declare function indexReachByScope(reach: ContextReachDescriptor[]): Map<
  * When `reach` (the caller's own live grants) is passed, each scope is tagged
  * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
  */
-export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: ContextReachDescriptor[]): Record<string, unknown>;
+export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: ContextReachDescriptor[], activeTasksError?: string): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -205,7 +205,7 @@ function tagScopesWithGrants(scopes, byScope) {
  * When `reach` (the caller's own live grants) is passed, each scope is tagged
  * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
  */
-export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach) {
+export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError) {
     // ZIG-660: build the grant index once and feed both the read plan (grant
     // pinning) and the scope tags from it — buildReadPlan no longer runs before
     // the grants are available.
@@ -213,7 +213,7 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach)
     const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope);
     const scopes = tagScopesWithGrants(inbox.scopes ?? [], byScope);
     const origin = resolveWebAppOrigin(webOrigin);
-    const pending = formatPendingDecisionsPayload(inbox, origin, { activeTasks });
+    const pending = formatPendingDecisionsPayload(inbox, origin, { activeTasks, activeTasksError });
     const pendingTail = pending.hasActionable === true
         ? {
             pendingCount: pending.pendingCount,
@@ -226,6 +226,14 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach)
         : {};
     const tail = {
         ...pendingTail,
+        // ZIG-700 — always surface a task-fetch failure, even when there is nothing
+        // else actionable, so hasActiveWork:false is not read as "no tasks".
+        ...(pending.activeTasksFetchError
+            ? {
+                activeTasksFetchError: pending.activeTasksFetchError,
+                workCardOmitted: true,
+            }
+            : {}),
         ...(readPlan.length ? { readPlan } : {}),
         ...(readPlanTruncated ? { readPlanTruncated } : {}),
     };

package/dist/pendingDecisions.d.ts

@@ -34,6 +34,20 @@ export declare function agreementsListAppUrl(origin: string): string;
 /** Where the human connects MCP servers and grants tools (ZIG-686). */
 export declare function connectionsSettingsAppUrl(origin: string): string;
 export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string): PendingDecisionItem[];
+/**
+ * ZIG-658: keep only tasks this delegate (or its principal) is expected to
+ * execute. The backend's GET /tasks returns every task reachable in the org,
+ * so the session card must not present all of them as "your work".
+ *
+ * A task is "for me" when:
+ * - it is explicitly assigned (`assigneeId`) to one of my ids, or
+ * - it has no explicit assignee and one of my ids sits on the executing side
+ *   of the task/agreement (executor, agent, provider, providerAgent,
+ *   proposedTo).
+ * Tasks with no assignee and no readable agreement parties are excluded —
+ * "can't tell" must not render as "yours".
+ */
+export declare function filterTasksForDelegate(tasks: Task[], selfIds: ReadonlySet<string>): Task[];
 export declare function buildActiveWorkItems(tasks: Task[], webOrigin: string): ActiveWorkItem[];
 export declare function buildDecisionChatCard(items: PendingDecisionItem[], opts: {
     truncatedProposals?: number;
@@ -52,5 +66,6 @@ export declare function buildSessionChatCard(decisions: PendingDecisionItem[], w
 /** Structured session payload for MCP tools (ZIG-625 + active work). */
 export declare function formatPendingDecisionsPayload(inbox: InboxEnvelope, webOrigin: string, opts?: {
     activeTasks?: Task[];
+    activeTasksError?: string;
 }): Record<string, unknown>;
 export declare function buildPendingNextActions(decisions: PendingDecisionItem[], work?: ActiveWorkItem[]): string[];

package/dist/pendingDecisions.js

@@ -109,6 +109,32 @@ export function buildPendingDecisionItems(inbox, webOrigin) {
     }
     return items;
 }
+/**
+ * ZIG-658: keep only tasks this delegate (or its principal) is expected to
+ * execute. The backend's GET /tasks returns every task reachable in the org,
+ * so the session card must not present all of them as "your work".
+ *
+ * A task is "for me" when:
+ * - it is explicitly assigned (`assigneeId`) to one of my ids, or
+ * - it has no explicit assignee and one of my ids sits on the executing side
+ *   of the task/agreement (executor, agent, provider, providerAgent,
+ *   proposedTo).
+ * Tasks with no assignee and no readable agreement parties are excluded —
+ * "can't tell" must not render as "yours".
+ */
+export function filterTasksForDelegate(tasks, selfIds) {
+    const mine = (id) => typeof id === 'string' && id.length > 0 && selfIds.has(id);
+    return tasks.filter((t) => {
+        if (t.assigneeId)
+            return mine(t.assigneeId);
+        if (mine(t.executorId) || mine(t.agentId))
+            return true;
+        const p = t.agreement?.parties;
+        if (!p)
+            return false;
+        return mine(p.provider) || mine(p.providerAgent) || mine(p.proposedTo);
+    });
+}
 export function buildActiveWorkItems(tasks, webOrigin) {
     return tasks
         .filter((t) => t.state === 'active')
@@ -381,6 +407,14 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         ...(workChatCard ? { workChatCard } : {}),
         ...(sessionChatCard ? { sessionChatCard } : {}),
         ...(inbox.humanAttention ? { humanAttention: inbox.humanAttention } : {}),
+        // ZIG-700 — when the active-task fetch failed, say so instead of letting
+        // hasActiveWork:false read as "no tasks". Mirrors the inbox fetchError signal.
+        ...(opts?.activeTasksError
+            ? {
+                activeTasksFetchError: `Could not load active tasks: ${opts.activeTasksError}`,
+                workCardOmitted: true,
+            }
+            : {}),
         instruction,
     };
 }

package/dist/toolError.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ZIG-667 — one error surface for every MCP tool.
+ *
+ * Raw client exceptions read like
+ *   `ContextReadClient.read messages 403 {"error":"not authorized for this scope"}`
+ * — an internal class.method name, a raw HTTP status, and a raw backend body.
+ * LLM callers stall on stack-trace prose; they recover from errors they can
+ * parse. This module strips the internals, keeps a stable machine-readable
+ * code, and for authorization denials says what to do next.
+ */
+export interface ToolErrorShape {
+    code: string;
+    message: string;
+    hint?: string;
+}
+/** Classify a raw client error message into a stable shape. */
+export declare function classifyToolError(rawMessage: string): ToolErrorShape;
+/** MCP tool error result: machine-readable code + cleaned message (+ hint). */
+export declare function toolError(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/toolError.js

@@ -0,0 +1,81 @@
+/**
+ * ZIG-667 — one error surface for every MCP tool.
+ *
+ * Raw client exceptions read like
+ *   `ContextReadClient.read messages 403 {"error":"not authorized for this scope"}`
+ * — an internal class.method name, a raw HTTP status, and a raw backend body.
+ * LLM callers stall on stack-trace prose; they recover from errors they can
+ * parse. This module strips the internals, keeps a stable machine-readable
+ * code, and for authorization denials says what to do next.
+ */
+const CLIENT_PREFIX = /^[A-Z][A-Za-z0-9]*Client\.[A-Za-z0-9_]+\s+/;
+const HTTP_STATUS = /(?:^|\s)([1-5]\d{2})(?=\s|$)/;
+const SCOPE_DENIED_HINT = 'You are not authorized for this scope. To get access: ask the counterparty ' +
+    'to issue you a context grant (they run ziggs_issue_grant), or request a ' +
+    'bilateral link first (ziggs_request_link). Check what you can already ' +
+    'reach with ziggs_discover_context / ziggs_get_scope.';
+function codeForStatus(status) {
+    if (status === 401)
+        return 'NOT_AUTHENTICATED';
+    if (status === 403)
+        return 'NOT_AUTHORIZED';
+    if (status === 404)
+        return 'NOT_FOUND';
+    if (status === 409)
+        return 'CONFLICT';
+    if (status === 429)
+        return 'RATE_LIMITED';
+    if (status >= 500)
+        return 'UPSTREAM_ERROR';
+    if (status >= 400)
+        return 'BAD_REQUEST';
+    return 'TOOL_ERROR';
+}
+/** Pull a human reason out of an embedded backend JSON body, if any. */
+function extractBodyReason(raw) {
+    const start = raw.indexOf('{');
+    if (start === -1)
+        return null;
+    try {
+        const parsed = JSON.parse(raw.slice(start));
+        const reason = parsed['error'] ?? parsed['message'];
+        return typeof reason === 'string' && reason.trim() ? reason.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Classify a raw client error message into a stable shape. */
+export function classifyToolError(rawMessage) {
+    const cleaned = rawMessage.replace(CLIENT_PREFIX, '').trim();
+    const statusMatch = HTTP_STATUS.exec(cleaned);
+    const status = statusMatch ? Number(statusMatch[1]) : null;
+    const bodyReason = extractBodyReason(cleaned);
+    if (status === null) {
+        return { code: 'TOOL_ERROR', message: cleaned || rawMessage };
+    }
+    const code = codeForStatus(status);
+    // Prefer the backend's own reason over the transport framing.
+    const message = bodyReason ?? cleaned;
+    // Context-scope denials (the backend says "…for this scope") get the scope
+    // code and a recovery path. Other 403s (connection grants, party checks)
+    // keep the generic code — their fixes live in other domains.
+    if (code === 'NOT_AUTHORIZED' && /\bscope\b/i.test(message)) {
+        return {
+            code: 'NOT_AUTHORIZED_FOR_SCOPE',
+            message,
+            hint: SCOPE_DENIED_HINT,
+        };
+    }
+    return { code, message };
+}
+/** MCP tool error result: machine-readable code + cleaned message (+ hint). */
+export function toolError(message) {
+    const shape = classifyToolError(message);
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify({ error: shape }, null, 2) },
+        ],
+        isError: true,
+    };
+}

package/dist/tools.js

@@ -4,9 +4,10 @@ import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDi
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
-import { connectionsSettingsAppUrl, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
+import { connectionsSettingsAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { toolError } from './toolError.js';
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
 // from the shared const so this description can't drift from SKILL / server
 // instructions / .cursorrules.
@@ -48,12 +49,6 @@ function textResult(data) {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
-function toolError(message) {
-    return {
-        content: [{ type: 'text', text: message }],
-        isError: true,
-    };
-}
 const scopeKindSchema = z.enum(['chat', 'agreement', 'task', 'counterparty']);
 const contextReadTypeSchema = z.enum([
     'messages',
@@ -84,6 +79,8 @@ async function writeArtifactStrict(creds, input) {
         const body = await res.text().catch(() => '');
         throw new Error(`POST /artifacts ${res.status} ${body.slice(0, 200)}`);
     }
+    const body = (await res.json().catch(() => ({})));
+    return { artifactId: body.artifactId };
 }
 // ZIG-569 — defense-in-depth mirror of the backend leak-guard
 // (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
@@ -249,19 +246,36 @@ async function listMcpConnectionRequests(creds) {
     const parsed = body ? JSON.parse(body) : null;
     return parsed?.['requests'] ?? [];
 }
+/**
+ * Ids this delegate answers for: its own agent id plus its principal's user
+ * id (operator-key ownerId / ZIGGS_OWNER_USER_ID). Used to decide which
+ * active tasks count as "your work" on session cards (ZIG-658).
+ */
+function delegateSelfIds(creds, cfg) {
+    const ids = new Set([creds.agentId]);
+    const ownerId = decodeOperatorKeyClaims(creds.operatorKey)?.ownerId;
+    if (ownerId)
+        ids.add(ownerId);
+    if (cfg.ZIGGS_OWNER_USER_ID)
+        ids.add(cfg.ZIGGS_OWNER_USER_ID);
+    return ids;
+}
 async function loadSessionActionsPayload(creds, cfg) {
     const webOrigin = resolveWebAppOrigin(cfg.ZIGGS_WEB_URL);
     const client = new InboxClient(creds.operatorKey, creds.agentId);
     const inbox = await client.getInbox();
     let activeTasks = [];
+    let activeTasksError;
     try {
         const listed = await listTasks({ state: 'active', limit: 20 }, creds);
-        activeTasks = listed.tasks ?? [];
+        activeTasks = filterTasksForDelegate(listed.tasks ?? [], delegateSelfIds(creds, cfg));
     }
-    catch {
-        // Inbox is still useful when task listing fails.
+    catch (e) {
+        // ZIG-700 — inbox is still useful when task listing fails, but surface the
+        // failure so hasActiveWork:false is not mistaken for "no tasks".
+        activeTasksError = e.message;
     }
-    return formatPendingDecisionsPayload(inbox, webOrigin, { activeTasks });
+    return formatPendingDecisionsPayload(inbox, webOrigin, { activeTasks, activeTasksError });
 }
 export function registerZiggsTools(server, creds, cfg) {
     server.tool('ziggs_auth_status', 'Verify MCP OAuth binding: delegate agent id, owner user id, and org scope. Call after connect before inbox/chats. Includes pendingDecisions summary when approve/reject is waiting. (Renamed from ziggs_connection_status — "connection" now refers only to third-party credential connections, see ziggs_connection_proxy.)', {}, READ_ONLY, async () => {
@@ -477,7 +491,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_propose_agreement', 'Propose a direct service agreement to one counterparty in a chat, as the payer-side delegate. Requires payerId (or ZIGGS_OWNER_USER_ID). price is recorded on the agreement but does not itself trigger a transfer — V1 has no real payment rail yet.', {
+    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty in a chat, as the payer-side delegate. engagementKind "service" (default) = one deliverable; "hire" = an ongoing engagement (same kinds ziggs_publish_offer accepts). Requires payerId (or ZIGGS_OWNER_USER_ID). price is recorded on the agreement but does not itself trigger a transfer — V1 has no real payment rail yet.', {
         proposedTo: z.string(),
         chatId: z.string(),
         description: z.string(),
@@ -486,7 +500,11 @@ export function registerZiggsTools(server, creds, cfg) {
             .optional()
             .describe('Human user id = payer (your userId)'),
         price: z.number().optional().describe('Optional; does not trigger transfer by itself'),
-    }, WRITE, async ({ proposedTo, chatId, description, payerId, price }) => {
+        engagementKind: z
+            .enum(['hire', 'service'])
+            .optional()
+            .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement"),
+    }, WRITE, async ({ proposedTo, chatId, description, payerId, price, engagementKind }) => {
         try {
             const resolvedPayer = payerId ?? cfg.ZIGGS_OWNER_USER_ID;
             if (!resolvedPayer) {
@@ -498,7 +516,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 description,
                 payerId: resolvedPayer,
                 price,
-                engagementKind: 'service',
+                engagementKind: engagementKind ?? 'service',
             }, creds);
             return textResult({ agreement });
         }
@@ -604,12 +622,14 @@ export function registerZiggsTools(server, creds, cfg) {
             const acked = ack?.length ? await client.ack(ack) : null;
             const inbox = await client.getInbox();
             let activeTasks = [];
+            let activeTasksError;
             try {
                 const listed = await listTasks({ state: 'active', limit: 20 }, creds);
-                activeTasks = listed.tasks ?? [];
+                activeTasks = filterTasksForDelegate(listed.tasks ?? [], delegateSelfIds(creds, cfg));
             }
-            catch {
-                // omit work card when tasks fail
+            catch (e) {
+                // ZIG-700 — surface the failure instead of silently omitting the work card.
+                activeTasksError = e.message;
             }
             // ZIG-635: tag each scope with the covering grant from the caller's own
             // live reach descriptors. Best-effort — the inbox still works untagged.
@@ -620,7 +640,7 @@ export function registerZiggsTools(server, creds, cfg) {
             catch {
                 // omit grant tags when discovery fails
             }
-            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach));
+            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach, activeTasksError));
         }
         catch (e) {
             return toolError(e.message);
@@ -693,7 +713,7 @@ export function registerZiggsTools(server, creds, cfg) {
             if ((chatId && agreementId) || (!chatId && !agreementId)) {
                 return toolError('Pass exactly one of chatId or agreementId');
             }
-            await writeArtifactStrict(creds, {
+            const { artifactId } = await writeArtifactStrict(creds, {
                 text,
                 visibility,
                 chatId,
@@ -703,6 +723,7 @@ export function registerZiggsTools(server, creds, cfg) {
             });
             return textResult({
                 ok: true,
+                artifactId,
                 visibility,
                 chatId,
                 agreementId,

package/dist/trustTools.js

@@ -1,17 +1,12 @@
 import { z } from 'zod';
 import { AgentSearchClient, ContextGrantsClient, createAgreement, listAgreements, revokeAgreement, claimAgreement, addChatMember, } from '@ziggs-ai/api-client';
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { toolError } from './toolError.js';
 function textResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
-function toolError(message) {
-    return {
-        content: [{ type: 'text', text: message }],
-        isError: true,
-    };
-}
 const grantScopeKindSchema = z.enum(['chat', 'agreement', 'org']);
 const contextTemporalSchema = z.enum(['from-now', 'from-start']);
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
@@ -29,9 +24,21 @@ export function registerTrustTools(server, creds, cfg) {
             if (!result.success) {
                 return toolError(result.error ?? result.message ?? 'search failed');
             }
+            if (!result.agents?.length) {
+                // ZIG-664: a bare {count: 0} reads as "discovery is down" to LLM
+                // callers — say what was searched and how to recover instead.
+                return textResult({
+                    count: 0,
+                    agents: [],
+                    searched: ['published store', 'your org-mates', 'your linked delegates'],
+                    hint: 'Zero hits means no agent profile matched these terms — discovery itself is up. ' +
+                        'Matching is lexical against agent name/description/tags, so try shorter or different keywords. ' +
+                        'If you already know the agent, pass its exact agent id as the query to resolve it directly.',
+                });
+            }
             return textResult({
-                count: result.agents?.length ?? 0,
-                agents: result.agents ?? [],
+                count: result.agents.length,
+                agents: result.agents,
             });
         }
         catch (e) {
@@ -197,13 +204,38 @@ export function registerTrustTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_list_links', 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Each item exposes parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner), proposal.status and status. Approve pending links via ziggs_respond_to_agreement.', {}, READ_ONLY, async () => {
+    server.tool('ziggs_list_links', 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_respond_to_agreement.', {
+        status: z
+            .enum(['active', 'open', 'cancelled', 'all'])
+            .optional()
+            .describe('active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status'),
+    }, READ_ONLY, async ({ status }) => {
         try {
-            const links = await listAgreements({ engagementKind: 'link' }, creds);
+            const resolvedStatus = status ?? 'active';
+            const links = await listAgreements({
+                engagementKind: 'link',
+                ...(resolvedStatus === 'all' ? {} : { status: resolvedStatus }),
+            }, creds);
+            // ZIG-670: link-shaped summaries, not raw agreement documents — the
+            // money block, approvals array, and Mongo internals are noise here.
+            const summaries = links.map((a) => ({
+                agreementId: a.agreementId,
+                status: a.status,
+                proposalStatus: a.proposalStatus,
+                parties: {
+                    creatorAgent: a.parties?.creatorAgent ?? null,
+                    providerAgent: a.parties?.providerAgent ?? null,
+                    creator: a.parties?.creator ?? null,
+                    proposedTo: a.parties?.proposedTo ?? null,
+                },
+                ...(a.description ? { description: a.description } : {}),
+                createdAt: a.createdAt,
+            }));
             const hasActive = links.some((a) => a.status === 'active');
             return textResult({
-                count: links.length,
-                links,
+                count: summaries.length,
+                status: resolvedStatus,
+                links: summaries,
                 ...(hasActive
                     ? {
                         nextSteps: 'A link is reach-only. Use ziggs_open_conversation (participantId = peer agent id) and/or ziggs_issue_grant before reading context.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {