@ziggs-ai/agent-sdk 0.2.1 → 0.3.0

package/dist/server/tools/tier1/protocolRunner.js

@@ -34,7 +34,7 @@ function normalizePlanInPlace(payload) {
         payload.planReviewTiming = 'with_proposal';
     }
 }
-export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null) {
+export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, wakeKeys = null) {
     if (!payload?.operation)
         return null;
     normalizePlanInPlace(payload);
@@ -43,9 +43,9 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
     const actorId = actingAgentId?.trim() || null;
     switch (operation) {
         case 'agreement-propose':
-            return proposeAgreement(services, payload, chatId, agents, actorId);
+            return proposeAgreement(services, payload, chatId, agents, actorId, wakeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, chatId, agents, actorId);
+            return subcontractAgreement(services, payload, chatId, agents, actorId, wakeKeys);
         case 'agreement-respond':
             if (!payload.agreementId || !payload.action)
                 return null;
@@ -146,12 +146,27 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
                 inputArtifactIds: Array.isArray(payload.inputArtifactIds)
                     ? payload.inputArtifactIds
                     : undefined,
+                // Wake-derived idempotency key (delivery law): a crash-replay re-issuing
+                // this spawn resolves to the already-created task server-side instead of
+                // creating a duplicate. Keyed on what is actually written (the resolved
+                // agreement, not the LLM-cited one), so multiple spawns in one wake stay
+                // distinct.
+                idempotencyKey: wakeKeys?.taskSpawnKey({
+                    agreementId: spawnAgreementId,
+                    description: payload.description,
+                    assigneeId: payload.assigneeId,
+                    parentTaskId: payload.parentTaskId,
+                }),
             });
         }
-        case 'task-update':
+        case 'task-update': {
             if (!payload.taskId || !payload.status)
                 return null;
-            return taskService.updateState(payload.taskId, normalizeState(payload.status), payload.result);
+            const state = normalizeState(payload.status);
+            // Wake-derived idempotency key: a crash-replay re-issuing this transition
+            // no-ops server-side instead of erroring on the already-terminal task.
+            return taskService.updateState(payload.taskId, state, payload.result, wakeKeys?.taskStateKey(payload.taskId, state));
+        }
         case 'task-update-plan-step':
             if (!payload.taskId)
                 throw new Error('task-update-plan-step requires `taskId`');
@@ -173,7 +188,7 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             throw new Error(`Unknown protocol operation: ${operation}`);
     }
 }
-async function proposeAgreement(services, payload, chatId, _agents, actingAgentId) {
+async function proposeAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
     if (!payload.description)
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
@@ -187,7 +202,17 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     }
     const priced = applyFleetPricingForProtocol('agreement-propose', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;
-    return services.agreementService.propose({ ...fields, chatId });
+    // Wake-derived idempotency key (delivery law): a crash-replay re-issuing this
+    // propose resolves to the already-created agreement server-side instead of
+    // minting a duplicate proposal. Keyed on what the proposal writes, so
+    // multiple proposals in one wake stay distinct.
+    const idempotencyKey = wakeKeys?.agreementProposeKey({
+        proposedTo: payload.proposedTo,
+        providerId: payload.providerId,
+        description: payload.description,
+        parentAgreementId: payload.parentAgreementId,
+    });
+    return services.agreementService.propose({ ...fields, chatId, idempotencyKey });
 }
 // ── ZIG-832: deterministic sub-agreement resolution ─────────────────────────
 // The orchestrator delegates one task per worker, but the LLM inconsistently
@@ -228,7 +253,7 @@ function agActive(a) {
 function agIsActiveStatus(a) {
     return String(a.status ?? '') === 'active';
 }
-async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId) {
+async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, wakeKeys = null) {
     if (!payload.description || !payload.executorId)
         return null;
     // b1 (ZIG-832): idempotent subcontract — if a non-terminal sub-agreement for
@@ -284,5 +309,14 @@ async function subcontractAgreement(services, payload, chatId, _agents, actingAg
         f.lifecycle = 'count-bound';
         f.maxExecutions = 1;
     }
-    return services.agreementService.delegate({ ...fields, chatId });
+    // Wake-derived idempotency key (delivery law): a crash-replay that slips past
+    // the b1 reuse check above (e.g. no chatId, or the sub not yet visible in the
+    // snapshot) resolves to the already-created sub-agreement server-side instead
+    // of minting a duplicate.
+    const idempotencyKey = wakeKeys?.agreementSubcontractKey({
+        executorId: payload.executorId,
+        description: payload.description,
+        parentAgreementId: payload.parentAgreementId ?? '',
+    });
+    return services.agreementService.delegate({ ...fields, chatId, idempotencyKey });
 }

