@ziggs-ai/api-client 0.3.0 → 0.4.0

package/dist/capabilities/grants.js

@@ -0,0 +1,77 @@
+import { GrantsClient } from '../http/GrantsClient.js';
+import { fullCreds } from './types.js';
+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;
+}
+/**
+ * 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 const listGrantsCapability = {
+    key: 'list_grants',
+    names: { sdk: 'list_grants', mcp: 'ziggs_list_grants' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no 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 to page. Pass a grantId to ziggs_read_context to pin a specific grant, or ziggs_expand_context to enumerate a scope.',
+    },
+    annotation: 'read-only',
+    params: {
+        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)' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        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, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).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,
+        });
+        return {
+            count: items.length,
+            grants: items,
+            nextCursor,
+            ...(unreadableRails?.length ? { unreadableRails } : {}),
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const GRANTS_CAPABILITIES = [listGrantsCapability];

package/dist/capabilities/index.d.ts

@@ -0,0 +1,9 @@
+export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
+export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
+export { LINK_CAPABILITIES, requestLinkCapability, createLinkInviteCapability, claimLinkInviteCapability, listLinksCapability, revokeLinkCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
+export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -0,0 +1,9 @@
+export { fullCreds, rethrowWithContext, } from './types.js';
+export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
+export { LINK_CAPABILITIES, requestLinkCapability, createLinkInviteCapability, claimLinkInviteCapability, listLinksCapability, revokeLinkCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
+export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/links.d.ts

@@ -0,0 +1,17 @@
+import type { Agreement } from '../types.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+/**
+ * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
+ * block, approvals array, and Mongo internals are noise on a trust
+ * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
+ * return it too (they used to leak the raw agreement doc).
+ */
+export declare function linkSummary(a: Agreement): Record<string, unknown>;
+/** A link is reach-only — the follow-up move differs by surface tool names. */
+export declare function linkIsReachOnly(env: CapabilityEnv): string;
+export declare const requestLinkCapability: CapabilityDefinition;
+export declare const createLinkInviteCapability: CapabilityDefinition;
+export declare const claimLinkInviteCapability: CapabilityDefinition;
+export declare const listLinksCapability: CapabilityDefinition;
+export declare const revokeLinkCapability: CapabilityDefinition;
+export declare const LINK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/links.js

