@ziggs-ai/api-client 0.10.4 → 0.12.0

package/dist/capabilities/connections.js

@@ -63,7 +63,7 @@ export const requestConnectionCapability = {
             'On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).',
         mcp: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
             'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
-            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call (not ziggs_connection_proxy).',
+            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.',
     },
     annotation: 'write',
     params: {

package/dist/capabilities/context.js

@@ -214,6 +214,9 @@ export const contextDelegateCapability = {
         const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
         const result = await client.delegateGrant(args['parentGrantId'], {
             holderId: args['holderId'],
+            // An agent passing part of its own grant onward hands it to another
+            // agent; a person is granted through their own surface.
+            holderKind: 'agent',
             scope: { kind: scopeKind, id: scopeId },
             temporal: temporal,
             expiresAt: args['expiresAt'] ?? undefined,

package/dist/capabilities/grants.d.ts

@@ -5,12 +5,13 @@ import { type CapabilityDefinition } from './types.js';
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *
- * HOLD, not reach. `GET /grants` lists granted rows and nothing else; access
- * that is implicit rather than granted (authorship, chat membership, agreement
- * party, org membership) leaves no row behind, so a reader can be entitled to
- * something this list will never mention. The description
- * says so, because the old "the single answer" wording was read as completeness
- * and an empty list as "no access".
+ * HOLD, not reach. `GET /grants` lists rows this holder is named on, and taking
+ * part in a room or being party to a live agreement now IS such a row. Two kinds
+ * of access still leave none: authoring an artifact, and the org memberships
+ * that make an ORG-held grant cover you (the row names the org, not you). So a
+ * reader can still be entitled to something this list will never mention, and
+ * the description says so, because the old "the single answer" wording was read
+ * as completeness and an empty list as "no access".
  */
 export declare const listGrantsCapability: CapabilityDefinition;
 export declare const GRANTS_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/grants.js

@@ -27,20 +27,21 @@ function parseScopeKinds(raw) {
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *
- * HOLD, not reach. `GET /grants` lists granted rows and nothing else; access
- * that is implicit rather than granted (authorship, chat membership, agreement
- * party, org membership) leaves no row behind, so a reader can be entitled to
- * something this list will never mention. The description
- * says so, because the old "the single answer" wording was read as completeness
- * and an empty list as "no access".
+ * HOLD, not reach. `GET /grants` lists rows this holder is named on, and taking
+ * part in a room or being party to a live agreement now IS such a row. Two kinds
+ * of access still leave none: authoring an artifact, and the org memberships
+ * that make an ORG-held grant cover you (the row names the org, not you). So a
+ * reader can still be entitled to something this list will never mention, and
+ * the description says so, because the old "the single answer" wording was read
+ * as completeness and an empty list as "no access".
  */
 export const listGrantsCapability = {
     key: 'grant_list',
     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?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", 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?": authorship, chat membership, agreement party, and org membership leave no grant row — an empty holder list means "no grants", 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), 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.',
     },
     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 { AGREEMENT_VERB_CAPABILITIES, agreementCommissionCapability, agreementBidCapability, agreementBrokerCapability, agreementQuestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
-export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.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, 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 { AGREEMENT_VERB_CAPABILITIES, agreementCommissionCapability, agreementBidCapability, agreementBrokerCapability, agreementQuestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
-export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.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, 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

@@ -3,23 +3,34 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * A link is reach-only — the follow-up move differs by surface tool names.
  *
  * Opening a chat is itself the admission: the backend issues a standing from-now
- * chat grant to every agent member as it creates the room, so both delegates can
+ * write grant to each side as it creates the room, so both delegates can
  * read and post immediately. Do NOT tell agents to follow chat_open with an
  * issue_grant on that same new chat — that only mints a duplicate grant carrying
  * the default 30-day expiry. issue_grant / context_delegate are for scopes that
  * 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 { createAgreement, listAgreements } from '../http/AgreementClient.js';
-import { nextCall, peerAgentId } from './nextCall.js';
+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) {
@@ -23,7 +23,7 @@ function inviteShareUrl(env, agreementId) {
  * A link is reach-only — the follow-up move differs by surface tool names.
  *
  * Opening a chat is itself the admission: the backend issues a standing from-now
- * chat grant to every agent member as it creates the room, so both delegates can
+ * write grant to each side as it creates the room, so both delegates can
  * read and post immediately. Do NOT tell agents to follow chat_open with an
  * issue_grant on that same new chat — that only mints a duplicate grant carrying
  * the default 30-day expiry. issue_grant / context_delegate are for scopes that
@@ -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,63 +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 createAgreement({
-            engagementKind: 'link',
-            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: {
@@ -120,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'));
         }
@@ -143,54 +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 createAgreement({
-            engagementKind: 'link',
-            providerId: 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'),
             ],
         };
     },
@@ -198,6 +184,5 @@ export const proposeLinkCapability = {
 };
 export const LINK_CAPABILITIES = [
     proposeLinkCapability,
-    createLinkInviteCapability,
     listLinksCapability,
 ];

package/dist/capabilities/marketplace.js

@@ -1,12 +1,12 @@
-import { pullOffers, pullQuests } from '../http/MarketplaceClient.js';
+import { pullOffers, pullRequests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
-const VIEW_KINDS = ['all', 'quests', 'offers'];
+const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
-    const propose = env.surface === 'mcp' ? 'ziggs_agreement_quest' : 'agreement_quest';
+    const propose = env.surface === 'mcp' ? 'ziggs_agreement_request' : 'agreement_request';
     const claim = env.surface === 'mcp' ? 'ziggs_agreement_claim' : 'agreement_claim';
     return (`Claim any row with ${claim} (agreementId). Publish your own with ${propose}: ` +
-        `proposedTo "everyone" or "org" with no providerId broadcasts a quest (claimer works, you pay); ` +
+        `proposedTo "everyone" or "org" with no providerId broadcasts a request (claimer works, you pay); ` +
         `the same with providerId = your own id publishes a standing offer (you work, claimer pays).`);
 }
 /** A broadcast sentinel in a party slot means "open", not a counterparty. */
@@ -35,15 +35,21 @@ function toListingRow(a, kind) {
         kind,
         description: terms.description ?? '',
         price: a?.money?.price ?? 0,
+        // What that price MEANS: a whole-engagement total, or a rate charged per
+        // completed task. Omitting it left a metered standing hire indistinguishable
+        // from a flat-priced one at the moment a caller decides to claim, and
+        // `per_task` is the default for a hire. Absent on rows written before the
+        // field existed, which read as `total`.
+        ...(terms.billing ? { billing: terms.billing } : {}),
         engagementKind: a?.engagementKind,
         lifecycle: terms.lifecycle,
         ...(terms.expiresAt ? { expiresAt: terms.expiresAt } : {}),
         ...(terms.maxExecutions != null ? { maxExecutions: terms.maxExecutions } : {}),
-        // Who does the work on an offer, who is paying on a quest. The other slot is
+        // 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,
@@ -59,15 +65,15 @@ export const marketplaceViewCapability = {
     names: { sdk: 'marketplace_view', mcp: 'ziggs_marketplace_view' },
     title: 'Browse the marketplace',
     descriptions: {
-        sdk: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a quest).',
-        mcp: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Quests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own with ziggs_agreement_offer (you do the work, the claimer pays) or ziggs_agreement_quest (the claimer does the work, you pay).',
+        sdk: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Requests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a request).',
+        mcp: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Requests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own with ziggs_agreement_offer (you do the work, the claimer pays) or ziggs_agreement_request (the claimer does the work, you pay).',
     },
     annotation: 'read-only',
     params: {
         kind: {
             type: 'string',
             enum: VIEW_KINDS,
-            description: 'all (default) | quests | offers',
+            description: 'all (default) | requests | offers',
         },
         limit: { type: 'number', description: 'Max rows per kind (default 20)' },
         since: { type: 'string', description: 'ISO timestamp — only rows published after this' },
@@ -83,22 +89,22 @@ export const marketplaceViewCapability = {
             limit: typeof args['limit'] === 'number' ? args['limit'] : 20,
             ...(args['since'] ? { since: args['since'] } : {}),
         };
-        const [quests, offers] = await Promise.all([
-            kind === 'offers' ? Promise.resolve([]) : pullQuests(options, creds),
-            kind === 'quests' ? Promise.resolve([]) : pullOffers(options, creds),
+        const [requests, offers] = await Promise.all([
+            kind === 'offers' ? Promise.resolve([]) : pullRequests(options, creds),
+            kind === 'requests' ? Promise.resolve([]) : pullOffers(options, creds),
         ]);
         return {
             ...(kind !== 'offers'
-                ? { quests: quests.map((q) => toListingRow(q, 'quest')), questCount: quests.length }
+                ? { requests: requests.map((q) => toListingRow(q, 'request')), requestCount: requests.length }
                 : {}),
-            ...(kind !== 'quests'
+            ...(kind !== 'requests'
                 ? { offers: offers.map((o) => toListingRow(o, 'offer')), offerCount: offers.length }
                 : {}),
             // Claiming is the move after browsing, and the id is in the row the
             // caller just received. The prose hint stays for the publish side, which
             // is a choice rather than a call.
             readPlan: [
-                ...(quests.length || offers.length
+                ...(requests.length || offers.length
                     ? [
                         nextCall(env, 'agreement_claim', undefined, 'claim a listing from this view by passing its agreementId — listings are take-it-or-leave-it, never countered'),
                     ]

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;