package/dist/server/tools/tier1/protocolTools.js

@@ -13,7 +13,7 @@ function handlerFor(operation) {
             taskService: c.taskService,
             agreementService: c.agreementService,
             contextReadClient: c.contextReadClient,
-        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null);
+        }, { operation, ...args }, c.chatId ?? null, c.agents ?? [], typeof c.agentId === 'string' ? c.agentId : null, c.wakeKeys ?? null);
         if (result == null)
             throw new Error(`Operation ${operation} returned no result`);
         return result;

package/dist/server/tools/tier2/artifactTools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const recordArtifactTool: ToolDefinition;
+export declare const ARTIFACT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/artifactTools.js

@@ -0,0 +1,82 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { ArtifactsClient } from '@ziggs-ai/api-client';
+/**
+ * ZIG-899 — deliberate artifact recording on the SDK surface, same base name
+ * as ziggs-mcp's ziggs_record_artifact. Until now artifacts were written only
+ * as a host-side effect (recordReport / record-event); the model could not
+ * decide "this is a deliverable, record it" — which is exactly what the
+ * delegate protocol tells agents to do for heavy results. Rides
+ * ArtifactsClient.writeStrict (fail loudly, return the artifactId) — the same
+ * wire call as the MCP tool.
+ */
+function creds(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+/**
+ * ZIG-560 teaching carried over from the MCP tool: name the result slot on the
+ * success path so an agent finds the right move unaided — reworded to the SDK
+ * task grammar (task_update carries the terminal result on this surface).
+ */
+function reportingHint(contentType, taskId) {
+    if (contentType === 'result') {
+        return taskId
+            ? 'Recorded as a task-bound result artifact. Close the task by setting its terminal result with task_update.'
+            : 'Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with task_update.';
+    }
+    return 'Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with task_update — chat messages are conversation only.';
+}
+export const recordArtifactTool = defineTool('record_artifact', {
+    text: { type: 'string', required: true, description: 'Artifact body' },
+    visibility: {
+        type: 'string',
+        required: true,
+        enum: ['chat', 'agent-private'],
+        description: 'chat = visible to scope parties; agent-private = your eyes only',
+    },
+    chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
+    agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
+    taskId: {
+        type: 'string',
+        description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
+    },
+    content_type: { type: 'string', description: 'Default text; use result for a finished deliverable' },
+}, async (args, ctx) => {
+    const chatId = args['chatId'];
+    const agreementId = args['agreementId'];
+    if ((chatId && agreementId) || (!chatId && !agreementId)) {
+        throw new Error('Pass exactly one of chatId or agreementId');
+    }
+    const visibility = args['visibility'];
+    if (visibility !== 'chat' && visibility !== 'agent-private') {
+        throw new Error('visibility must be chat or agent-private');
+    }
+    const contentType = args['content_type'];
+    const taskId = args['taskId'];
+    const { operatorKey, agentId } = creds(ctx);
+    const { artifactId } = await new ArtifactsClient(operatorKey, agentId).writeStrict({
+        text: args['text'],
+        visibility,
+        chatId,
+        agreementId,
+        taskId,
+        content_type: contentType,
+    });
+    return {
+        ok: true,
+        artifactId,
+        visibility,
+        chatId,
+        agreementId,
+        taskId,
+        reportingHint: reportingHint(contentType, taskId),
+    };
+}, {
+    description: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+});
+export const ARTIFACT_TOOLS = [recordArtifactTool];

package/dist/server/tools/tier2/chatTools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const openConversationTool: ToolDefinition;
+export declare const CHAT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/chatTools.js

@@ -0,0 +1,37 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { openConversation } from '@ziggs-ai/api-client';
+/**
+ * ZIG-900 — the decided chat surface for hosted agents: open_conversation
+ * only, same base name as MCP's ziggs_open_conversation. There is deliberately
+ * NO chat-listing tool on the SDK: agents read context only via held grants
+ * (ZIG-425) and chat membership auto-mints a chat grant (ZIG-428/426), so
+ * "what chats can I see" is already answered by list_grants scopeKind=chat —
+ * adding a lister would duplicate a context-family read (ZIG-626 rule).
+ */
+function creds(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+export const openConversationTool = defineTool('open_conversation', {
+    participantId: {
+        type: 'string',
+        required: true,
+        description: 'User or agent id to converse with (from agent_search — do not guess ids)',
+    },
+}, async (args, ctx) => {
+    if (!args['participantId'])
+        throw new Error('participantId is required');
+    const { chatId } = await openConversation(args['participantId'], creds(ctx));
+    return {
+        chatId,
+        note: 'Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in list_grants scopeKind=chat for context reads.',
+    };
+}, {
+    description: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
+});
+export const CHAT_TOOLS = [openConversationTool];

package/dist/server/tools/tier2/connectionTools.d.ts

@@ -1,4 +1,5 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const connectionProxyTool: ToolDefinition;
 export declare const connectionListGrantsTool: ToolDefinition;
+export declare const requestConnectionTool: ToolDefinition;
 export declare const CONNECTION_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/connectionTools.js

@@ -1,13 +1,13 @@
 import { defineTool } from '../../../tools/defineTool.js';
-import { ZiggsConnectClient } from '../../ziggsconnect/ZiggsConnectClient.js';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
 function clientFor(ctx) {
     const operatorKey = ctx?.['operatorKey'];
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    return new ZiggsConnectClient({
-        operatorKey,
-        actAsAgentId: ctx?.['agentId'] || undefined,
-    });
+    // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the shared
+    // client defaults to HTTP_URL (api-client convention) when neither is set.
+    const baseUrl = process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined;
+    return new ConnectionsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
 }
 function rethrowWithContext(error, prefix) {
     const e = error;
@@ -57,7 +57,54 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', { c
         rethrowWithContext(e, 'Failed to list connection grants');
     }
 });
