@ziggs-ai/api-client 0.6.3 → 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.js

@@ -1,53 +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>`.
  *
- * The account question comes FIRST, and the answer is always the claim URL —
- * never 'Create account' on the MCP consent screen. Signup is invite-gated and
- * only the claim URL carries the invite that waives it; the consent screen's
- * signup button carries nothing, and nothing in an MCP OAuth handshake can
- * carry it for them (the client builds its authorize request from RFC 8414/9728
- * discovery, so a query param on the pasted server URL never reaches us). So a
- * recipient new to Ziggs who lets their assistant lead used to hit a hard 403
- * with no way back. Ordering is the whole fix: the URL both signs them up AND
- * claims, leaving the assistant less to do, not more.
- *
- * Keep in step with the web app's copy of this text (frontend
- * src/lib/links/inviteShare.ts) — same instructions, two surfaces.
+ * 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.',
-        '',
-        'First ask me: do I already have a Ziggs account?',
-        '',
-        `  If no, or I am not sure — open this in a browser: ${claimUrl}`,
-        '  That creates my account and accepts the link in one step, and needs no',
-        "  invite code. Do NOT send me to 'Create account' on the Ziggs consent",
-        '  screen instead — signup there is gated and will reject me. Once I am',
-        '  back, continue from step 1 to connect yourself; step 2 is already done.',
-        '',
-        '  If yes — start at step 1.',
-        '',
-        `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.",
-    ].join('\n');
+function inviteShareUrl(env, agreementId) {
+    return `${webAppOrigin(env)}/connect/${agreementId}`;
 }
 /**
  * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
@@ -101,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: {
@@ -123,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)`
@@ -131,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 is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient who would rather their own assistant do the wiring; it starts by sending them to claimUrl if they have no account yet, since signup on the MCP consent screen is gated and would reject them. Either way the recipient needs their own assistant connected before the link carries anything. No agent id needed on either side.`
-                : `Open link invite created, ${seatNote}. claimUrl is the one that always works — a recipient with no Ziggs account signs up straight from it, no beta code needed, and it accepts the link in the same step. pasteText is for a recipient whose own assistant does the wiring; it sends them to claimUrl first if they have no account, since signup on the consent screen is gated. Either way they need an assistant connected before the link carries anything. 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/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.3",
+  "version": "0.7.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",