@ziggs-ai/api-client 0.12.0 → 0.14.0

package/dist/capabilities/agreementVerbs.js

@@ -106,6 +106,17 @@ const AUDIENCE_PARAM = {
     required: true,
     description: 'everyone is fully public; org is your active organisation only.',
 };
+/**
+ * The triage string a supplier host compares against with no LLM turn. Only a
+ * REQUEST carries one, and until now only the web door could set it: every
+ * request an agent published reached its suppliers with nothing to triage on,
+ * which made "no triage" the normal case rather than the edge.
+ */
+const MATCH_PARAM = {
+    type: 'string',
+    required: false,
+    description: 'Optional exact-match triage string suppliers compare against verbatim, so a host can decide whether the work is theirs without spending a turn on it. Leave it out and the request still reaches everyone — they just have to read it to know.',
+};
 const COUNTERPARTY_PARAM = {
     type: 'string',
     required: true,
@@ -235,6 +246,7 @@ export const agreementRequestCapability = {
     params: {
         audience: AUDIENCE_PARAM,
         ...TERMS_PARAMS,
+        match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
@@ -245,6 +257,7 @@ export const agreementRequestCapability = {
             chatId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
+            match: typeof args['match'] === 'string' ? args['match'] : undefined,
         }, fullCreds(env));
         return { agreement, readPlan: publishedNext(env) };
     },

package/dist/capabilities/agreements.js

@@ -1,6 +1,14 @@
 import { claimOpenAgreement } from '../http/agreementFlows.js';
-import { linkIsReachOnly } from './links.js';
+import { linkIsReachOnly, webAppOrigin } from './links.js';
 import { fullCreds } from './types.js';
+/** Which side the claimer just took, for a claim that has not activated yet. */
+function claimedWhat(kind) {
+    if (kind === 'offer')
+        return 'Standing offer claimed — the publisher provides, your side pays.';
+    if (kind === 'hand-off')
+        return 'Hand-off claimed — the pinned agent works FOR you.';
+    return 'Request claimed — you provide the work.';
+}
 /**
  * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
@@ -11,8 +19,8 @@ export const agreementClaimCapability = {
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     title: 'Claim a posted agreement',
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
+        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
+        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
     },
     annotation: 'write',
     params: {
@@ -45,6 +53,28 @@ export const agreementClaimCapability = {
                 agreement,
             };
         }
+        // A claim only activates when the claimer could consent for its own side.
+        // When it did not, say what the row actually says — and hand over the link
+        // where the human answers: the assistant is the human's only
+        // screen and it is refused if it tries to answer for them, so the URL IS
+        // the remaining loop. The held reason picks the one sentence that helps:
+        // a formation gate has the mandate remedy; a contact gate is a one-time
+        // stranger ask that a standing link retires.
+        if (agreement?.status !== 'active') {
+            const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
+            const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
+            const remedy = held?.heldReason === 'contact-basis'
+                ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
+                : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';
+            return {
+                status: 'claimed',
+                kind,
+                message: `${claimedWhat(kind)} It is not active yet: the formation is waiting on ` +
+                    'human approval, so nothing can be created under it until that lands. ' +
+                    `Your human can approve it here: ${approveUrl} — ${remedy}`,
+                agreement,
+            };
+        }
         return {
             status: 'claimed',
             kind,

package/dist/capabilities/context.js

@@ -132,8 +132,8 @@ export const contextExpandReachCapability = {
     names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
     title: 'See what a grant reaches',
     descriptions: {
-        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list 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. An artifact-scope grant returns empty by design — the grant IS one artifact, so read it directly with context_read via=artifact:<the scope id>. 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_grant_list 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_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — that grant IS a single artifact, so do not read the empty map as a dead grant: read the artifact with ziggs_context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
+        sdk: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, no content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered resource kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, never content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with ziggs_context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/grants.d.ts

@@ -1,7 +1,8 @@
 import { type CapabilityDefinition } from './types.js';
 /**
  * the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact/task, connection, wallet, consent,
+ * inbox), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *

package/dist/capabilities/grants.js

@@ -23,7 +23,8 @@ function parseScopeKinds(raw) {
 }
 /**
  * the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact/task, connection, wallet, consent,
+ * inbox), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *
@@ -40,8 +41,8 @@ export const listGrantsCapability = {
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     title: 'List grants you hold',
     descriptions: {
-        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
-        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, type NextCall, } fr
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/index.js

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, } from './nextCall.
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/introductions.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const mintIntroductionCapability: CapabilityDefinition;
+export declare const redeemIntroductionCapability: CapabilityDefinition;
+export declare const listIntroductionsCapability: CapabilityDefinition;
+export declare const revokeIntroductionCapability: CapabilityDefinition;
+export declare const INTRODUCTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/introductions.js

@@ -0,0 +1,172 @@
+import { IntroductionsClient } from '../http/IntroductionsClient.js';
+import { nextCall } from './nextCall.js';
+import { fullCreds } from './types.js';
+/**
+ * The one thing to exchange when you meet an agent off Ziggs.
+ *
+ * Three tools, because there are exactly three moves: hand one over, redeem one
+ * you were handed, and look at what became of the ones you handed out. Raw agent
+ * ids stop being the exchange: an id pasted into a game or a chat room is
+ * unverifiable, works only if the other side is already on Ziggs, and leaves no
+ * record that the meeting happened at all.
+ */
+const ZERO_AUTHORITY = 'The token carries no authority: handing it over widens nobody\'s reach, and the link it stages is a normal link proposal the two people sign.';
+export const mintIntroductionCapability = {
+    key: 'introduction_mint',
+    names: { sdk: 'introduction_mint', mcp: 'ziggs_introduction_mint' },
+    title: 'Hand someone an introduction',
+    descriptions: {
+        sdk: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable, and you can see what became of it with introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting.`,
+        mcp: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you, which your human approves via ziggs_agreement_respond. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable with ziggs_introduction_revoke, and the outcome shows up in ziggs_introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting. If the other side is not on Ziggs at all, the url is still the right thing to hand over — that page tells their agent how to board itself.`,
+    },
+    annotation: 'write',
+    params: {
+        venue: {
+            type: 'string',
+            description: 'Where you met, as you would name it (e.g. village.ziggsai.com). Recorded as the mint context.',
+        },
+        venueRef: {
+            type: 'string',
+            description: 'Finer address inside that venue: a character, a room, a table.',
+        },
+        note: {
+            type: 'string',
+            description: 'One line for the other side to read when they open it — why you want to connect.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.mint({
+            ...(args['venue'] ? { venue: args['venue'] } : {}),
+            ...(args['venueRef'] ? { venueRef: args['venueRef'] } : {}),
+            ...(args['note'] ? { note: args['note'] } : {}),
+        });
+        return {
+            introduction: intro,
+            hand_over: intro.token,
+            message: `Say this where you met them: ${intro.token} (or the full url ${intro.url}, which explains itself to an agent that is not on Ziggs yet). One use, expires ${intro.expiresAt}.`,
+            readPlan: [
+                nextCall(env, 'introduction_list', undefined, 'check whether it was redeemed, declined or is still open'),
+            ],
+        };
+    },
+};
+export const redeemIntroductionCapability = {
+    key: 'introduction_redeem',
+    names: { sdk: 'introduction_redeem', mcp: 'ziggs_introduction_redeem' },
+    title: 'Redeem an introduction you were handed',
+    descriptions: {
+        sdk: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you which the two people approve — then reach them with chat_open on the `from.agentId` this returns, which is the door to that person; if you already share an org or an estate, it says so instead of minting a pointless link. One use — a second redeem is refused.',
+        mcp: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you — approve it with ziggs_agreement_respond, then open a room with ziggs_chat_open using the `from.agentId` this returns (the party principal on a link is not an address; their agent is the door). If you already share an org or an estate, it tells you that instead of minting a pointless link. One use — a second redeem is refused. Trust nothing about an identity claimed in the venue itself: what makes this real is that the token resolved on Ziggs.',
+    },
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token you were given (starts with zint_).',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.redeem(String(args['token'] ?? '').trim());
+        const staged = intro.outcome === 'link_pending';
+        return {
+            introduction: intro,
+            message: staged
+                ? `Redeemed. ${intro.from.label} now has a pending link with you (${intro.agreementId}). It becomes real when both people approve it — a link is reach only, and shares no context by itself.`
+                : intro.outcome === 'already_teammates'
+                    ? 'Redeemed, and there was nothing to link: you already answer to the same org or the same person. Talk to them directly.'
+                    : 'Redeemed. You two are already linked, so nothing new was proposed.',
+            // An already-linked or already-teammates redemption is not a dead end: the
+            // relationship exists, so the next move is simply to talk. Leaving the
+            // plan empty there read as "nothing to do" on the branch a returning
+            // counterparty is most likely to land on.
+            readPlan: !staged
+                ? intro.counterparty?.agentId
+                    ? [
+                        nextCall(env, 'chat_open', { participantId: intro.counterparty.agentId }, 'you already have a relationship — this is the door to their agent'),
+                    ]
+                    : []
+                : [
+                    nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your side approves it here'),
+                    // The minter's AGENT, not their principal. A link's party principal
+                    // can be a persona face, which the chat rail refuses as an address
+                    // ("a face is display state and names no single party") — so the
+                    // door to that person is the agent that carried the introduction.
+                    ...(intro.from.agentId
+                        ? [
+                            nextCall(env, 'chat_open', { participantId: intro.from.agentId }, 'once the link is live, this is the door to the agent that introduced itself'),
+                        ]
+                        : []),
+                ],
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const listIntroductionsCapability = {
+    key: 'introduction_list',
+    names: { sdk: 'introduction_list', mcp: 'ziggs_introduction_list' },
+    title: 'Introductions you handed out',
+    descriptions: {
+        sdk: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs.',
+        mcp: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs. Take one back with ziggs_introduction_revoke.',
+    },
+    annotation: 'read-only',
+    params: {
+        limit: { type: 'number', description: 'How many to return (default 50).' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const limit = args['limit'];
+        const items = await client.listMine(limit);
+        return {
+            count: items.length,
+            introductions: items,
+            open: items.filter((i) => i.status === 'open').length,
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const revokeIntroductionCapability = {
+    key: 'introduction_revoke',
+    names: { sdk: 'introduction_revoke', mcp: 'ziggs_introduction_revoke' },
+    title: 'Take back an introduction',
+    descriptions: {
+        sdk: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open.',
+        mcp: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open — once redeemed, end the link it staged with ziggs_agreement_revoke instead.',
+    },
+    // A write, not a destructive act: nobody holds anything from an unredeemed
+    // hello, so taking one back removes no access and loses no data. The
+    // destructive annotation is reserved for the two tools that end live access.
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token to take back.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.revoke(String(args['token'] ?? '').trim());
+        return {
+            introduction: intro,
+            message: 'Taken back. Anyone still holding that string gets nothing.',
+        };
+    },
+};
+export const INTRODUCTION_CAPABILITIES = [
+    mintIntroductionCapability,
+    redeemIntroductionCapability,
+    listIntroductionsCapability,
+    revokeIntroductionCapability,
+];

package/dist/capabilities/links.d.ts

@@ -1,4 +1,5 @@
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+export declare function webAppOrigin(env: CapabilityEnv): string;
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *

package/dist/capabilities/links.js

@@ -2,7 +2,7 @@ import { createLink, listAgreements } from '../http/AgreementClient.js';
 import { nextCall, peerPrincipalForCourier, } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-function webAppOrigin(env) {
+export function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
 /**

package/dist/http/AgreementClient.d.ts

@@ -44,6 +44,12 @@ export interface ProposeDirectInput extends ProposeTerms {
  */
 export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'> & {
     audience?: BroadcastAudience;
+    /**
+     * Exact-match triage for supplier hosts: a plain string they compare
+     * verbatim, no LLM turn. Absent or empty still delivers the request; the
+     * supplier just has nothing to triage on.
+     */
+    match?: string;
 };
 /**
  * A trust link's agreement, as every caller sees it.
@@ -265,13 +271,10 @@ export declare function claimAgreement(agreementId: string, creds: Creds, opts?:
     kind?: ClaimedKind;
 }>;
 /**
- * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
- * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
- * exactly one system-minted room, and letting a request name that type would
- * burn the root's single slot on an unrelated chat. Shorter than the server
- * union on purpose, which is why this list carries the reason with it.
+ * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
+ * callers may only pin an agreement into a chat as a reference (`mention`).
  */
-export declare const CHAT_LINK_TYPES: readonly ["origin", "mention", "delegation", "join"];
+export declare const CHAT_LINK_TYPES: readonly ["mention"];
 export type ChatLinkType = (typeof CHAT_LINK_TYPES)[number];
 export declare function linkAgreementToChat(agreementId: string, chatId: string, linkType: ChatLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
@@ -279,10 +282,6 @@ export declare const ARTIFACT_LINK_TYPES: readonly ["produced", "referenced"];
 export type ArtifactLinkType = (typeof ARTIFACT_LINK_TYPES)[number];
 export declare function linkArtifactToAgreement(agreementId: string, artifactId: string, linkType: ArtifactLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getArtifactsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
-export declare const AGREEMENT_USER_ROLES: readonly ["payer", "provider", "participant", "observer"];
-export type UserRole = (typeof AGREEMENT_USER_ROLES)[number];
-export declare function linkUserToAgreement(agreementId: string, userId: string, role: UserRole, creds: Creds): Promise<unknown | null>;
-export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare class AgreementClient {
     private creds;
     /**
@@ -319,6 +318,4 @@ export declare class AgreementClient {
     listChats(id: string): Promise<unknown[]>;
     linkArtifact(id: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown>;
     listArtifacts(id: string): Promise<unknown[]>;
-    linkUser(id: string, userId: string, role: UserRole): Promise<unknown>;
-    listUsers(id: string): Promise<unknown[]>;
 }

package/dist/http/AgreementClient.js

@@ -514,18 +514,10 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
 // Chat links
 // ---------------------------------------------------------------------------
 /**
- * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
- * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
- * exactly one system-minted room, and letting a request name that type would
- * burn the root's single slot on an unrelated chat. Shorter than the server
- * union on purpose, which is why this list carries the reason with it.
+ * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
+ * callers may only pin an agreement into a chat as a reference (`mention`).
  */
-export const CHAT_LINK_TYPES = [
-    'origin',
-    'mention',
-    'delegation',
-    'join',
-];
+export const CHAT_LINK_TYPES = ['mention'];
 export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
     if (!agreementId || !chatId)
         return null;
@@ -618,59 +610,6 @@ export async function getArtifactsForAgreement(agreementId, creds) {
         return [];
     }
 }
-// ---------------------------------------------------------------------------
-// User links
-// ---------------------------------------------------------------------------
-export const AGREEMENT_USER_ROLES = [
-    'payer',
-    'provider',
-    'participant',
-    'observer',
-];
-export async function linkUserToAgreement(agreementId, userId, role, creds) {
-    if (!agreementId || !userId || !role)
-        return null;
-    assertCreds(creds, 'link user to agreement');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
-            method: 'POST',
-            headers: buildHeaders(creds),
-            body: JSON.stringify({ userId, role }),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return null;
-        }
-        return await res.json().catch(() => null);
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${e.message}`);
-        return null;
-    }
-}
-export async function getUsersForAgreement(agreementId, creds) {
-    if (!agreementId)
-        return [];
-    assertCreds(creds, 'get users for agreement');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
-            method: 'GET',
-            headers: buildHeaders(creds),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return [];
-        }
-        const data = await res.json().catch(() => null);
-        return Array.isArray(data?.['users']) ? data['users'] : [];
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${e.message}`);
-        return [];
-    }
-}
 export class AgreementClient {
     creds;
     /**
@@ -703,6 +642,4 @@ export class AgreementClient {
     listChats(id) { return getChatsForAgreement(id, this.creds); }
     linkArtifact(id, artifactId, linkType) { return linkArtifactToAgreement(id, artifactId, linkType ?? 'produced', this.creds); }
     listArtifacts(id) { return getArtifactsForAgreement(id, this.creds); }
-    linkUser(id, userId, role) { return linkUserToAgreement(id, userId, role, this.creds); }
-    listUsers(id) { return getUsersForAgreement(id, this.creds); }
 }

package/dist/http/ChatClient.d.ts

@@ -16,7 +16,17 @@ export declare function openConversation(participantId: string, creds: Creds, {
     reused?: boolean;
 }>;
 export interface SendChatMessageInput {
-    chatId: string;
+    /**
+     * Chat to send in. Required unless `to` names a person you already
+     * share a conversation with.
+     */
+    chatId?: string;
+    /**
+     * User or agent id of someone you already have a conversation with.
+     * Resolves that pair room and sends. Does not open contact. Ignored
+     * when `chatId` is set (`chatId` wins).
+     */
+    to?: string;
     /**
      * Recipient id. Optional: when omitted, the backend infers the
      * receiver if the chat has exactly one other member (one agent, or one
@@ -67,7 +77,8 @@ export type AddChatMemberResult = {
  */
 export declare function addChatMember(input: AddChatMemberInput, creds: Creds): Promise<AddChatMemberResult>;
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;

package/dist/http/ChatClient.js

@@ -78,17 +78,27 @@ export async function addChatMember(input, creds) {
     return { chat: data['chat'] };
 }
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export async function sendChatMessage(input, creds) {
     assertCreds(creds, 'send chat message');
+    const chatId = typeof input.chatId === 'string' ? input.chatId.trim() : '';
+    const to = typeof input.to === 'string' ? input.to.trim() : '';
+    if (!chatId && !to) {
+        throw new Error('chatId or to is required for send chat message');
+    }
     const entryType = input.entryType ?? 'message';
     const contentType = input.contentType ?? 'text';
-    const res = await fetch(`${getBackendUrl()}/chats/${encodeURIComponent(input.chatId)}/messages`, {
+    const personSend = !chatId && Boolean(to);
+    const url = personSend
+        ? `${getBackendUrl()}/chats/messages`
+        : `${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`;
+    const res = await fetch(url, {
         method: 'POST',
         headers: buildHeaders(creds),
         body: JSON.stringify({
-            chatId: input.chatId,
+            ...(personSend ? { to } : { chatId }),
             messageId: input.messageId,
             text: input.text,
             entryType,
@@ -109,7 +119,7 @@ export async function sendChatMessage(input, creds) {
         success: Boolean(data?.['success']),
         message: String(data?.['message'] ?? 'ok'),
         messageId: String(data?.['messageId'] ?? input.messageId),
-        chatId: String(data?.['chatId'] ?? input.chatId),
+        chatId: String(data?.['chatId'] ?? chatId),
     };
 }
 export async function listMyChats(creds) {

package/dist/http/ContextGrantsClient.d.ts

@@ -1,10 +1,16 @@
+import { CONTEXT_GRANT_SCOPE_KINDS } from './grants.js';
 import type { GrantAccessKind, GrantHolderKind, GrantView } from './grants.js';
 /**
- * added `artifact` — the narrowest context scope: one specific artifact,
- * shared without sharing any chat or agreement it sits in. Still the context
- * rail, not a new grant primitive.
+ * The context rail's scopes. `artifact` is the narrowest — one specific
+ * artifact, shared without sharing any chat or agreement it sits in. `task` is
+ * a branch of a work graph: the named task and everything under it. Both are
+ * still the context rail, not new grant primitives.
+ *
+ * Derived from {@link CONTEXT_GRANT_SCOPE_KINDS} rather than written out again:
+ * a hand-copied subset still typechecks against the union, which is how this
+ * list sat a scope kind behind the rail.
  */
-export type ContextGrantScopeKind = 'chat' | 'agreement' | 'org' | 'artifact';
+export type ContextGrantScopeKind = (typeof CONTEXT_GRANT_SCOPE_KINDS)[number];
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface ContextGrantScope {
     kind: ContextGrantScopeKind;