@@ -0,0 +1,193 @@
+import { createAgreement, claimAgreement, listAgreements, revokeAgreement, } from '../http/AgreementClient.js';
+import { fullCreds } from './types.js';
+const DEFAULT_WEB_URL = 'https://ziggsai.com';
+function webAppOrigin(env) {
+    return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
+}
+/**
+ * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
+ * block, approvals array, and Mongo internals are noise on a trust
+ * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
+ * return it too (they used to leak the raw agreement doc).
+ */
+export function linkSummary(a) {
+    return {
+        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,
+    };
+}
+/** A link is reach-only — the follow-up move differs by surface tool names. */
+export function linkIsReachOnly(env) {
+    return env.surface === 'mcp'
+        ? 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.'
+        : 'A link is reach-only: it does not grant context. Share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one, before reading.';
+}
+const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
+export const requestLinkCapability = {
+    key: 'request_link',
+    names: { sdk: 'request_link', mcp: 'ziggs_request_link' },
+    descriptions: {
+        sdk: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — that is the connection rail). A link is just an agreement (engagementKind "link"). The target OWNER must approve it before unpublished delegates can message each other.',
+        mcp: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — see ziggs_list_my_connections for that). A link is just an agreement (POST /agreements {engagementKind:"link"}). The target OWNER must approve it (via ziggs_respond_to_agreement) before unpublished delegates can message each other.',
+    },
+    annotation: 'write',
+    params: {
+        providerId: {
+            type: 'string',
+            required: true,
+            description: 'Bare agent id to link with (the target delegate). Use agent search or a known delegate id — do not guess.',
+        },
+        message: {
+            type: 'string',
+            description: 'Optional note shown to the counterparty human on approval (agreement description)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await createAgreement({
+            engagementKind: 'link',
+            providerId: args['providerId'],
+            description: args['message'],
+        }, fullCreds(env));
+        return {
+            status: 'pending',
+            message: env.surface === 'mcp'
+                ? 'Link agreement created — the counterparty owner must approve (ziggs_respond_to_agreement) before cross-org reach. Surface pending state to the human.'
+                : 'Link agreement created — the counterparty owner must approve (agreement_respond on their side) before cross-org reach. Surface pending state to your principal.',
+            agreement: linkSummary(agreement),
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const createLinkInviteCapability = {
+    key: 'create_link_invite',
+    names: { sdk: 'create_link_invite', mcp: 'ziggs_create_link_invite' },
+    descriptions: {
+        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId.",
+        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_claim_link_invite — neither side pastes an agent id. Revoke via ziggs_revoke_link to disable.',
+    },
+    annotation: 'write',
+    params: {
+        message: {
+            type: 'string',
+            description: 'Optional note shown to whoever opens the invite (agreement description)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await createAgreement({ engagementKind: 'link', description: args['message'] }, fullCreds(env));
+        return {
+            status: 'open',
+            inviteId: agreement.agreementId,
+            claimUrl: `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`,
+            message: env.surface === 'mcp'
+                ? 'Open link invite created. Share claimUrl with the counterparty — they open it in the Ziggs web app to claim and activate the link. No agent id needed on either side.'
+                : 'Open link invite created. Share claimUrl (or the inviteId) with the counterparty — they claim it in the Ziggs web app or via their claim_link_invite tool. No agent id needed on either side. Revoke with revoke_link to disable.',
+            agreement: linkSummary(agreement),
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const claimLinkInviteCapability = {
+    key: 'claim_link_invite',
+    names: { sdk: 'claim_link_invite', mcp: 'ziggs_claim_link_invite' },
+    descriptions: {
+        sdk: 'Claim an open link invite by its id to form a bilateral link. You become the counterparty and the link activates immediately (cross-org reach). You cannot claim your own invite.',
+        mcp: 'Claim an open link invite by its id to form a bilateral link (agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) (POST /agreements/:id/claim). You become the counterparty and the link activates immediately (cross-org reach + bilateral context grants). You cannot claim your own invite.',
+    },
+    annotation: 'write',
+    params: {
+        agreementId: {
+            type: 'string',
+            required: true,
+            description: 'The invite id (agreementId) shared by the issuer',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await claimAgreement(args['agreementId'], fullCreds(env));
+        return {
+            status: 'linked',
+            message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
+            agreement: linkSummary(agreement),
+        };
+    },
+};
+export const listLinksCapability = {
+    key: 'list_links',
+    names: { sdk: 'list_links', mcp: 'ziggs_list_links' },
+    descriptions: {
+        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (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.',
+        mcp: '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.',
+    },
+    annotation: 'read-only',
+    params: {
+        status: {
+            type: 'string',
+            enum: LINK_STATUSES,
+            description: 'active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const status = args['status'] ?? 'active';
+        if (!LINK_STATUSES.includes(status)) {
+            throw new Error('status must be one of active, open, cancelled, all');
+        }
+        const links = await listAgreements({
+            engagementKind: 'link',
+            ...(status === 'all' ? {} : { status }),
+        }, fullCreds(env));
+        const summaries = links.map(linkSummary);
+        const hasActive = links.some((a) => a.status === 'active');
+        return {
+            count: summaries.length,
+            status,
+            links: summaries,
+            ...(hasActive ? { nextSteps: linkIsReachOnly(env) } : {}),
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const revokeLinkCapability = {
+    key: 'revoke_link',
+    names: { sdk: 'revoke_link', mcp: 'ziggs_revoke_link' },
+    descriptions: {
+        sdk: 'Revoke a bilateral link agreement (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use agreement_revoke — same endpoint, different messaging.',
+        mcp: 'Revoke a bilateral link agreement — agent-to-agent trust, NOT a third-party service connection (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use ziggs_revoke_agreement — same endpoint, different messaging.',
+    },
+    annotation: 'destructive',
+    params: {
+        agreementId: {
+            type: 'string',
+            required: true,
+            description: 'agreementId of the link agreement (from the link lister)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const result = await revokeAgreement(args['agreementId'], fullCreds(env));
+        return {
+            status: 'revoked',
+            message: 'Link revoked — unpublished cross-org reach to this peer is blocked again.',
+            agreementId: args['agreementId'],
+            agreement: result.agreement ? linkSummary(result.agreement) : null,
+        };
+    },
+};
+export const LINK_CAPABILITIES = [
+    requestLinkCapability,
+    createLinkInviteCapability,
+    claimLinkInviteCapability,
+    listLinksCapability,
+    revokeLinkCapability,
+];

package/dist/capabilities/payments.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const paymentBalanceCapability: CapabilityDefinition;
+export declare const paymentResolveWalletCapability: CapabilityDefinition;
+export declare const paymentTransferCapability: CapabilityDefinition;
+export declare const paymentWaitForApprovalCapability: CapabilityDefinition;
+export declare const paymentHoldCapability: CapabilityDefinition;
+export declare const paymentReleaseCapability: CapabilityDefinition;
+export declare const paymentIssueGrantCapability: CapabilityDefinition;
+export declare const paymentAttenuateGrantCapability: CapabilityDefinition;
+export declare const paymentRevokeGrantCapability: CapabilityDefinition;
+export declare const PAYMENT_CAPABILITIES: CapabilityDefinition[];