+export const requestConnectionTool = defineTool('request_connection', {
+    chatId: {
+        type: 'string',
+        required: true,
+        description: 'The chat you are working in — the consent card is opened there',
+    },
+    serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
+    tools: {
+        type: 'array',
+        items: { type: 'string' },
+        required: true,
+        description: "Tool names you want — become the grant's allowed_actions caveats",
+    },
+    reason: {
+        type: 'string',
+        description: 'Plain-language reason shown to the human deciding',
+    },
+}, async (args, ctx) => {
+    if (!args['chatId'])
+        throw new Error('chatId is required');
+    if (!args['serverUrl'])
+        throw new Error('serverUrl is required');
+    const tools = args['tools'];
+    if (!Array.isArray(tools) || tools.length === 0) {
+        throw new Error('tools must be a non-empty array of tool names');
+    }
+    try {
+        const result = await clientFor(ctx).requestMcpConnection({
+            chatId: args['chatId'],
+            serverUrl: args['serverUrl'],
+            tools: tools,
+            reason: args['reason'],
+        });
+        return {
+            ok: true,
+            ...result,
+            note: 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
+                'Once approved, the connection + grant appear in list_grants (scopeKind=connection) / connection_list_grants for connection_proxy.',
+        };
+    }
+    catch (e) {
+        rethrowWithContext(e, 'Connection request failed');
+    }
+}, {
+    description: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. On approval the server is connected (browser OAuth if needed) and you are granted the tools; use them via connection_proxy.',
+});
 export const CONNECTION_TOOLS = [
     connectionProxyTool,
     connectionListGrantsTool,
+    requestConnectionTool,
 ];

package/dist/server/tools/tier2/contextTools.d.ts

@@ -1,4 +1,6 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
-export declare const contextDiscoverTool: ToolDefinition;
+export declare const contextReadTool: ToolDefinition;
 export declare const contextDelegateTool: ToolDefinition;
-export declare const CONTEXT_TOOLS: readonly [ToolDefinition, ToolDefinition];
+export declare const contextExpandReachTool: ToolDefinition;
+export declare const contextDiscoverGrantableTool: ToolDefinition;
+export declare const CONTEXT_TOOLS: readonly [ToolDefinition, ToolDefinition, ToolDefinition, ToolDefinition];

package/dist/server/tools/tier2/contextTools.js

@@ -1,16 +1,78 @@
 import { defineTool } from '../../../tools/defineTool.js';
