@ziggs-ai/api-client 0.6.1 → 0.7.1

package/dist/capabilities/agreements.js

@@ -10,8 +10,8 @@ export const agreementClaimCapability = {
     key: 'agreement_claim',
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with ziggs_marketplace_view; direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
+        sdk: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.',
+        mcp: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with ziggs_marketplace_view; direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
     },
     annotation: 'write',
     params: {
@@ -37,7 +37,9 @@ export const agreementClaimCapability = {
             kind,
             message: kind === 'offer'
                 ? 'Standing offer claimed — the publisher provides, your side pays. Spawn work under it with the task-create tool.'
-                : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
+                : kind === 'hand-off'
+                    ? 'Hand-off claimed — the pinned agent works FOR you: you are the customer (and the payer when priced), never the worker. Spawn work under it with the task-create tool.'
+                    : 'Quest claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
             agreement,
         };
     },

package/dist/capabilities/links.d.ts

@@ -7,7 +7,16 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * return it too (they used to leak the raw agreement doc).
  */
 export declare function linkSummary(a: Agreement): Record<string, unknown>;
-/** A link is reach-only — the follow-up move differs by surface tool names. */
+/**
+ * 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
+ * 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;

package/dist/capabilities/links.js

@@ -1,32 +1,22 @@
 import { createAgreement, listAgreements } from '../http/AgreementClient.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-/** Public Streamable-HTTP MCP endpoint; OAuth is discovered from it (RFC 9728). */
-const ZIGGS_MCP_URL = 'https://mcp.ziggsai.com/mcp';
 function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
 /**
- * The second form an invite travels in: text the recipient pastes into their
- * own assistant, which then connects itself and claims the invite. The claim
- * URL alone only helps someone who already has Ziggs and an assistant wired
- * up, so hand the caller both and let it pick per recipient.
+ * The one thing an invite travels as: `/connect/<inviteId>`.
+ *
+ * There used to be two forms — this URL plus a block of instructions to paste
+ * into the recipient's assistant — and the caller had to explain which was
+ * which and pick per recipient. That block now lives on the page itself, which
+ * is public and server-rendered: a person reads it, and an assistant handed the
+ * same URL fetches it and finds the MCP server address, the claim tool and the
+ * invite id in the markup. One link, both readers, nothing to keep in step
+ * across two repos.
  */
