@ziggs-ai/api-client 0.11.0 → 0.13.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -3,6 +3,13 @@ export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;
 export declare const agreementRequestCapability: CapabilityDefinition;
+/**
+ * No mandate param here, deliberately: a listing is formed inside no job. It is
+ * a standing invitation to the world that outlives whatever the agent happens
+ * to be doing today, and the publish path says so at its own end
+ * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
+ * listing when the job ended.
+ */
 export declare const agreementOfferCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;
 export declare const AGREEMENT_VERB_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/agreementVerbs.js

@@ -77,6 +77,28 @@ function termsFrom(args) {
 function engagementKindFrom(args) {
     return args['engagementKind'] ?? 'service';
 }
+/**
+ * The job an agent declares it is acting inside.
+ *
+ * The consent gate excuses a formation that sits inside a job a human already
+ * approved, and it verifies the claim against the acting agent. What did not
+ * exist was a way to MAKE the claim: `parentAgreementId` rode only on internal
+ * service calls, so every agreement an agent formed arrived at the gate as an
+ * outsider and waited on a human — including the ordinary case of buying the
+ * help the job it was hired for needs.
+ *
+ * Declared by the caller, never guessed by the server. The SDK fills it in from
+ * the task it is executing, so an agent doing assigned work pays nothing for it.
+ */
+const MANDATE_PARAM = {
+    type: 'string',
+    description: 'The active agreement whose work this is part of — the job you are doing. It becomes this engagement\'s parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job.',
+};
+/** Pull the declared mandate off a validated arg bag, as the wire field. */
+function mandateFrom(args) {
+    const declared = args['mandateAgreementId'];
+    return typeof declared === 'string' && declared ? { parentAgreementId: declared } : {};
+}
 /** The audience a broadcast reaches. */
 const AUDIENCE_PARAM = {
     type: 'string',
@@ -84,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,
@@ -114,12 +147,14 @@ export const agreementBuyCapability = {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const counterparty = args['counterparty'];
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: counterparty,
             chatId: args['chatId'],
             // They provide. The payer is derived server-side as the other side.
@@ -143,12 +178,14 @@ export const agreementBidCapability = {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: args['counterparty'],
             chatId: args['chatId'],
             // You provide, so the counterparty pays.
@@ -180,11 +217,13 @@ export const agreementBrokerCapability = {
         },
         chatId: CHAT_PARAM,
         ...TERMS_PARAMS,
+        mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const agreement = await proposeDirectTo({
             ...termsFrom(args),
+            ...mandateFrom(args),
             proposedTo: args['counterparty'],
             chatId: args['chatId'],
             providerId: args['provider'],
@@ -204,19 +243,33 @@ export const agreementRequestCapability = {
         mcp: 'Post work you want done and will pay for: whoever claims it does the work. Use this when nothing already listed fits, rather than proposing to named counterparties one at a time. To offer work you would do, use ziggs_agreement_offer. Claimable via ziggs_agreement_claim; visible in ziggs_marketplace_view.',
     },
     annotation: 'write',
-    params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS },
+    params: {
+        audience: AUDIENCE_PARAM,
+        ...TERMS_PARAMS,
+        match: MATCH_PARAM,
+        mandateAgreementId: MANDATE_PARAM,
+    },
     needsAgentId: true,
     handler: async (args, env) => {
         const agreement = await proposeBroadcast({
             ...termsFrom(args),
+            ...mandateFrom(args),
             chatId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
+            match: typeof args['match'] === 'string' ? args['match'] : undefined,
         }, fullCreds(env));
         return { agreement, readPlan: publishedNext(env) };
     },
     sdkOptions: { isAgreementCreation: true },
 };
+/**
+ * No mandate param here, deliberately: a listing is formed inside no job. It is
+ * a standing invitation to the world that outlives whatever the agent happens
+ * to be doing today, and the publish path says so at its own end
+ * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
+ * listing when the job ended.
+ */
 export const agreementOfferCapability = {
     key: 'agreement_offer',
     names: { sdk: 'agreement_offer', mcp: 'ziggs_agreement_offer' },
@@ -278,7 +331,7 @@ export const agreementHandoffCapability = {
         // would have had to look it up to pass it, and a lookup whose answer is
         // unique is not a decision worth handing to the caller.
         const parent = await getAgreement(parentAgreementId, creds);
-        const providerId = parent?.parties?.providerAgent;
+        const providerId = parent?.parties?.provider?.actor;
         if (!providerId) {
             throw new Error(`Cannot hand off ${parentAgreementId}: it names no provider, so there is no hire to share. Check the id with agreement_get.`);
         }

package/dist/capabilities/agreements.js

@@ -21,10 +21,22 @@ export const agreementClaimCapability = {
             required: true,
             description: 'The open agreement to claim (request / offer / link invite id)',
         },
+        // The job this claim is part of. A claim is the DEFAULT way to engage, so
+        // without this the ordinary case — an agent claiming the help the job it is
+        // doing needs — waited on a human every time. It authorizes; it does not
+        // re-parent: the row belongs to whoever posted it, and a claimer cannot move
+        // somebody else's agreement into its own tree.
+        mandateAgreementId: {
+            type: 'string',
+            description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env));
+        const declaredMandate = args['mandateAgreementId'];
+        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), typeof declaredMandate === 'string' && declaredMandate
+            ? { mandateAgreementId: declaredMandate }
+            : {});
         if (kind === 'link') {
             return {
                 status: 'linked',

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

@@ -1,8 +1,8 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
-export { nextCall, peerAgentId, type NextCall } from './nextCall.js';
+export { nextCall, peerPrincipalId, peerPrincipalForCourier, type NextCall, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.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

@@ -1,8 +1,8 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
-export { nextCall, peerAgentId } from './nextCall.js';
+export { nextCall, peerPrincipalId, peerPrincipalForCourier, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.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/links.d.ts

@@ -10,16 +10,27 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * already exist (an older chat, an agreement, an org).
  */
 export declare function linkIsReachOnly(env: CapabilityEnv): string;
-export declare const createLinkInviteCapability: CapabilityDefinition;
 export declare const listLinksCapability: CapabilityDefinition;
 /**
- * A link proposed to an agent you can name.
+ * The one way to connect with someone.
  *
  * This used to ride the propose grammar as `engagementKind: "link"`, which put
  * bilateral trust on the same verb as commercial terms it has none of: no
- * price, no chat, no work. It belongs here, beside the invite and the list, so
- * links have one rail. `link_create_invite` is the same act when you do NOT
- * have an agent id and need a shareable page instead.
+ * price, no chat, no work. It moved here, and then absorbed the other two ways
+ * of doing the same thing: naming an agent id, naming an email — a form the
+ * backend had but no tool ever sent, so an assistant could not name a person at
+ * all — and minting a share link.
+ *
+ * `to` is an email or an agent id, and the link is with the PERSON either way.
+ * An id is only a way to find its owner: naming one specific assistant is
+ * fragile, because people connect more than one, swap them, and someone who has
+ * connected none has no agent to name. An agent that answers to an ORG is
+ * refused rather than resolved, since that would link the caller to whoever
+ * happens to own the org, who consented to nothing.
+ *
+ * The answer is constant. It never says whether the address belonged to anyone,
+ * whether the two were already connected, or whether this was a repeat — a
+ * response that distinguished those would be a way to check who has an account.
  */
 export declare const proposeLinkCapability: CapabilityDefinition;
 export declare const LINK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/links.js

@@ -1,5 +1,5 @@
 import { createLink, listAgreements } from '../http/AgreementClient.js';
-import { nextCall, peerAgentId } from './nextCall.js';
+import { nextCall, peerPrincipalForCourier, } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
 function webAppOrigin(env) {
@@ -31,8 +31,8 @@ function inviteShareUrl(env, agreementId) {
  */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only — it shares no context on its own. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id): that admits both linked agents to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
-        : 'A link is reach-only — it shares no context on its own. Opening a chat with the peer admits both linked agents to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
+        ? 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side (ziggs_chat_open, participantId = the peer principal): delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Opening the room admits both sides to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
+        : 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side; delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Opening the room admits both sides to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
 /**
@@ -41,62 +41,20 @@ const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
  * the limit instead of letting an agent discover it by getting a 400.
  */
 const MAX_LINK_INVITE_CLAIMS = 25;
-///1022 — the link rail shrank to two tools. Links are agreements, so
-// the agreement verbs carry the rest: request a direct link with
-// link_propose (counterparty = the agent id), claim
+// Two tools. Links are agreements, so the agreement verbs carry the rest: claim
 // an invite with agreement_claim, end a link with agreement_revoke.
-export const createLinkInviteCapability = {
-    key: 'link_create_invite',
-    names: { sdk: 'link_create_invite', mcp: 'ziggs_link_create_invite' },
-    title: 'Create a 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 and returns shareUrl — one public page that is the entire invite, for a person or for their assistant. Set maxClaims to let several people claim the same link — each gets their own separate connection. When you DO have the agent id, propose the link directly instead: link_propose with counterparty = that id.",
-        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_connection_list 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") and returns shareUrl: one public page that is the entire invite — the recipient accepts from it with no account, and their assistant can read the connect instructions off the same URL. Give the human that link and nothing else. Set maxClaims to share ONE link with several people; each claimer gets their own separate connection, not a group. Revoke via ziggs_agreement_revoke to disable. When you DO have the agent id, propose the link directly instead: ziggs_link_propose with counterparty = that id.',
-    },
-    annotation: 'write',
-    params: {
-        message: {
-            type: 'string',
-            description: 'Optional note shown to whoever opens the invite (agreement description)',
-        },
-        maxClaims: {
-            type: 'number',
-            description: `How many people may claim this one link (default 1, max ${MAX_LINK_INVITE_CLAIMS}). Each claimer forms their own separate connection with you — this does not create a group.`,
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        const maxClaims = args['maxClaims'];
-        const { agreement } = await createLink({
-            description: args['message'],
-            ...(maxClaims == null ? {} : { maxClaims }),
-        }, fullCreds(env));
-        const shareUrl = inviteShareUrl(env, agreement.agreementId);
-        const seats = agreement.linkInvite?.maxClaims ?? 1;
-        const seatNote = seats > 1
-            ? `valid 7 days and claimable by up to ${seats} people (each gets their own separate connection — not a group)`
-            : 'single-use and valid 7 days';
-        return {
-            status: 'open',
-            inviteId: agreement.agreementId,
-            shareUrl,
-            maxClaims: seats,
-            seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
-            message: env.surface === 'mcp'
-                ? `Open link invite created, ${seatNote}. Give the human shareUrl and nothing else — it is the whole invite. A recipient with no Ziggs account signs up straight from that page, no beta code needed, and accepting the link is part of the same step; a recipient who would rather their own assistant do the wiring can hand it the same URL, because the page carries the MCP server address and the claim instructions in its markup. Either way the recipient's side of the link is one of their agents — their assistant by default — and it must be running before the link carries anything.`
-                : `Open link invite created, ${seatNote}. shareUrl is the whole invite: a recipient with no Ziggs account signs up straight from that page and accepts the link in the same step, and an assistant handed the same URL reads the connect instructions off it. Their side of the link is one of their agents (their assistant by default), and it must be running before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
-            agreement,
-        };
-    },
-    sdkOptions: { isAgreementCreation: true },
-};
+//
+// There were three. `link_create_invite` was the same act as `link_propose` with
+// a different way of naming the other side, and an assistant had to choose
+// between them before knowing which applied. One verb takes an email, an agent
+// id, or nothing.
 export const listLinksCapability = {
     key: 'link_list',
     names: { sdk: 'link_list', mcp: 'ziggs_link_list' },
     title: 'List your links',
     descriptions: {
-        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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. Request a new link with link_propose, or link_create_invite when you lack the agent id; end one with agreement_revoke.',
-        mcp: 'List link agreements for this agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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_agreement_respond; request a new one with ziggs_link_propose, or ziggs_link_create_invite when you lack the agent id; end one with ziggs_agreement_revoke.',
+        sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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. The two principals on a link are the two PEOPLE it connects; the actor slots record which agent carried the paperwork and are not addresses. Connect with someone new using link_propose; end a link with agreement_revoke.',
+        mcp: 'List link agreements for this agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. 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, and parties — where parties.creator.principal and parties.provider.principal are the two PEOPLE the link connects. The actor slots record which agent carried the paperwork and are not addresses: message the person. Approve pending links via ziggs_agreement_respond; connect with someone new using ziggs_link_propose; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -119,15 +77,28 @@ export const listLinksCapability = {
         const active = links.filter((a) => a.status === 'active');
         // A link grants reach and nothing else, so the move after seeing one is
         // always the same: open a room with that peer, or share context explicitly.
-        // Both were named in prose, and the peer id had to be dug out of
-        // `parties` by whoever read it — while being right here.
+        // Both were named in prose, and the peer id had to be dug out of `parties`
+        // by whoever read it — while being right here.
+        //
+        // The peer is a PERSON. This used to pre-fill the peer's `actor`, which is
+        // courier info and null on most links, so the suggestion either named an
+        // agent that is no longer a door or silently disappeared. It fills in only
+        // when this agent's own stamp identifies which side is ours; otherwise the
+        // peer is named in prose and read off the rows below, because a pre-filled
+        // call naming the wrong party would get run.
         const readPlan = [];
+        let unnamedPeers = 0;
         for (const link of active.slice(0, 3)) {
-            const peer = peerAgentId(link.parties, env.creds.agentId);
-            if (!peer)
+            const peer = peerPrincipalForCourier(link.parties, env.creds.agentId);
+            if (!peer) {
+                unnamedPeers += 1;
                 continue;
+            }
             readPlan.push(nextCall(env, 'chat_open', { participantId: peer }, 'open a room with this linked peer — a link alone carries no context'));
         }
+        if (unnamedPeers > 0) {
+            readPlan.push(nextCall(env, 'chat_open', undefined, 'open a room with a linked peer: participantId is the other principal on the link (parties.creator / parties.provider), which is a person'));
+        }
         if (active.length) {
             readPlan.push(nextCall(env, 'context_issue_grant', undefined, 'share context that already exists: a link does not share any on its own'));
         }
@@ -142,53 +113,70 @@ export const listLinksCapability = {
     sdkOptions: { isGenericFallback: true },
 };
 /**
- * A link proposed to an agent you can name.
+ * The one way to connect with someone.
  *
  * This used to ride the propose grammar as `engagementKind: "link"`, which put
  * bilateral trust on the same verb as commercial terms it has none of: no
- * price, no chat, no work. It belongs here, beside the invite and the list, so
- * links have one rail. `link_create_invite` is the same act when you do NOT
- * have an agent id and need a shareable page instead.
+ * price, no chat, no work. It moved here, and then absorbed the other two ways
+ * of doing the same thing: naming an agent id, naming an email — a form the
+ * backend had but no tool ever sent, so an assistant could not name a person at
+ * all — and minting a share link.
+ *
+ * `to` is an email or an agent id, and the link is with the PERSON either way.
+ * An id is only a way to find its owner: naming one specific assistant is
+ * fragile, because people connect more than one, swap them, and someone who has
+ * connected none has no agent to name. An agent that answers to an ORG is
+ * refused rather than resolved, since that would link the caller to whoever
+ * happens to own the org, who consented to nothing.
+ *
+ * The answer is constant. It never says whether the address belonged to anyone,
+ * whether the two were already connected, or whether this was a repeat — a
+ * response that distinguished those would be a way to check who has an account.
  */
 export const proposeLinkCapability = {
     key: 'link_propose',
     names: { sdk: 'link_propose', mcp: 'ziggs_link_propose' },
-    title: 'Propose a link to an agent',
+    title: 'Connect with someone',
     descriptions: {
-        sdk: "Propose bilateral trust to an agent you can name — no chat, no money, no work. Approval is routed to that agent's owner, because a person decides who their delegate trusts. When you do NOT have the agent id, use link_create_invite for a shareable page instead.",
-        mcp: "Propose bilateral trust to an agent you can name (NOT a third-party service connection — see ziggs_connection_list for that). No chat, no money, no work: a link is reach, and reach only. The server routes approval to that agent's owner human, because a person decides who their delegate trusts, so the id in the response may differ from the one you passed; `note` says so when it does. Approve via ziggs_agreement_respond. When you do NOT have the agent id, use ziggs_link_create_invite for a shareable page instead.",
+        sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organisation is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
+        mcp: "Connect with a person (NOT a third-party service connection — see ziggs_connection_list for that): pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent answering to an organisation is refused, because a link connects two people. Leave `to` out and you get shareUrl: one public page that is the whole invite, which you hand to your human to paste wherever they like. Someone with no Ziggs account signs up from that page and accepts in the same step, and their assistant handed the same URL reads the connect instructions off it. A link is reach and nothing else: no chat, no money, no work. The answer is identical every time, so it never reveals whether an address has an account. Approve links proposed to you with ziggs_agreement_respond; end one with ziggs_agreement_revoke.",
     },
     annotation: 'write',
     params: {
-        counterparty: {
+        to: {
             type: 'string',
-            required: true,
-            description: 'Agent id to link with.',
+            description: "The person to connect with: their email address, or the id of an agent that answers to them. Leave it out for a share link you pass on yourself.",
         },
         message: {
             type: 'string',
-            description: 'Optional note shown to whoever approves it.',
+            description: 'Optional note shown to whoever is asked to accept it.',
+        },
+        maxClaims: {
+            type: 'number',
+            description: `Share links only: how many people may claim this one link (default 1, max ${MAX_LINK_INVITE_CLAIMS}). Each claimer forms their own separate connection with you — this does not create a group.`,
         },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        const counterparty = args['counterparty'];
-        const { agreement } = await createLink({
-            targetAgentId: counterparty,
+        const to = args['to']?.trim();
+        const maxClaims = args['maxClaims'];
+        const { shareUrl } = await createLink({
+            ...(to ? { to } : {}),
             ...(args['message'] ? { description: args['message'] } : {}),
+            ...(maxClaims == null || to ? {} : { maxClaims }),
         }, fullCreds(env));
-        // The owner rewrite is surfaced rather than left to be noticed: an agent
-        // that passed one id and reads back another otherwise concludes it was
-        // ignored.
-        const routedTo = agreement?.parties?.proposedTo;
-        const note = routedTo && routedTo !== counterparty
-            ? `Approval routed to the target agent's owner (${routedTo}): a person decides who their delegate trusts. You passed ${counterparty}.`
-            : undefined;
+        // Two messages, chosen by what the CALLER passed rather than by what came
+        // back. That is the whole discipline: the caller knows whether it named
+        // somebody, so branching on it discloses nothing, while branching on
+        // anything the server learned about the target would.
         return {
-            agreement,
-            ...(note ? { note } : {}),
+            status: 'sent',
+            shareUrl,
+            message: to
+                ? `Invitation sent to ${to}. You will not be told whether they already had an account, whether you were already connected, or whether this repeated an earlier invitation — the answer is the same in every case, on purpose. It becomes a live connection when they accept. ${linkIsReachOnly(env)}`
+                : `Share link created, valid 7 days. Give your human shareUrl and nothing else: it is the whole invite. ${linkIsReachOnly(env)}`,
             readPlan: [
-                nextCall(env, 'link_list', { status: 'open' }, 'check whether it has been approved yet'),
+                nextCall(env, 'link_list', { status: 'open' }, 'check whether it has been accepted yet'),
             ],
         };
     },
@@ -196,6 +184,5 @@ export const proposeLinkCapability = {
 };
 export const LINK_CAPABILITIES = [
     proposeLinkCapability,
-    createLinkInviteCapability,
     listLinksCapability,
 ];

package/dist/capabilities/marketplace.js

@@ -47,9 +47,9 @@ function toListingRow(a, kind) {
         ...(terms.maxExecutions != null ? { maxExecutions: terms.maxExecutions } : {}),
         // Who does the work on an offer, who is paying on a request. The other slot is
         // the open one you would be filling by claiming, so it carries no name yet.
-        ...(named(parties.providerAgent) ? { providerAgent: parties.providerAgent } : {}),
-        ...(named(parties.provider) ? { provider: parties.provider } : {}),
-        ...(named(parties.payer) ? { payer: parties.payer } : {}),
+        ...(named(parties.provider?.actor) ? { providerAgent: parties.provider.actor } : {}),
+        ...(named(parties.provider?.principal) ? { provider: parties.provider.principal } : {}),
+        ...(named(parties.payer?.principal) ? { payer: parties.payer.principal } : {}),
         // Access the job cannot be done without — worth knowing before claiming it.
         ...(requiredConnections.length ? { requiredConnections } : {}),
         createdAt: a?.createdAt,

package/dist/capabilities/nextCall.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementParties } from '../types.js';
 import type { CapabilityEnv } from './types.js';
 /**
  * One runnable next step: a tool name, pre-filled arguments, and why.
@@ -32,13 +33,43 @@ export interface NextCall {
  */
 export declare function nextCall(env: CapabilityEnv, capabilityKey: string, args: Record<string, unknown> | undefined, why: string): NextCall;
 /**
- * The other party in a two-party agreement, from the perspective of `selfId`.
+ * The other PRINCIPAL in a two-party agreement, from the perspective of
+ * `selfId`.
+ *
+ * This was `peerAgentId`, and it read the `actor` columns — the agents that
+ * carried the paperwork. Those became courier info when a link was re-keyed to
+ * the two people it belongs to, and on most links they are null, so the hint it
+ * fed either pre-filled a call with an agent that is no longer a door or
+ * silently vanished because the helper returned nothing.
+ *
+ * Named for the SLOT, not for what a link happens to put in it. On a link both
+ * principals are guaranteed to be people, because links are person-only and
+ * both sides are userIds by construction — but the same slots hold an org or an
+ * agent on other engagement kinds, so a caller who read "person" here and
+ * trusted it on a hire would be wrong. The person guarantee is a link-only
+ * property; ask the kind before relying on it.
  *
  * Returns null rather than guessing when the row does not identify one, because
  * a pre-filled call naming the wrong counterparty is worse than no pre-filled
  * call: the caller would run it, and it would do something they did not ask for.
  */
-export declare function peerAgentId(parties: {
-    creatorAgent?: string | null;
-    providerAgent?: string | null;
-} | undefined, selfId: string | undefined): string | null;
+export declare function peerPrincipalId(parties: AgreementParties | undefined, selfId: string | undefined): string | null;
+/**
+ * The peer's principal, located by finding MY side rather than by knowing my
+ * own principal id.
+ *
+ * An agent knows its own agent id and not the id of the person it answers for,
+ * so it cannot ask {@link peerPrincipalId} which of two people it is. What it
+ * CAN recognise is its own courier stamp: if my agent id is in one side's
+ * `actor`, that side is mine and the other side's principal is the peer.
+ *
+ * Note the difference from the bug this replaced. Reading the peer's `actor` as
+ * the peer's address was wrong — those slots are courier info, null on most
+ * links, and never a door. Reading MY OWN `actor` to work out which side I am on
+ * is sound, because I am comparing against an id I hold.
+ *
+ * Returns null when neither side carries my stamp, which is the common case for
+ * a link two people formed from the web. No pre-filled call is the right answer
+ * there: naming the wrong counterparty would get run.
+ */
+export declare function peerPrincipalForCourier(parties: AgreementParties | undefined, myAgentId: string | undefined): string | null;