-import { ZiggsContextClient } from '../../ziggscontext/ZiggsContextClient.js';
-function clientFor(ctx) {
+import { ContextDiscoveryClient, ContextGrantsClient, ContextReadClient, } from '@ziggs-ai/api-client';
+/**
+ * Context grant calls impersonate the grant holder, so both operatorKey (fleet
+ * or agent-scoped key) and agentId (X-Agent-Id) must be on the tool context.
+ * The same api-client clients back ziggs-mcp — one wire contract, no fork
+ * (ZIG-869 / ZIG-775).
+ */
+function creds(ctx) {
     const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    return new ZiggsContextClient({
-        operatorKey,
-        actAsAgentId: ctx?.['agentId'] || undefined,
-    });
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
 }
-export const contextDiscoverTool = defineTool('context_discover', {}, async (_args, ctx) => clientFor(ctx).discover(), {
-    description: 'List every context grant this agent holds, as scope descriptors — grantId, scope, temporal, watermarkAt, expiresAt (no message or artifact content).',
+const CONTEXT_READ_TYPES = [
+    'messages',
+    'artifacts',
+    'agreements',
+    'tasks',
+];
+export const contextReadTool = defineTool('context_read', {
+    type: {
+        type: 'string',
+        required: true,
+        enum: [...CONTEXT_READ_TYPES],
+        description: 'Resource type to read from the scope',
+    },
+    via: {
+        type: 'string',
+        required: true,
+        description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>',
+    },
+    cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
+    after: {
+        type: 'string',
+        description: 'ISO timestamp for forward-delta (messages/artifacts)',
+    },
+    direction: {
+        type: 'string',
+        enum: ['forward'],
+        description: 'Use "forward" with after for a message forward-delta',
+    },
+    limit: { type: 'number', description: 'Page size (server default when omitted)' },
+    state: { type: 'string', description: 'Task state filter (tasks only)' },
+    contextGrantId: {
+        type: 'string',
+        description: 'Pin a specific grant when you hold several over the same scope',
+    },
+}, async (args, ctx) => {
+    const { operatorKey, agentId } = creds(ctx);
+    const type = args['type'];
+    if (!CONTEXT_READ_TYPES.includes(type)) {
+        throw new Error(`type must be one of ${CONTEXT_READ_TYPES.join(', ')}`);
+    }
+    const via = args['via'];
+    if (!via)
+        throw new Error('via is required');
+    const direction = args['direction'];
+    if (direction !== undefined && direction !== 'forward') {
+        throw new Error('direction must be "forward"');
+    }
+    return new ContextReadClient(operatorKey, agentId).read(type, {
+        via,
+        cursor: args['cursor'],
+        after: args['after'],
+        direction: direction,
+        limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+        state: args['state'],
+        contextGrantId: args['contextGrantId'],
+    });
+}, {
+    description: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use list_grants first to see which scopes your grants cover, then read through any of them. Cursored; all access is grant-fenced server-side.',
 });
 export const contextDelegateTool = defineTool('context_delegate', {
     parentGrantId: { type: 'string', required: true },
@@ -29,8 +91,8 @@ export const contextDelegateTool = defineTool('context_delegate', {
     if (scopeKind !== 'chat' && scopeKind !== 'agreement' && scopeKind !== 'org') {
         throw new Error('scopeKind must be chat, agreement, or org');
     }
-    return clientFor(ctx).delegate({
-        parentGrantId: args['parentGrantId'],
+    const { operatorKey, agentId } = creds(ctx);
+    return new ContextGrantsClient(operatorKey, agentId).delegateGrant(args['parentGrantId'], {
         holderId: args['holderId'],
         scope: { kind: scopeKind, id: args['scopeId'] },
         temporal,
@@ -38,9 +100,40 @@ export const contextDelegateTool = defineTool('context_delegate', {
         watermarkAt: args['watermarkAt'],
     });
 }, {
-    description: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only.',
+    description: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval).',
+});
+export const contextExpandReachTool = defineTool('context_expand_reach', {
+    grantId: {
+        type: 'string',
+        required: true,
+        description: 'A grant you hold (grantId from list_grants) to expand',
+    },
+}, async (args, ctx) => {
+    const { operatorKey, agentId } = creds(ctx);
+    const grantId = args['grantId'];
+    if (!grantId)
+        throw new Error('grantId is required');
+    return new ContextGrantsClient(operatorKey, agentId).getReach(grantId);
+}, {
+    description: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+});
+// ZIG-754 — the negative-space complement to the reach tools. list_grants /
+// context_expand_reach answer "what CAN I read?"; this answers "what exists
+// just outside my fence that I CAN'T read yet?" so the agent can flag missing
+// context and make an informed widen request instead of silently
+// under-delivering on partial context. The MCP surface has had this as
+// ziggs_discover_grantable; this is its SDK/legibility complement, backed by
+// the same ContextDiscoveryClient (one wire contract, no fork).
+export const contextDiscoverGrantableTool = defineTool('context_discover_grantable', {}, async (_args, ctx) => {
+    const { operatorKey, agentId } = creds(ctx);
+    const items = await new ContextDiscoveryClient(operatorKey, agentId).discoverGrantable();
+    return { count: items.length, items };
+}, {
+    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
 });
 export const CONTEXT_TOOLS = [
-    contextDiscoverTool,
+    contextReadTool,
     contextDelegateTool,
+    contextExpandReachTool,
+    contextDiscoverGrantableTool,
 ];

package/dist/server/tools/tier2/grantsTools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const listGrantsTool: ToolDefinition;
+export declare const GRANTS_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/grantsTools.js

@@ -0,0 +1,81 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { GrantsClient, unreadableGrantRails, } from '@ziggs-ai/api-client';
+/**
+ * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
+ * (context chat/agreement/org, connection, wallet), holder-scoped, cross-session.
+ * Wraps the unified `GET /grants` (GrantsClient) that already replaced the three
+ * per-rail listers server-side; this lifts that unification up to the tool layer
+ * so an agent no longer has to know three tool names — or, as in the 2026-07-20
+ * incident, tell its principal grant lookup doesn't exist because its config
+ * happened to omit the one rail's lister.
+ */
+function creds(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+const SCOPE_KINDS = [
+    'chat',
+    'agreement',
+    'org',
+    'connection',
+    'wallet',
+];
+const HEALTHS = ['active', 'expired', 'revoked'];
+function parseScopeKinds(raw) {
+    if (raw == null)
+        return undefined;
+    const list = Array.isArray(raw) ? raw : [raw];
+    const out = [];
+    for (const r of list) {
+        if (!SCOPE_KINDS.includes(r)) {
+            throw new Error(`scopeKind must be one of ${SCOPE_KINDS.join(', ')}`);
+        }
+        if (!out.includes(r))
+            out.push(r);
+    }
+    return out.length ? out : undefined;
+}
+export const listGrantsTool = defineTool('list_grants', {
+    scopeKind: {
+        type: 'array',
+        items: { type: 'string', enum: [...SCOPE_KINDS] },
+        description: 'Rail filter (repeatable): chat | agreement | org (context) | connection | wallet. Omit for every rail you can read.',
+    },
+    health: {
+        type: 'string',
+        enum: [...HEALTHS],
+        description: 'Grant health filter. Defaults to active (live grants only).',
+    },
+    cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
+    limit: { type: 'number', description: 'Page size (server default when omitted)' },
+}, async (args, ctx) => {
+    const { operatorKey, agentId } = creds(ctx);
+    const scopeKind = parseScopeKinds(args['scopeKind']);
+    const healthArg = args['health'];
+    if (healthArg !== undefined && !HEALTHS.includes(healthArg)) {
+        throw new Error(`health must be one of ${HEALTHS.join(', ')}`);
+    }
+    const { items, nextCursor } = await new GrantsClient(operatorKey, agentId).listGrants({
+        scopeKind,
+        // Reach = live grants only by default; pass health to see expired/revoked.
+        health: healthArg ?? 'active',
+        cursor: args['cursor'],
+        limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+    });
+    const unreadable = unreadableGrantRails(operatorKey, scopeKind);
+    return {
+        count: items.length,
+        grants: items,
+        nextCursor,
+        ...(unreadable && unreadable.length ? { unreadableRails: unreadable } : {}),
+    };
+}, {
+    description: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
+    isGenericFallback: true,
+});
+export const GRANTS_TOOLS = [listGrantsTool];

package/dist/server/tools/tier2/linkTools.d.ts

@@ -0,0 +1,7 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const requestLinkTool: ToolDefinition;
+export declare const createLinkInviteTool: ToolDefinition;
+export declare const claimLinkInviteTool: ToolDefinition;
+export declare const listLinksTool: ToolDefinition;
+export declare const revokeLinkTool: ToolDefinition;
+export declare const LINK_TOOLS: ToolDefinition[];