-function invitePasteText(agreementId, claimUrl) {
-    return [
-        'Connect me to Ziggs and accept this agent link invite.',
-        '',
-        `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
-        '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
-        '   but I may need to approve a consent screen in my browser.',
-        `2. Once connected, call the tool ziggs_agreement_claim with agreementId "${agreementId}".`,
-        '3. Then tell me who I am linked with, and what they can and cannot see.',
-        '',
-        'If you cannot add MCP servers yourself, tell me exactly where to paste that',
-        "URL in my assistant's settings, then continue from step 2.",
-        '',
-        `Invite link (if you need it in a browser instead): ${claimUrl}`,
-    ].join('\n');
+function inviteShareUrl(env, agreementId) {
+    return `${webAppOrigin(env)}/connect/${agreementId}`;
 }
 /**
  * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
@@ -49,11 +39,20 @@ export function linkSummary(a) {
         createdAt: a.createdAt,
     };
 }
-/** A link is reach-only — the follow-up move differs by surface tool names. */
+/**
+ * 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
+ * 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 function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only. Open a chat with the peer (ziggs_chat_open, participantId = peer agent id) and grant it chat access with ziggs_context_issue_grant, or share a slice of a grant you hold with ziggs_context_delegate, before reading context.'
-        : 'A link is reach-only: it does not grant context. Share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one, before reading.';
+        ? '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 delegates 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 delegates 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'];
 /**
@@ -71,8 +70,8 @@ export const createLinkInviteCapability = {
     key: 'link_create_invite',
     names: { sdk: 'link_create_invite', mcp: 'ziggs_link_create_invite' },
     descriptions: {
-        sdk: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId with agreement_claim. 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: agreement_propose with engagementKind \"link\" and proposedTo = 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"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_agreement_claim — neither side pastes an agent id. 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_agreement_propose with engagementKind "link" and proposedTo = that id.',
+        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: agreement_propose with engagementKind \"link\" and proposedTo = 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_agreement_propose with engagementKind "link" and proposedTo = that id.',
     },
     annotation: 'write',
     params: {
@@ -93,7 +92,7 @@ export const createLinkInviteCapability = {
             description: args['message'],
             ...(maxClaims == null ? {} : { maxClaims }),
         }, fullCreds(env));
-        const claimUrl = `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`;
+        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)`
@@ -101,13 +100,12 @@ export const createLinkInviteCapability = {
         return {
             status: 'open',
             inviteId: agreement.agreementId,
-            claimUrl,
+            shareUrl,
             maxClaims: seats,
             seatsRemaining: seats - (agreement.linkInvite?.claimsUsed ?? 0),
-            pasteText: invitePasteText(agreement.agreementId, claimUrl),
             message: env.surface === 'mcp'
-                ? `Open link invite created, ${seatNote}. Give the human BOTH forms and say which is which: claimUrl for a recipient who already uses Ziggs, pasteText for one who has an AI assistant but no Ziggs account — pasting it makes their assistant connect and claim the invite itself. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side.`
-                : `Open link invite created, ${seatNote}. Share claimUrl with a counterparty who already uses Ziggs, or pasteText with one who has an assistant but no Ziggs account yet — their assistant connects and claims it. A recipient with no Ziggs account can sign up straight from the link; no beta code needed. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
+                ? `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 needs their own assistant connected 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. They still need an assistant connected before the link carries anything. No agent id needed on either side. Revoke with agreement_revoke to disable.`,
             agreement: linkSummary(agreement),
         };
     },

package/dist/http/InboxClient.d.ts

@@ -28,6 +28,10 @@ export interface InboxProposalRef {
 export interface InboxConnectionRequestRef {
     requestId: string;
     requesterAgentId: string;
+    /** ZIG-1039 — human-readable name for consent cards. */
+    requesterDisplayName?: string | null;
+    /** ZIG-1039 — org label for consent cards. */
+    requesterOrgName?: string | null;
     message: string | null;
     requestedAt: string | null;
 }

package/dist/http/agreementFlows.d.ts

@@ -22,7 +22,7 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
     agreement: Agreement;
     shape: ProposeShape;
 }>;
-export type ClaimedKind = 'link' | 'offer' | 'quest';
+export type ClaimedKind = 'link' | 'offer' | 'quest' | 'hand-off';
 /**
  * ZIG-1021 — one claim verb for any open broadcast. Fetches the agreement to
  * route: link invites and quests claim through POST /agreements/:id/claim;

package/dist/http/agreementFlows.js

@@ -76,5 +76,10 @@ export async function claimOpenAgreement(agreementId, creds) {
         return { agreement, kind: 'offer' };
     }
     const { agreement } = await claimAgreement(agreementId, creds);
-    return { agreement, kind: 'quest' };
+    // ZIG-1059: a pinned provider inverts the quest reading — the publisher's
+    // hired agent does the work and the claimer is who it is done FOR.
+    return {
+        agreement,
+        kind: existing.providerPinned === true ? 'hand-off' : 'quest',
+    };
 }

package/dist/types.d.ts

@@ -113,6 +113,12 @@ export interface Agreement {
     } | null;
     /** Set on a link that was formed by claiming the invite with this id. */
     linkInviteTemplateId?: string | null;
+    /**
+     * ZIG-997/ZIG-1059 — the provider slot is FIXED (a hand-off): claiming or
+     * approving this makes you the party the work is done FOR, not the worker —
+     * and, when priced, the payer.
+     */
+    providerPinned?: boolean;
     metadata?: Record<string, unknown>;
     createdAt?: string;
     updatedAt?: string;

package/package.json

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