@ziggs-ai/api-client 0.3.1 → 0.4.0

package/dist/capabilities/artifacts.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const recordArtifactCapability: CapabilityDefinition;
+export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -0,0 +1,86 @@
+import { ArtifactsClient } from '../http/ArtifactsClient.js';
+import { fullCreds } from './types.js';
+/**
+ * ZIG-560 teaching: name the result slot on the success path so an agent finds
+ * the right move unaided — worded in each surface's task grammar (SDK
+ * task_update carries the terminal result; MCP has ziggs_set_task_result).
+ */
+function reportingHint(env, contentType, taskId) {
+    const close = env.surface === 'mcp'
+        ? 'ziggs_set_task_result ({ summary, status, links })'
+        : 'task_update';
+    if (contentType === 'result') {
+        return taskId
+            ? `Recorded as a task-bound result artifact. Close the task by setting its terminal result with ${close}.`
+            : `Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with ${close}.`;
+    }
+    return `Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
+}
+export const recordArtifactCapability = {
+    key: 'record_artifact',
+    names: { sdk: 'record_artifact', mcp: 'ziggs_record_artifact' },
+    descriptions: {
+        sdk: '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.',
+        mcp: '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. ' +
+            'Finished work is the task result — set it with ziggs_set_task_result; never report finished work as a chat message (chat is conversation only).',
+    },
+    annotation: 'write',
+    params: {
+        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',
+        },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        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 creds = fullCreds(env);
+        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({
+            text: args['text'],
+            visibility,
+            chatId,
+            agreementId,
+            taskId,
+            content_type: contentType,
+            idempotencyKey: args['idempotencyKey'],
+        });
+        return {
+            ok: true,
+            artifactId,
+            visibility,
+            chatId,
+            agreementId,
+            taskId,
+            reportingHint: reportingHint(env, contentType, taskId),
+        };
+    },
+};
+export const ARTIFACT_CAPABILITIES = [recordArtifactCapability];

package/dist/capabilities/chat.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * 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 (ZIG-626 rule). MCP keeps its rich session-UX lister
+ * (ziggs_list_chats) for humans in Cursor/Claude.
+ */
+export declare const openConversationCapability: CapabilityDefinition;
+export declare const CHAT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/chat.js

@@ -0,0 +1,38 @@
+import { openConversation } from '../http/ChatClient.js';
+import { fullCreds } from './types.js';
+/**
+ * ZIG-900 — the decided chat surface for agents: open_conversation only.
+ * 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 (ZIG-626 rule). MCP keeps its rich session-UX lister
+ * (ziggs_list_chats) for humans in Cursor/Claude.
+ */
+export const openConversationCapability = {
+    key: 'open_conversation',
+    names: { sdk: 'open_conversation', mcp: 'ziggs_open_conversation' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — call ziggs_request_link (if you have its agent id) or ziggs_create_link_invite (if you do not) and have it approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.',
+    },
+    annotation: 'write',
+    params: {
+        participantId: {
+            type: 'string',
+            required: true,
+            description: 'User or agent id to converse with (from agent search — do not guess ids)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['participantId'])
+            throw new Error('participantId is required');
+        const { chatId } = await openConversation(args['participantId'], fullCreds(env));
+        const lister = env.surface === 'mcp' ? 'ziggs_list_grants' : 'list_grants';
+        return {
+            chatId,
+            note: `Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`,
+        };
+    },
+};
+export const CHAT_CAPABILITIES = [openConversationCapability];

package/dist/capabilities/connections.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const connectionProxyCapability: CapabilityDefinition;
+export declare const requestConnectionCapability: CapabilityDefinition;
+export declare const CONNECTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/connections.js

@@ -0,0 +1,112 @@
+import { ConnectionsClient } from '../http/ConnectionsClient.js';
+import { rethrowWithContext, } from './types.js';
+function client(env) {
+    const { operatorKey, agentId } = env.creds;
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    return new ConnectionsClient(operatorKey, agentId, env.baseUrl);
+}
+export const connectionProxyCapability = {
+    key: 'connection_proxy',
+    names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
+    descriptions: {
+        sdk: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira) without ever seeing the credential. Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. Don't know connectionId/grantId yet? Use list_grants (scopeKind=connection) or connection_list_grants first.",
+        mcp: "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_list_links for that) without ever seeing the credential. " +
+            'Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). ' +
+            'Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. ' +
+            "Don't know connectionId/grantId yet? Call ziggs_list_my_connections first.",
+    },
+    annotation: 'write',
+    params: {
+        connectionId: { type: 'string', required: true, description: 'Connection to act on' },
+        grantId: {
+            type: 'string',
+            required: true,
+            description: 'Grant the owner issued to this agent for the connection',
+        },
+        action: { type: 'string', required: true, description: 'Provider action, e.g. repo:read' },
+        payload: { type: 'object', description: 'Action-specific arguments (provider-defined)' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['connectionId'])
+            throw new Error('connectionId is required');
+        if (!args['grantId'])
+            throw new Error('grantId is required');
+        if (!args['action'])
+            throw new Error('action is required');
+        try {
+            const result = await client(env).proxy({
+                connectionId: args['connectionId'],
+                grantId: args['grantId'],
+                action: args['action'],
+                payload: args['payload'],
+            });
+            return { ok: true, action: args['action'], result };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Connection proxy failed');
+        }
+    },
+};
+export const requestConnectionCapability = {
+    key: 'request_connection',
+    names: { sdk: 'request_connection', mcp: 'ziggs_request_connection' },
+    descriptions: {
+        sdk: '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.',
+        mcp: '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 (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
+            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_list_my_connections for use with ziggs_connection_proxy.',
+    },
+    annotation: 'write',
+    params: {
+        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' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        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 client(env).requestMcpConnection({
+                chatId: args['chatId'],
+                serverUrl: args['serverUrl'],
+                tools: tools,
+                reason: args['reason'],
+            });
+            return {
+                ok: true,
+                ...result,
+                note: env.surface === 'mcp'
+                    ? 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
+                        'Once approved, the connection + grant appear in ziggs_list_my_connections for ziggs_connection_proxy.'
+                    : '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');
+        }
+    },
+};
+export const CONNECTION_CAPABILITIES = [
+    connectionProxyCapability,
+    requestConnectionCapability,
+];

package/dist/capabilities/context.d.ts

@@ -0,0 +1,23 @@
+import { type GrantView } from '../http/grants.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+/**
+ * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
+ * grant's temporal mode + read watermark into the canonical `caveats` array,
+ * so pull them back out here to keep the `bounds` summary stable.
+ */
+export declare function contextBounds(grant: GrantView): Record<string, unknown>;
+/**
+ * ZIG-941 #6 — org-scoped grants may name the org instead of pasting its
+ * opaque org_... id: exact id or case-insensitive name against the operator's
+ * memberships. Ambiguous names throw with the candidate list rather than
+ * guessing; a name that matched nothing throws with a pointer to the org
+ * lister. An org_... id that is not a membership passes through unchanged —
+ * you may hold a grant on an org you do not belong to, so the server stays
+ * the authority on the id.
+ */
+export declare function resolveOrgScopeId(env: CapabilityEnv, scopeId: string): Promise<string>;
+export declare const contextReadCapability: CapabilityDefinition;
+export declare const contextExpandReachCapability: CapabilityDefinition;
+export declare const contextDiscoverGrantableCapability: CapabilityDefinition;
+export declare const contextDelegateCapability: CapabilityDefinition;
+export declare const CONTEXT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/context.js

@@ -0,0 +1,220 @@
+import { ContextReadClient } from '../http/ContextReadClient.js';
+import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
+import { ContextDiscoveryClient } from '../http/ContextDiscoveryClient.js';
+import { grantCaveat } from '../http/grants.js';
+import { fetchMyOrgs, resolveOrgSelector } from '../http/OrgsClient.js';
+import { fullCreds } from './types.js';
+const CONTEXT_READ_TYPES = [
+    'messages',
+    'artifacts',
+    'agreements',
+    'tasks',
+];
+const GRANT_SCOPE_KINDS = ['chat', 'agreement', 'org'];
+const CONTEXT_TEMPORALS = ['from-now', 'from-start'];
+/**
+ * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
+ * grant's temporal mode + read watermark into the canonical `caveats` array,
+ * so pull them back out here to keep the `bounds` summary stable.
+ */
+export function contextBounds(grant) {
+    return {
+        temporal: grantCaveat(grant, 'temporal'),
+        watermarkAt: grantCaveat(grant, 'watermark_at'),
+        expiresAt: grant.expiresAt,
+    };
+}
+/**
+ * ZIG-941 #6 — org-scoped grants may name the org instead of pasting its
+ * opaque org_... id: exact id or case-insensitive name against the operator's
+ * memberships. Ambiguous names throw with the candidate list rather than
+ * guessing; a name that matched nothing throws with a pointer to the org
+ * lister. An org_... id that is not a membership passes through unchanged —
+ * you may hold a grant on an org you do not belong to, so the server stays
+ * the authority on the id.
+ */
+export async function resolveOrgScopeId(env, scopeId) {
+    const resolution = resolveOrgSelector(await fetchMyOrgs(fullCreds(env), env.baseUrl), scopeId);
+    if (resolution.status === 'ok')
+        return resolution.orgId;
+    if (resolution.status === 'ambiguous') {
+        throw new Error(`Org name "${scopeId}" matches ${resolution.matches.length} of your orgs — pass the org id: ` +
+            resolution.matches.map((m) => `${m.name} (${m.orgId})`).join(', '));
+    }
+    if (scopeId.startsWith('org_'))
+        return scopeId;
+    const lister = env.surface === 'mcp' ? 'ziggs_list_my_orgs' : 'your org list';
+    throw new Error(`No org named "${scopeId}" in your memberships — use ${lister} to see them, or pass the org id.`);
+}
+export const contextReadCapability = {
+    key: 'context_read',
+    names: { sdk: 'context_read', mcp: 'ziggs_read_context' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist (your chats / tasks / agreements / grants / links), use the ziggs_list_* tools.',
+    },
+    annotation: 'read-only',
+    params: {
+        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',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        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(creds.operatorKey, creds.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'],
+        });
+    },
+};
+export const contextExpandReachCapability = {
+    key: 'context_expand_reach',
+    names: { sdk: 'context_expand_reach', mcp: 'ziggs_expand_context' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_read_context (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+    },
+    annotation: 'read-only',
+    params: {
+        grantId: {
+            type: 'string',
+            required: true,
+            description: 'A grant you hold (grantId from the grant lister) to expand',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const grantId = args['grantId'];
+        if (!grantId)
+            throw new Error('grantId is required');
+        return new ContextGrantsClient(creds.operatorKey, creds.agentId).getReach(grantId);
+    },
+};
+export const contextDiscoverGrantableCapability = {
+    key: 'context_discover_grantable',
+    names: { sdk: 'context_discover_grantable', mcp: 'ziggs_discover_grantable' },
+    descriptions: {
+        sdk: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). 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).',
+        mcp: 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). 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. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_delegate_grant using the scopeRef. Use ziggs_list_grants for what you already hold; this is what you lack.',
+    },
+    annotation: 'read-only',
+    params: {},
+    needsAgentId: true,
+    handler: async (_args, env) => {
+        const creds = fullCreds(env);
+        const items = await new ContextDiscoveryClient(creds.operatorKey, creds.agentId).discoverGrantable();
+        return { count: items.length, items };
+    },
+};
+export const contextDelegateCapability = {
+    key: 'context_delegate',
+    names: { sdk: 'context_delegate', mcp: 'ziggs_delegate_grant' },
+    descriptions: {
+        sdk: '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).',
+        mcp: 'Delegate a narrower child grant from one you hold (POST /context/grants/:id/delegate). Delegation only narrows scope/expiry/temporal — never broadens. If the grant\'s original owner is a different party, this does NOT grant — it opens a request that owner must approve, and returns { status: "pending_approval", agreementId }; surface that to the human and do not treat it as done.',
+    },
+    annotation: 'write',
+    params: {
+        parentGrantId: { type: 'string', required: true },
+        holderId: { type: 'string', required: true, description: 'Agent receiving the delegated grant' },
+        scopeKind: { type: 'string', required: true, enum: GRANT_SCOPE_KINDS },
+        scopeId: { type: 'string', required: true },
+        temporal: {
+            type: 'string',
+            required: true,
+            enum: CONTEXT_TEMPORALS,
+            description: 'from-now or from-start (must be same-or-narrower)',
+        },
+        expiresAt: { type: 'string' },
+        watermarkAt: {
+            type: 'string',
+            description: 'from-now watermark ISO-8601 (optional; server may default)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const temporal = args['temporal'];
+        if (!CONTEXT_TEMPORALS.includes(temporal)) {
+            throw new Error('temporal must be from-now or from-start');
+        }
+        const scopeKind = args['scopeKind'];
+        if (!GRANT_SCOPE_KINDS.includes(scopeKind)) {
+            throw new Error('scopeKind must be chat, agreement, or org');
+        }
+        // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
+        let scopeId = args['scopeId'];
+        if (scopeKind === 'org') {
+            scopeId = await resolveOrgScopeId(env, scopeId);
+        }
+        const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
+        const result = await client.delegateGrant(args['parentGrantId'], {
+            holderId: args['holderId'],
+            scope: { kind: scopeKind, id: scopeId },
+            temporal: temporal,
+            expiresAt: args['expiresAt'] ?? undefined,
+            watermarkAt: args['watermarkAt'],
+        });
+        if (result.status === 'pending_approval') {
+            return {
+                status: 'pending_approval',
+                message: "This grant's original owner must approve sharing it. A request was opened for them — surface it to the human; nothing is granted yet.",
+                parentGrantId: args['parentGrantId'],
+                agreementId: result.agreementId,
+                ownerId: result.ownerId,
+            };
+        }
+        const grant = result.grant;
+        return {
+            status: 'delegated',
+            parentGrantId: args['parentGrantId'],
+            grant,
+            bounds: contextBounds(grant),
+        };
+    },
+};
+export const CONTEXT_CAPABILITIES = [
+    contextReadCapability,
+    contextDelegateCapability,
+    contextExpandReachCapability,
+    contextDiscoverGrantableCapability,
+];

package/dist/capabilities/discovery.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const agentSearchCapability: CapabilityDefinition;
+export declare const agentGetCapability: CapabilityDefinition;
+export declare const DISCOVERY_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/discovery.js

@@ -0,0 +1,77 @@
+import { AgentSearchClient } from '../http/AgentSearchClient.js';
+import { fullCreds } from './types.js';
+export const agentSearchCapability = {
+    key: 'agent_search',
+    names: { sdk: 'agent_search', mcp: 'ziggs_search_agents' },
+    descriptions: {
+        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with. Passing an EXACT agent id resolves that one agent even if unpublished/private. Use before agreement_propose or agreement_subcontract to discover the right agent for a job; use returned agentId in grant/issue tools — do not guess ids.',
+        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.',
+    },
+    annotation: 'read-only',
+    params: {
+        query: {
+            type: 'string',
+            required: true,
+            description: 'Keyword/natural-language search (published store + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)',
+        },
+        limit: { type: 'number', description: 'Max results (default server-side)' },
+        minScore: { type: 'number', description: 'Minimum match score filter' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['query'])
+            throw new Error('query is required');
+        const creds = fullCreds(env);
+        const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
+        const result = await client.searchAgents(args['query'], {
+            limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+            minScore: typeof args['minScore'] === 'number' ? args['minScore'] : undefined,
+        });
+        if (!result.success) {
+            throw new Error(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 {
+                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 { count: result.agents.length, agents: result.agents };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const agentGetCapability = {
+    key: 'agent_get',
+    names: { sdk: 'agent_get', mcp: 'ziggs_get_agent' },
+    descriptions: {
+        sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, and reliability. Use to confirm capabilities and terms before proposing an agreement, when you already hold the agent id. An id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use agent_search.',
+        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_propose_agreement / ziggs_request_link, when you already hold the agent id (from ziggs_search_agents, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_search_agents.',
+    },
+    annotation: 'read-only',
+    params: {
+        agentId: { type: 'string', required: true, description: 'Exact agent id to fetch — do not guess' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        if (!args['agentId'])
+            throw new Error('agentId is required');
+        const creds = fullCreds(env);
+        const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
+        const result = await client.getAgentById(args['agentId']);
+        if (!result.success) {
+            throw new Error(result.error ?? 'agent not found');
+        }
+        const { success: _success, ...agent } = result;
+        return { agent };
+    },
+};
+export const DISCOVERY_CAPABILITIES = [
+    agentSearchCapability,
+    agentGetCapability,
+];

package/dist/capabilities/grants.d.ts

@@ -0,0 +1,9 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
+ * (context chat/agreement/org, connection, wallet), holder-scoped,
+ * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
+ * list is never presented as complete when the key can't read a rail.
+ */
+export declare const listGrantsCapability: CapabilityDefinition;
+export declare const GRANTS_CAPABILITIES: CapabilityDefinition[];