@ziggs-ai/api-client 0.11.0 → 0.12.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',
@@ -114,12 +136,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 +167,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 +206,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,11 +232,16 @@ 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,
+        mandateAgreementId: MANDATE_PARAM,
+    },
     needsAgentId: true,
     handler: async (args, env) => {
         const agreement = await proposeBroadcast({
             ...termsFrom(args),
+            ...mandateFrom(args),
             chatId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
@@ -217,6 +250,13 @@ export const agreementRequestCapability = {
     },
     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 +318,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/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;

package/dist/capabilities/nextCall.js

@@ -14,19 +14,65 @@ export function nextCall(env, capabilityKey, args, why) {
     };
 }
 /**
- * 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 function peerAgentId(parties, selfId) {
+export function peerPrincipalId(parties, selfId) {
     if (!parties || !selfId)
         return null;
-    const { creatorAgent, providerAgent } = parties;
-    if (creatorAgent && creatorAgent !== selfId)
-        return creatorAgent;
-    if (providerAgent && providerAgent !== selfId)
-        return providerAgent;
+    const creator = parties.creator?.principal;
+    const provider = parties.provider?.principal;
+    if (creator && creator !== selfId)
+        return creator;
+    if (provider && provider !== selfId)
+        return provider;
     return 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 function peerPrincipalForCourier(parties, myAgentId) {
+    if (!parties || !myAgentId)
+        return null;
+    const mineIsCreator = parties.creator?.actor === myAgentId;
+    const mineIsProvider = parties.provider?.actor === myAgentId;
+    // Both sides stamped with me is one estate on both ends, not a peer.
+    if (mineIsCreator === mineIsProvider)
+        return null;
+    const peer = mineIsCreator
+        ? parties.provider?.principal
+        : parties.creator?.principal;
+    return peer && peer !== myAgentId ? peer : null;
+}

package/dist/http/AgreementClient.d.ts

@@ -124,8 +124,12 @@ export declare function respondToAgreement(agreementId: string, action: 'approve
 export interface PendingApprovalFacts {
     /** Party ids with a pending entry on the approvals ledger. */
     pendingPartyIds: readonly string[];
-    /** The direct responder slot, when the proposal names one. */
-    proposedTo?: string | null;
+    /**
+     * The direct responder slot, when the proposal names one. A side names up to
+     * two ids — the accountable principal and the delegate acting for it — and
+     * either may be the one holding the decision.
+     */
+    proposedToIds?: readonly string[];
 }
 /**
  * Which of `candidateIds` holds the pending approval slot, first match wins —
@@ -182,17 +186,33 @@ export declare function getMyAgreements(filters: GetMyAgreementsFilters | undefi
 /** One agreement, shaped: a link comes back as its summary. */
 export declare function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null>;
 export interface CreateLinkBody {
-    /** Target agent for a direct link. Omit for an open, claimable invite. */
-    targetAgentId?: string;
+    /**
+     * Who to connect with: an email address, or the id of an agent that answers
+     * to them. Either way the link is with the PERSON — an id is only a way to
+     * find its owner, and an agent that answers to an org is refused. Omit for an
+     * open invite you share yourself.
+     */
+    to?: string;
     /** Message shown to whoever is asked to approve or claim it. */
     description?: string;
     /** Open invites only: how many people may claim this one link. Default 1. */
     maxClaims?: number;
-    /** Which of the caller's own agents stands on their side of the link. */
-    asAgentId?: string;
 }
 /**
- * Create a trust link — a direct proposal to one agent, or an open invite.
+ * The route's one answer, whatever was in `to`.
+ *
+ * Deliberately carries no agreement. Returning the row for an id target and a
+ * bare "sent" for an address made one of the two an existence oracle over the
+ * user table, so both say the same thing now: it went. `shareUrl` is null
+ * exactly when `to` was named, which the caller already knows.
+ */
+export interface CreateLinkResult {
+    ok: boolean;
+    status: 'sent';
+    shareUrl: string | null;
+}
+/**
+ * Connect with someone — by email, by agent id, or with a shareable invite.
  *
  * This posts to `POST /agreements/links`. It used to post to `POST /agreements`,
  * which also created work agreements inline and skipped the gates the proposal
@@ -200,10 +220,7 @@ export interface CreateLinkBody {
  * (`POST /agreements/proposals`) and the marketplace claim routes; this rail
  * carries links and nothing else.
  */
-export declare function createLink(body: CreateLinkBody, creds: Creds): Promise<{
-    ok: boolean;
-    agreement: Agreement;
-}>;
+export declare function createLink(body: CreateLinkBody, creds: Creds): Promise<CreateLinkResult>;
 export declare function revokeAgreement(agreementId: string, creds: Creds): Promise<{
     ok: boolean;
     agreement: Agreement;
@@ -225,7 +242,24 @@ export type ClaimedKind = 'link' | 'offer' | 'request' | 'hand-off';
  *
  * POST /agreements/:id/claim — canonical; no partyId in body.
  */
-export declare function claimAgreement(agreementId: string, creds: Creds): Promise<{
+/**
+ * What a claimer can say about WHY it is claiming.
+ *
+ * A claim binds a party to terms somebody else posted, so the only thing there
+ * is to declare is the authority behind it: the job the claiming agent is
+ * already doing. Nothing here changes the row — the lineage of a posted
+ * agreement belongs to whoever posted it.
+ */
+export interface ClaimOptions {
+    /**
+     * The active agreement whose work this claim is part of. An agent acting
+     * inside a job its human approved does not need a second consent for the
+     * engagements that job requires, but it has to NAME the job — the server
+     * verifies the claim against the acting agent and never guesses one.
+     */
+    mandateAgreementId?: string;
+}
+export declare function claimAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     ok: boolean;
     agreement: Agreement;
     kind?: ClaimedKind;
@@ -267,10 +301,7 @@ export declare class AgreementClient {
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
     listMine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(id: string): Promise<Agreement | null>;
-    createLink(data: CreateLinkBody): Promise<{
-        ok: boolean;
-        agreement: Agreement;
-    }>;
+    createLink(data: CreateLinkBody): Promise<CreateLinkResult>;
     revoke(id: string): Promise<{
         ok: boolean;
         agreement: Agreement;

package/dist/http/AgreementClient.js

@@ -1,6 +1,6 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget } from '../types.js';
+import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
 // Lazy: read at call time so a `configureApiClient` call that lands after this
 // module is imported still takes effect. Baking it at module-load time would
@@ -37,6 +37,10 @@ function assertCreds(creds, op) {
  * unchanged.
  */
 export function linkSummary(a) {
+    const side = (s) => ({
+        principal: s?.principal ?? null,
+        actor: s?.actor ?? null,
+    });
     return {
         agreementId: a.agreementId,
         // Kept deliberately: callers branch on this, and a summary that hides what
@@ -44,11 +48,11 @@ export function linkSummary(a) {
         engagementKind: a.engagementKind,
         status: a.status,
         proposalStatus: a.proposalStatus,
+        // No `payer`: a link carries no money, so the paying side is never occupied.
         parties: {
-            creatorAgent: a.parties?.creatorAgent ?? null,
-            providerAgent: a.parties?.providerAgent ?? null,
-            creator: a.parties?.creator ?? null,
-            proposedTo: a.parties?.proposedTo ?? null,
+            creator: side(a.parties?.creator),
+            provider: side(a.parties?.provider),
+            proposedTo: side(a.parties?.proposedTo),
         },
         ...(a.description ? { description: a.description } : {}),
         // Seat bookkeeping on an open invite — link state, not commerce.
@@ -169,8 +173,8 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
         ownerUserId: opts.ownerUserId,
         agentId: creds.agentId,
     });
-    const proposedTo = agreement.parties?.proposedTo;
-    if (isBroadcastTarget(proposedTo) || isBroadcastTarget(agreement.parties?.payer)) {
+    const proposedTo = agreement.parties?.proposedTo?.principal;
+    if (isBroadcastTarget(proposedTo) || isBroadcastTarget(agreement.parties?.payer?.principal)) {
         // respond is approve/reject on DIRECT proposals only. An open
         // broadcast (request, standing offer, link invite) has no per-recipient
         // approval slot — a BYSTANDER can neither approve nor reject it
@@ -206,11 +210,12 @@ export function resolvePendingApprovalPartyId(facts, candidateIds) {
     }
     // A row with no pending ledger entries is a legacy one (approvals[] predates
     //), and there the named responder slot IS the decision.
-    const proposedTo = facts.proposedTo ?? null;
-    if (proposedTo &&
-        actorIds.includes(proposedTo) &&
-        facts.pendingPartyIds.length === 0) {
-        return proposedTo;
+    if (facts.pendingPartyIds.length === 0) {
+        const responderIds = facts.proposedToIds ?? [];
+        for (const id of actorIds) {
+            if (responderIds.includes(id))
+                return id;
+        }
     }
     return null;
 }
@@ -223,7 +228,7 @@ export function resolveMyPendingApprovalPartyId(agreement, opts) {
         pendingPartyIds: (agreement.approvals ?? [])
             .filter((a) => a.status === 'pending' || a.status === 'PENDING')
             .map((a) => a.partyId),
-        proposedTo: agreement.parties?.proposedTo ?? null,
+        proposedToIds: partySideIds(agreement.parties?.proposedTo),
     }, [opts.agentId, opts.ownerUserId]);
 }
 /**
@@ -407,7 +412,7 @@ export async function getAgreement(agreementId, creds) {
     return agreement ? shapeAgreement(agreement) : null;
 }
 /**
- * Create a trust link — a direct proposal to one agent, or an open invite.
+ * Connect with someone — by email, by agent id, or with a shareable invite.
  *
  * This posts to `POST /agreements/links`. It used to post to `POST /agreements`,
  * which also created work agreements inline and skipped the gates the proposal
@@ -429,11 +434,15 @@ export async function createLink(body, creds) {
         throwApiError(res, responseBody, `Link creation failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/links');
+    if (data?.['status'] !== 'sent') {
+        throw new Error('Invalid response: expected { ok, status: "sent", shareUrl } from POST /agreements/links');
     }
-    const envelope = data;
-    return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
+    const shareUrl = data['shareUrl'];
+    return {
+        ok: data['ok'] === true,
+        status: 'sent',
+        shareUrl: typeof shareUrl === 'string' ? shareUrl : null,
+    };
 }
 export async function revokeAgreement(agreementId, creds) {
     if (!agreementId)
@@ -477,20 +486,15 @@ export async function fulfillAgreement(agreementId, creds) {
     const envelope = data;
     return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
 }
-/**
- * Claim an open agreement. Three shapes are claimable:
- * - open link invite (`engagementKind: link`, proposedTo everyone)
- * - open broadcast request (proposedTo 'everyone', status open)
- * - org-scoped broadcast request (proposedTo 'org') — the server rejects the
- *   claim with 403 if the caller is not a member of the agreement's orgId
- *
- * POST /agreements/:id/claim — canonical; no partyId in body.
- */
-export async function claimAgreement(agreementId, creds) {
+export async function claimAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
         throw new Error('agreementId is required to claim an open agreement');
     assertCreds(creds, 'open agreement claim');
-    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, { method: 'POST', headers: buildHeaders(creds) });
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}),
+    });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         throwApiError(res, body, `Open agreement claim failed: ${res.status} ${res.statusText}`);

package/dist/http/InboxClient.js

@@ -1,5 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+import { INBOX_HOST_CLAIMANT_HEADER, instanceIdentity, } from '../instanceIdentity.js';
 /**
  * The doorbell, not the door: references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -24,6 +25,9 @@ export class InboxClient {
         const headers = {
             Authorization: `Bearer ${this.operatorKey}`,
             'Content-Type': 'application/json',
+            // This process, not the API. Two fleets of the same agent share
+            // one backend task; without this they both wake.
+            [INBOX_HOST_CLAIMANT_HEADER]: instanceIdentity(),
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;

package/dist/http/MarketplaceClient.d.ts

@@ -23,7 +23,6 @@ export interface PullOffersOptions {
     since?: string;
 }
 export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
-export declare function claimOffer(agreementId: string, creds: Creds): Promise<Agreement>;
 export interface PublishRequestPayload {
     /** See PublishOfferPayload.billing. */
     billing?: 'total' | 'per_task';
@@ -53,7 +52,6 @@ export declare class MarketplaceClient {
     constructor(operatorKey: string, agentId?: string);
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
-    claimOffer(agreementId: string): Promise<Agreement>;
     publishRequest(payload: PublishRequestPayload): Promise<Agreement>;
     pullRequests(options?: PullRequestsOptions): Promise<Agreement[]>;
 }

package/dist/http/MarketplaceClient.js

@@ -52,24 +52,6 @@ export async function pullOffers(options, creds) {
     const data = await res.json().catch(() => null);
     return data?.['offers'] ?? [];
 }
-export async function claimOffer(agreementId, creds) {
-    if (!agreementId)
-        throw new Error('agreementId is required');
-    assertCreds(creds, 'marketplace offer claim');
-    const res = await fetch(`${getMarketplaceBaseUrl()}/offers/claim`, {
-        method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify({ agreementId }),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throwApiError(res, body, `Marketplace offer claim failed: ${res.status}`);
-    }
-    const data = await res.json().catch(() => null);
-    if (!data?.['ok'])
-        throw new Error(data?.['error'] || 'Claim failed');
-    return shapeAgreement(data['offer']);
-}
 export async function publishRequest(payload, creds) {
     assertCreds(creds, 'request publish');
     const res = await fetch(`${getMarketplaceBaseUrl()}/requests/publish`, {
@@ -120,7 +102,6 @@ export class MarketplaceClient {
     }
     publishOffer(payload) { return publishOffer(payload, this.creds); }
     pullOffers(options) { return pullOffers(options, this.creds); }
-    claimOffer(agreementId) { return claimOffer(agreementId, this.creds); }
     publishRequest(payload) { return publishRequest(payload, this.creds); }
     pullRequests(options) { return pullRequests(options, this.creds); }
 }

package/dist/http/TaskClient.js

@@ -1,4 +1,5 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { partyActorIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
 function buildHeaders(creds) {
@@ -159,13 +160,7 @@ async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
     const { listAgreements } = await import('./AgreementClient.js');
     const agreements = await listAgreements({ status: 'active' }, creds);
     const partyIds = agreements
-        .filter((a) => {
-        const p = a.parties ?? {};
-        return (p.provider === agentId ||
-            p.providerAgent === agentId ||
-            p.creator === agentId ||
-            p.payer === agentId);
-    })
+        .filter((a) => partyActorIds(a.parties).includes(agentId))
         .map((a) => a.agreementId)
         .filter(Boolean);
     if (partyIds.length === 0)

package/dist/http/agreementFlows.d.ts

@@ -1,4 +1,4 @@
-import { type ClaimedKind, type ProposeTerms } from './AgreementClient.js';
+import { type ClaimedKind, type ClaimOptions, type ProposeTerms } from './AgreementClient.js';
 import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 /**
  * one propose grammar. Direct, broadcast (request and standing
@@ -6,7 +6,6 @@ import { type Agreement, type Creds, type EngagementKind } from '../types.js';
  * single propose tool instead of dedicated publish/request tools.
  *
  * Routing:
- * - engagementKind 'link'                    → POST /agreements (link proposal / open invite)
  * - proposedTo 'everyone' | 'org', providerId = self  → seller-broadcast standing offer
  * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast request
  * - anything else                            → direct proposal
@@ -17,7 +16,7 @@ export interface UnifiedProposeInput extends ProposeTerms {
     chatId?: string;
     engagementKind?: EngagementKind;
 }
-export type ProposeShape = 'direct' | 'request' | 'offer' | 'link';
+export type ProposeShape = 'direct' | 'request' | 'offer';
 export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds): Promise<{
     agreement: Agreement;
     shape: ProposeShape;
@@ -36,7 +35,7 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
  * `kind` arrives on the claim response — the route that did the routing reports
  * which broadcast kind this turned out to be.
  */
-export declare function claimOpenAgreement(agreementId: string, creds: Creds): Promise<{
+export declare function claimOpenAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     agreement: Agreement;
     kind: ClaimedKind;
 }>;

package/dist/http/agreementFlows.js

@@ -1,20 +1,15 @@
-import { createLink, claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
 import { publishOffer } from './MarketplaceClient.js';
 import { isBroadcastTarget, } from '../types.js';
 export async function proposeUnified(input, creds) {
     const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
     if (!proposedTo)
         throw new Error('proposedTo is required (a user/agent id, or "everyone"/"org" to broadcast)');
-    if (engagementKind === 'link') {
-        // A link is an agreement, proposed to one agent (providerId) or opened as
-        // an invite (proposedTo 'everyone'); no chat, no money.
-        const target = isBroadcastTarget(proposedTo) ? undefined : proposedTo;
-        const { agreement } = await createLink({
-            ...(target ? { targetAgentId: target } : {}),
-            ...(terms.description ? { description: terms.description } : {}),
-        }, creds);
-        return { agreement, shape: 'link' };
-    }
+    // The 'link' arm is gone. A link is not a proposal shape: it has no
+    // price, no chat and no work, and it is formed by `link_propose`, which takes
+    // an email or an agent id and answers the same either way. Keeping a second
+    // door here would have meant a caller reaching a link through the propose
+    // grammar, where the constant answer and the org-root refusal do not apply.
     if (isBroadcastTarget(proposedTo)) {
         const audience = proposedTo;
         if (providerId && creds.agentId && providerId === creds.agentId) {
@@ -68,10 +63,10 @@ export async function proposeUnified(input, creds) {
  * `kind` arrives on the claim response — the route that did the routing reports
  * which broadcast kind this turned out to be.
  */
-export async function claimOpenAgreement(agreementId, creds) {
+export async function claimOpenAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
         throw new Error('agreementId is required');
-    const { agreement, kind } = await claimAgreement(agreementId, creds);
+    const { agreement, kind } = await claimAgreement(agreementId, creds, opts);
     // A server that has not shipped the `kind` field yet still claims correctly;
     // 'request' is the shape the route has always handled.
     return { agreement, kind: kind ?? 'request' };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, partySideIds, partyActorIds, } from './types.js';
 export type { PrincipalPresentation } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';
 export { configureApiClient, apiClientConfig } from './config.js';
@@ -11,5 +11,5 @@ export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
-export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, partySideIds, partyActorIds, } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';
 // the host injects the environment; this package never reads it.
 export { configureApiClient, apiClientConfig } from './config.js';

package/dist/instanceIdentity.d.ts

@@ -0,0 +1,4 @@
+export declare const INBOX_HOST_CLAIMANT_HEADER = "X-Ziggs-Instance";
+export declare function instanceIdentity(): string;
+/** Test seam: forget the memoized value so a case can set different env. */
+export declare function resetInstanceIdentityForTests(): void;

package/dist/instanceIdentity.js

@@ -0,0 +1,44 @@
+import { hostname } from 'node:os';
+/**
+ * Which process is calling GET /inbox.
+ *
+ * The exclusive-read claimant must be the *host* (this fleet task, a
+ * laptop fleet, an MCP process), not the API process. Two fleets share
+ * one backend task, so stamping the API's identity would let both wake.
+ *
+ * `ecs:<id>` on Fargate, `local:<host>:<pid>` otherwise. Env-derived
+ * and memoized.
+ */
+let cached = null;
+const MAX_LENGTH = 64;
+export const INBOX_HOST_CLAIMANT_HEADER = 'X-Ziggs-Instance';
+export function instanceIdentity() {
+    if (cached)
+        return cached;
+    cached = resolve().slice(0, MAX_LENGTH);
+    return cached;
+}
+/** Test seam: forget the memoized value so a case can set different env. */
+export function resetInstanceIdentityForTests() {
+    cached = null;
+}
+function resolve() {
+    const metadataUri = process.env.ECS_CONTAINER_METADATA_URI_V4 ??
+        process.env.ECS_CONTAINER_METADATA_URI;
+    if (metadataUri) {
+        const id = metadataUri.split('/').filter(Boolean).pop() ?? '';
+        const short = id.replace(/[^A-Za-z0-9]/g, '').slice(0, 12);
+        if (short.length >= 8)
+            return `ecs:${short}`;
+    }
+    const host = process.env.HOSTNAME || safeHostname();
+    return `local:${host}:${process.pid}`;
+}
+function safeHostname() {
+    try {
+        return hostname() || 'unknown-host';
+    }
+    catch {
+        return 'unknown-host';
+    }
+}

package/dist/relay/provisionRelayWorkers.d.ts

@@ -1,5 +1,5 @@
 import type { Agreement, Creds } from '../types.js';
-import { claimOffer, delegateAgreement, getMyAgreements, pullOffers } from '../http/index.js';
+import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers } from '../http/index.js';
 /** Minimal relay step shape — keep field names aligned with agents/coordinators/relayTypes.ts */
 export interface RelayStepInput {
     stepId: string;
@@ -28,7 +28,7 @@ export type ProvisionedRelayStep = RelayPayloadShape['steps'][number] & {
 export interface RelayProvisionDeps {
     getMyAgreements: typeof getMyAgreements;
     pullOffers: typeof pullOffers;
-    claimOffer: typeof claimOffer;
+    claimOpenAgreement: typeof claimOpenAgreement;
     delegateAgreement: typeof delegateAgreement;
 }
 export interface ProvisionRelayWorkersInput {

package/dist/relay/provisionRelayWorkers.js

@@ -1,6 +1,6 @@
-import { claimOffer, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
+import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
 function providerAgentId(agreement) {
-    return agreement.parties?.providerAgent ?? agreement.parties?.provider ?? null;
+    return agreement.parties?.provider?.actor ?? null;
 }
 function isActiveAgreement(agreement) {
     return agreement.status === 'active';
@@ -30,7 +30,7 @@ export function findOpenOfferForAgent(assigneeId, offers) {
 export async function provisionRelayWorkers(input, deps = {
     getMyAgreements,
     pullOffers,
-    claimOffer,
+    claimOpenAgreement,
     delegateAgreement,
 }) {
     const { creds, hireAgreementId, chatId, steps, inputArtifactIds } = input;
@@ -55,7 +55,7 @@ export async function provisionRelayWorkers(input, deps = {
             continue;
         }
         if (step.offerAgreementId) {
-            const claimed = await deps.claimOffer(step.offerAgreementId, creds);
+            const { agreement: claimed } = await deps.claimOpenAgreement(step.offerAgreementId, creds);
             const agreementId = claimed.agreementId;
             const status = isActiveAgreement(claimed)
                 ? 'active'
@@ -78,7 +78,7 @@ export async function provisionRelayWorkers(input, deps = {
         }
         const openOffer = findOpenOfferForAgent(step.assigneeId, offersCache);
         if (openOffer?.agreementId) {
-            const claimed = await deps.claimOffer(openOffer.agreementId, creds);
+            const { agreement: claimed } = await deps.claimOpenAgreement(openOffer.agreementId, creds);
             const agreementId = claimed.agreementId;
             const status = isActiveAgreement(claimed)
                 ? 'active'

package/dist/types.d.ts

@@ -91,19 +91,46 @@ export declare const AGREEMENT_ENGAGEMENT_KIND: {
     readonly LINK: "link";
 };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
+/**
+ * One side of an agreement.
+ *
+ * An agent id occupies `actor` and nowhere else, so "is this agent on this
+ * side?" is a structural read rather than a lookup against the Agent
+ * collection. Asking `principal` about an agent id is always the wrong
+ * question — it would match that agent's estate instead.
+ */
+export interface AgreementPartySide {
+    /**
+     * The accountable person or org — never an agent. On `payer` and `proposedTo`
+     * this may instead hold a broadcast sentinel ({@link isBroadcastTarget}), in
+     * which case nobody has taken the side up yet.
+     */
+    principal?: string | null;
+    /** The agent that performed on this side. Null when the principal acted itself. */
+    actor?: string | null;
+}
+/** The four sides of an agreement, each {@link AgreementPartySide}. */
+export interface AgreementParties {
+    payer?: AgreementPartySide;
+    provider?: AgreementPartySide;
+    proposedTo?: AgreementPartySide;
+    creator?: AgreementPartySide;
+}
+/** Both ids on one side, principal first, absent ones dropped. */
+export declare function partySideIds(side: AgreementPartySide | null | undefined): string[];
+/**
+ * Every agent that acted on this agreement, deduped.
+ *
+ * The read for "is this agent a party?" — an agent id lives in `actor` alone,
+ * so widening the match to `principal` would hit an unrelated estate.
+ */
+export declare function partyActorIds(parties: AgreementParties | null | undefined): string[];
 /** Compact agreement reference carried by task reads. */
 export interface AgreementSummary {
     agreementId: string;
     description: string;
     status: AgreementStatus;
-    parties?: {
-        proposedTo?: string | null;
-        provider?: string | null;
-        payer?: string | null;
-        creator?: string | null;
-        creatorAgent?: string | null;
-        providerAgent?: string | null;
-    };
+    parties?: AgreementParties;
     /** The opposite party relative to the requesting agent; null for observers,
      * broadcast sentinels, and self-agreements. */
     counterparty: string | null;
@@ -120,14 +147,7 @@ export interface Agreement {
     status?: AgreementStatus;
     engagementKind?: EngagementKind;
     proposalStatus?: ProposalStatus;
-    parties?: {
-        proposedTo?: string;
-        provider?: string;
-        payer?: string;
-        creator?: string;
-        creatorAgent?: string;
-        providerAgent?: string;
-    };
+    parties?: AgreementParties;
     approvals?: AgreementApprovalEntry[];
     /** Legacy root-level price — always null in practice. Use money.price instead. */
     price?: number | null;

package/dist/types.js

@@ -34,6 +34,24 @@ export const AGREEMENT_ENGAGEMENT_KIND = {
     /** a bilateral reach link between two agents (no money, no work). */
     LINK: 'link',
 };
+/** The four sides, in the order every fan-out walks them. */
+const AGREEMENT_PARTY_SIDES = ['payer', 'provider', 'proposedTo', 'creator'];
+/** Both ids on one side, principal first, absent ones dropped. */
+export function partySideIds(side) {
+    return [side?.principal, side?.actor].filter((id) => typeof id === 'string' && id.length > 0);
+}
+/**
+ * Every agent that acted on this agreement, deduped.
+ *
+ * The read for "is this agent a party?" — an agent id lives in `actor` alone,
+ * so widening the match to `principal` would hit an unrelated estate.
+ */
+export function partyActorIds(parties) {
+    const p = parties ?? {};
+    return [
+        ...new Set(AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => typeof id === 'string' && id.length > 0)),
+    ];
+}
 /** ⚠️ Mirrors the server's entry-type constant; the server is authoritative. */
 export const EntryTypes = {
     MESSAGE: 'message',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",