@ziggs-ai/ziggs-mcp 0.1.24 → 0.1.26

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/pendingDecisions.d.ts

@@ -1,17 +1,22 @@
 import type { InboxEnvelope, Task } from '@ziggs-ai/api-client';
-export type PendingDecisionKind = 'proposal' | 'link_request';
+export type PendingDecisionKind = 'proposal' | 'link_request' | 'mcp_server_request';
 export interface PendingDecisionItem {
     kind: PendingDecisionKind;
+    /** Agreement id for proposals; requestId for link / MCP server requests. */
     agreementId: string;
     title: string;
     subtitle: string | null;
     proposedAt: string | null;
     proposedAtLabel: string | null;
     appUrl: string;
-    respondApprove: string;
-    respondReject: string;
-    sayApprove: string;
-    sayReject: string;
+    /**
+     * Null for mcp_server_request — connecting a server (OAuth) happens in the
+     * browser at /app/settings/connections; there is no MCP respond tool.
+     */
+    respondApprove: string | null;
+    respondReject: string | null;
+    sayApprove: string | null;
+    sayReject: string | null;
 }
 export interface ActiveWorkItem {
     taskId: string;
@@ -26,11 +31,28 @@ export interface ActiveWorkItem {
 export declare function resolveWebAppOrigin(webUrl?: string | null): string;
 export declare function agreementAppUrl(origin: string, agreementId: string): string;
 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;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: string): string;
@@ -38,6 +60,7 @@ export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: stri
 export declare function buildSessionChatCard(decisions: PendingDecisionItem[], work: ActiveWorkItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 /** Structured session payload for MCP tools (ZIG-625 + active work). */

package/dist/pendingDecisions.js

@@ -9,6 +9,10 @@ export function agreementAppUrl(origin, agreementId) {
 export function agreementsListAppUrl(origin) {
     return `${origin}/app/agreements`;
 }
+/** Where the human connects MCP servers and grants tools (ZIG-686). */
+export function connectionsSettingsAppUrl(origin) {
+    return `${origin}/app/settings/connections`;
+}
 function truncateText(text, max = TITLE_MAX) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     if (oneLine.length <= max)
@@ -75,6 +79,23 @@ function linkToItem(c, origin) {
         sayReject: `reject link ${id}`,
     };
 }
+function mcpServerRequestToItem(r, origin) {
+    const tools = r.tools?.length ? r.tools.join(', ') : 'no tools listed';
+    const reason = r.reason?.trim() || null;
+    return {
+        kind: 'mcp_server_request',
+        agreementId: r.requestId,
+        title: truncateText(`Connect MCP server · ${r.serverUrl}`),
+        subtitle: truncateText(reason ? `${reason} — tools: ${tools}` : `Tools: ${tools}`, 160),
+        proposedAt: r.requestedAt,
+        proposedAtLabel: formatWhen(r.requestedAt),
+        appUrl: connectionsSettingsAppUrl(origin),
+        respondApprove: null,
+        respondReject: null,
+        sayApprove: null,
+        sayReject: null,
+    };
+}
 export function buildPendingDecisionItems(inbox, webOrigin) {
     const items = [];
     for (const p of inbox.proposalsAwaitingMe ?? []) {
@@ -83,8 +104,37 @@ export function buildPendingDecisionItems(inbox, webOrigin) {
     for (const c of inbox.connectionRequestsAwaitingMe ?? []) {
         items.push(linkToItem(c, webOrigin));
     }
+    for (const r of inbox.mcpServerRequestsAwaitingMe ?? []) {
+        items.push(mcpServerRequestToItem(r, 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')
@@ -105,17 +155,26 @@ export function buildActiveWorkItems(tasks, webOrigin) {
     });
 }
 function kindLabel(kind) {
-    return kind === 'proposal' ? 'Agreement proposal' : 'Agent link request';
+    if (kind === 'proposal')
+        return 'Agreement proposal';
+    if (kind === 'link_request')
+        return 'Agent link request';
+    return 'MCP server request';
 }
 function kindHint(kind) {
-    return kind === 'proposal'
-        ? 'Someone proposed work or terms — your approval opens or rejects it.'
-        : 'Another agent wants to link — your approval enables cross-org reach.';
+    if (kind === 'proposal') {
+        return 'Someone proposed work or terms — your approval opens or rejects it.';
+    }
+    if (kind === 'link_request') {
+        return 'Another agent wants to link — your approval enables cross-org reach.';
+    }
+    return 'Your agent asks you to connect an MCP server and grant it the listed tools — connect (OAuth) or reject in the browser.';
 }
 function buildDecisionSection(items, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     if (!items.length && truncated === 0)
         return [];
     const lines = [];
@@ -136,18 +195,27 @@ function buildDecisionSection(items, opts) {
             lines.push(`> ${item.subtitle}`);
         }
         lines.push('');
-        lines.push(`[Review in Ziggs →](${item.appUrl})`);
-        lines.push('');
-        lines.push('| You say in chat | What the agent runs |');
-        lines.push('|:----------------|:--------------------|');
-        lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
-        lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
+        if (item.sayApprove && item.respondApprove && item.sayReject && item.respondReject) {
+            lines.push(`[Review in Ziggs →](${item.appUrl})`);
+            lines.push('');
+            lines.push('| You say in chat | What the agent runs |');
+            lines.push('|:----------------|:--------------------|');
+            lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
+            lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
+        }
+        else {
+            // Browser-only decision (mcp_server_request): connecting a server runs
+            // OAuth consent — no MCP tool can approve it from chat.
+            lines.push(`[Connect or reject in Ziggs →](${item.appUrl})`);
+            lines.push('');
+            lines.push('_This one is decided in the browser — nothing to approve from chat._');
+        }
         lines.push('');
     }
     if (truncated > 0) {
         lines.push('---');
         lines.push('');
-        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s)) — not listed here._`);
+        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s), ${truncatedMcpServerRequests} MCP server request(s)) — not listed here._`);
         lines.push('');
     }
     return lines;
@@ -188,11 +256,13 @@ function buildWorkSection(work, startIndex = 1) {
 export function buildDecisionChatCard(items, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     if (!items.length && truncated === 0)
         return '';
     const proposals = items.filter((i) => i.kind === 'proposal').length;
     const links = items.filter((i) => i.kind === 'link_request').length;
+    const mcpRequests = items.filter((i) => i.kind === 'mcp_server_request').length;
     const listedTotal = items.length + truncated;
     const lines = [
         `### 🔔 Ziggs — **${listedTotal}** ${listedTotal === 1 ? 'item needs' : 'items need'} your decision`,
@@ -201,9 +271,12 @@ export function buildDecisionChatCard(items, opts) {
         '|:--|--:|',
         `| Agreement proposals | **${proposals}** |`,
         `| Agent link requests | **${links}** |`,
+        ...(mcpRequests + truncatedMcpServerRequests > 0
+            ? [`| MCP server requests | **${mcpRequests}** |`]
+            : []),
         ...(truncated > 0 ? [`| _Not shown (inbox cap)_ | _+${truncated}_ |`] : []),
         '',
-        '> **Heads-up:** Ziggs MCP is pull-only — nothing pops up in Cursor until inbox is checked. **You** approve or reject in this chat; the agent calls `ziggs_respond_to_agreement` only after you say so.',
+        '> **Heads-up:** Ziggs MCP is pull-only — nothing pops up in Cursor until inbox is checked. **You** approve or reject in this chat; the agent calls `ziggs_respond_to_agreement` only after you say so. MCP server requests are the exception — those are connected or rejected in the browser.',
         '',
         ...buildDecisionSection(items, opts),
     ];
@@ -232,12 +305,15 @@ export function buildWorkChatCard(work, listUrl) {
 export function buildSessionChatCard(decisions, work, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     const decisionListed = decisions.length + truncated;
     const workCount = work.length;
     const total = decisionListed + workCount;
     if (total === 0)
         return '';
+    const mcpRequestCount = decisions.filter((d) => d.kind === 'mcp_server_request').length +
+        truncatedMcpServerRequests;
     const lines = [
         `### 🔔 Ziggs — **${total}** ${total === 1 ? 'thing needs' : 'things need'} you`,
         '',
@@ -248,11 +324,16 @@ export function buildSessionChatCard(decisions, work, opts) {
                 `| Approve / reject | **${decisionListed}** |`,
                 `| — proposals | ${decisions.filter((d) => d.kind === 'proposal').length}${truncatedProposals ? ` (+${truncatedProposals} hidden)` : ''} |`,
                 `| — link requests | ${decisions.filter((d) => d.kind === 'link_request').length}${truncatedConnectionRequests ? ` (+${truncatedConnectionRequests} hidden)` : ''} |`,
+                ...(mcpRequestCount > 0
+                    ? [
+                        `| — MCP server requests | ${decisions.filter((d) => d.kind === 'mcp_server_request').length}${truncatedMcpServerRequests ? ` (+${truncatedMcpServerRequests} hidden)` : ''} |`,
+                    ]
+                    : []),
             ]
             : []),
         ...(workCount > 0 ? [`| Active tasks (your work) | **${workCount}** |`] : []),
         '',
-        '> **Heads-up:** MCP is pull-only — check at session start. **Decisions:** you say approve/reject. **Tasks:** say `work on <taskId>` — the agent implements and reports on Ziggs.',
+        '> **Heads-up:** MCP is pull-only — check at session start. **Decisions:** you say approve/reject (MCP server requests are connected in the browser instead). **Tasks:** say `work on <taskId>` — the agent implements and reports on Ziggs.',
         '',
     ];
     let sectionIndex = 1;
@@ -275,13 +356,18 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const activeWork = buildActiveWorkItems(opts?.activeTasks ?? [], webOrigin);
     const truncatedProposals = inbox.truncatedProposals ?? 0;
     const truncatedConnectionRequests = inbox.truncatedConnectionRequests ?? 0;
-    const pendingCount = decisions.length + truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = inbox.truncatedMcpServerRequests ?? 0;
+    const pendingCount = decisions.length +
+        truncatedProposals +
+        truncatedConnectionRequests +
+        truncatedMcpServerRequests;
     const activeWorkCount = activeWork.length;
     const actionCount = pendingCount + activeWorkCount;
     const listUrl = agreementsListAppUrl(webOrigin);
     const cardOpts = {
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedMcpServerRequests,
         agreementsListAppUrl: listUrl,
     };
     const decisionChatCard = buildDecisionChatCard(decisions, cardOpts);
@@ -289,6 +375,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const sessionChatCard = buildSessionChatCard(decisions, activeWork, cardOpts);
     const proposalCount = decisions.filter((d) => d.kind === 'proposal').length;
     const linkCount = decisions.filter((d) => d.kind === 'link_request').length;
+    const mcpServerRequestCount = decisions.filter((d) => d.kind === 'mcp_server_request').length;
     const instruction = actionCount > 0
         ? 'Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_respond_to_agreement. Tasks: when the human says work on <taskId>, read context and implement.'
         : 'No pending decisions or active tasks — continue with ziggs_inbox for scope news.';
@@ -302,15 +389,20 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         summary: {
             proposals: proposalCount + truncatedProposals,
             linkRequests: linkCount + truncatedConnectionRequests,
+            mcpServerRequests: mcpServerRequestCount + truncatedMcpServerRequests,
             activeTasks: activeWorkCount,
             listed: decisions.length,
-            truncated: truncatedProposals + truncatedConnectionRequests,
+            truncated: truncatedProposals +
+                truncatedConnectionRequests +
+                truncatedMcpServerRequests,
         },
         decisions,
         activeWork,
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedMcpServerRequests,
         agreementsListAppUrl: listUrl,
+        connectionsSettingsAppUrl: connectionsSettingsAppUrl(webOrigin),
         ...(decisionChatCard ? { decisionChatCard } : {}),
         ...(workChatCard ? { workChatCard } : {}),
         ...(sessionChatCard ? { sessionChatCard } : {}),
@@ -327,7 +419,12 @@ export function buildPendingNextActions(decisions, work = []) {
         actions.push('Wait for the human to say approve/reject (e.g. `approve agr-…`) — do not auto-respond.');
     }
     for (const d of decisions.slice(0, 4)) {
-        actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
+        if (d.sayApprove && d.sayReject) {
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
+        }
+        else {
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: connect or reject in the browser → ${d.appUrl}`);
+        }
     }
     for (const w of work.slice(0, 4)) {
         actions.push(`Active task ${w.taskId}: human says \`${w.sayWork}\` to start implementation.`);

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 { 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*
@@ -205,6 +202,64 @@ async function listConnectionsForHolder(creds) {
     }
     return parsed?.['connections'] ?? [];
 }
+/**
+ * ZIG-686 — agent-initiated MCP connection request: ask the principal to
+ * connect a remote MCP server and grant this agent the listed tools. Creates a
+ * pending decision the human resolves in the browser (OAuth consent or a grant
+ * from an existing connection) — never from chat.
+ */
+async function createMcpConnectionRequest(creds, input) {
+    const url = `${getBackendUrl()}/connections/mcp/requests`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${creds.operatorKey}`,
+            'X-Agent-Id': creds.agentId,
+        },
+        body: JSON.stringify({
+            serverUrl: input.serverUrl,
+            tools: input.tools,
+            reason: input.reason,
+        }),
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`POST /connections/mcp/requests ${res.status} ${body.slice(0, 200)}`);
+    }
+    return body ? JSON.parse(body) : {};
+}
+/** ZIG-686 — the requests this agent made, each with status / connectionId / grantId. */
+async function listMcpConnectionRequests(creds) {
+    const url = `${getBackendUrl()}/connections/mcp/requests`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${creds.operatorKey}`,
+            'X-Agent-Id': creds.agentId,
+        },
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`GET /connections/mcp/requests ${res.status} ${body.slice(0, 200)}`);
+    }
+    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);
@@ -212,7 +267,7 @@ async function loadSessionActionsPayload(creds, cfg) {
     let activeTasks = [];
     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.
@@ -287,7 +342,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 : 'Next: ziggs_inbox or ziggs_pending_decisions at session start.',
         });
     });
-    server.tool('ziggs_switch_org', 'ZIG-640 — Switch which org this MCP OAuth session acts in without reconnecting. Existing Bearer unchanged; runtime org flips server-side. Requires confirm=true (party-identity change). Target org must be one you belong to. Call ziggs_auth_status after to verify actingOrgId.', {
+    server.tool('ziggs_switch_org', 'Switch which org this MCP OAuth session acts in without reconnecting. Existing Bearer unchanged; runtime org flips server-side. Requires confirm=true (party-identity change). Target org must be one you belong to. Call ziggs_auth_status after to verify actingOrgId.', {
         orgId: z.string().describe('Organization id to act in'),
         confirm: z
             .literal(true)
@@ -433,7 +488,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(),
@@ -442,7 +497,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) {
@@ -454,7 +513,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 description,
                 payerId: resolvedPayer,
                 price,
-                engagementKind: 'service',
+                engagementKind: engagementKind ?? 'service',
             }, creds);
             return textResult({ agreement });
         }
@@ -562,7 +621,7 @@ export function registerZiggsTools(server, creds, cfg) {
             let activeTasks = [];
             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
@@ -649,7 +708,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,
@@ -659,6 +718,7 @@ export function registerZiggsTools(server, creds, cfg) {
             });
             return textResult({
                 ok: true,
+                artifactId,
                 visibility,
                 chatId,
                 agreementId,
@@ -796,5 +856,46 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_request_connection', 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
+        'Creates a pending decision — the human connects (OAuth) or rejects it in the browser under Settings → Connections; there is no MCP tool to approve it, so tell them and link the returned approveUrl. ' +
+        'Check the outcome with ziggs_request_connection_status: a fulfilled request carries the connectionId + grantId to use with ziggs_connection_proxy.', {
+        serverUrl: z.string().describe('Remote MCP server URL (https)'),
+        tools: z
+            .array(z.string())
+            .describe("Tool names you want — become the grant's allowed_actions caveats"),
+        reason: z
+            .string()
+            .optional()
+            .describe('Plain-language reason shown to the human deciding'),
+    }, WRITE, async ({ serverUrl, tools, reason }) => {
+        try {
+            const result = await createMcpConnectionRequest(creds, {
+                serverUrl,
+                tools,
+                reason,
+            });
+            const approveUrl = connectionsSettingsAppUrl(resolveWebAppOrigin(cfg.ZIGGS_WEB_URL));
+            return textResult({
+                ok: true,
+                ...result,
+                approveUrl,
+                note: 'Pending your principal\'s decision. Tell the human now (pull-only MCP has no push) and link the approveUrl — they connect or reject there. ' +
+                    'Poll ziggs_request_connection_status for the outcome; fulfilled requests carry connectionId + grantId for ziggs_connection_proxy.',
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_request_connection_status', 'List the MCP server connection requests this agent made with ziggs_request_connection, each with status pending | fulfilled | rejected. ' +
+        'A fulfilled request carries the connectionId + grantId to feed into ziggs_connection_proxy (it also appears in ziggs_list_my_connections).', {}, READ_ONLY, async () => {
+        try {
+            const requests = await listMcpConnectionRequests(creds);
+            return textResult({ requests });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     registerTrustTools(server, creds, cfg);
 }

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.24",
+  "version": "0.1.26",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.19",
+    "@ziggs-ai/api-client": "^0.1.20",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },