@ziggs-ai/api-client 0.13.0 → 0.14.0

package/dist/capabilities/agreements.js

@@ -1,6 +1,14 @@
 import { claimOpenAgreement } from '../http/agreementFlows.js';
-import { linkIsReachOnly } from './links.js';
+import { linkIsReachOnly, webAppOrigin } from './links.js';
 import { fullCreds } from './types.js';
+/** Which side the claimer just took, for a claim that has not activated yet. */
+function claimedWhat(kind) {
+    if (kind === 'offer')
+        return 'Standing offer claimed — the publisher provides, your side pays.';
+    if (kind === 'hand-off')
+        return 'Hand-off claimed — the pinned agent works FOR you.';
+    return 'Request claimed — you provide the work.';
+}
 /**
  * the one claim verb. Requests, standing offers, and link invites
  * are all open broadcasts; claiming any of them is this call. The respond
@@ -11,8 +19,8 @@ export const agreementClaimCapability = {
     names: { sdk: 'agreement_claim', mcp: 'ziggs_agreement_claim' },
     title: 'Claim a posted agreement',
     descriptions: {
-        sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (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 requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
-        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (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 requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. 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 — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.',
+        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (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. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast.',
     },
     annotation: 'write',
     params: {
@@ -45,6 +53,28 @@ export const agreementClaimCapability = {
                 agreement,
             };
         }
+        // A claim only activates when the claimer could consent for its own side.
+        // When it did not, say what the row actually says — and hand over the link
+        // where the human answers: the assistant is the human's only
+        // screen and it is refused if it tries to answer for them, so the URL IS
+        // the remaining loop. The held reason picks the one sentence that helps:
+        // a formation gate has the mandate remedy; a contact gate is a one-time
+        // stranger ask that a standing link retires.
+        if (agreement?.status !== 'active') {
+            const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
+            const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
+            const remedy = held?.heldReason === 'contact-basis'
+                ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
+                : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';
+            return {
+                status: 'claimed',
+                kind,
+                message: `${claimedWhat(kind)} It is not active yet: the formation is waiting on ` +
+                    'human approval, so nothing can be created under it until that lands. ' +
+                    `Your human can approve it here: ${approveUrl} — ${remedy}`,
+                agreement,
+            };
+        }
         return {
             status: 'claimed',
             kind,

package/dist/capabilities/index.d.ts

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, type NextCall, } fr
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.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

@@ -3,6 +3,7 @@ export { nextCall, peerPrincipalId, peerPrincipalForCourier, } from './nextCall.
 export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
+export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.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/introductions.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const mintIntroductionCapability: CapabilityDefinition;
+export declare const redeemIntroductionCapability: CapabilityDefinition;
+export declare const listIntroductionsCapability: CapabilityDefinition;
+export declare const revokeIntroductionCapability: CapabilityDefinition;
+export declare const INTRODUCTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/introductions.js

@@ -0,0 +1,172 @@
+import { IntroductionsClient } from '../http/IntroductionsClient.js';
+import { nextCall } from './nextCall.js';
+import { fullCreds } from './types.js';
+/**
+ * The one thing to exchange when you meet an agent off Ziggs.
+ *
+ * Three tools, because there are exactly three moves: hand one over, redeem one
+ * you were handed, and look at what became of the ones you handed out. Raw agent
+ * ids stop being the exchange: an id pasted into a game or a chat room is
+ * unverifiable, works only if the other side is already on Ziggs, and leaves no
+ * record that the meeting happened at all.
+ */
+const ZERO_AUTHORITY = 'The token carries no authority: handing it over widens nobody\'s reach, and the link it stages is a normal link proposal the two people sign.';
+export const mintIntroductionCapability = {
+    key: 'introduction_mint',
+    names: { sdk: 'introduction_mint', mcp: 'ziggs_introduction_mint' },
+    title: 'Hand someone an introduction',
+    descriptions: {
+        sdk: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable, and you can see what became of it with introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting.`,
+        mcp: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Say the token string or its url in that venue; whoever redeems it lands in a pending link with you, which your human approves via ziggs_agreement_respond. ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable with ziggs_introduction_revoke, and the outcome shows up in ziggs_introduction_list. Prefer this over pasting your agent id: an id is unverifiable where you met, useless to anyone not on Ziggs yet, and leaves no record of the meeting. If the other side is not on Ziggs at all, the url is still the right thing to hand over — that page tells their agent how to board itself.`,
+    },
+    annotation: 'write',
+    params: {
+        venue: {
+            type: 'string',
+            description: 'Where you met, as you would name it (e.g. village.ziggsai.com). Recorded as the mint context.',
+        },
+        venueRef: {
+            type: 'string',
+            description: 'Finer address inside that venue: a character, a room, a table.',
+        },
+        note: {
+            type: 'string',
+            description: 'One line for the other side to read when they open it — why you want to connect.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.mint({
+            ...(args['venue'] ? { venue: args['venue'] } : {}),
+            ...(args['venueRef'] ? { venueRef: args['venueRef'] } : {}),
+            ...(args['note'] ? { note: args['note'] } : {}),
+        });
+        return {
+            introduction: intro,
+            hand_over: intro.token,
+            message: `Say this where you met them: ${intro.token} (or the full url ${intro.url}, which explains itself to an agent that is not on Ziggs yet). One use, expires ${intro.expiresAt}.`,
+            readPlan: [
+                nextCall(env, 'introduction_list', undefined, 'check whether it was redeemed, declined or is still open'),
+            ],
+        };
+    },
+};
+export const redeemIntroductionCapability = {
+    key: 'introduction_redeem',
+    names: { sdk: 'introduction_redeem', mcp: 'ziggs_introduction_redeem' },
+    title: 'Redeem an introduction you were handed',
+    descriptions: {
+        sdk: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you which the two people approve — then reach them with chat_open on the `from.agentId` this returns, which is the door to that person; if you already share an org or an estate, it says so instead of minting a pointless link. One use — a second redeem is refused.',
+        mcp: 'Redeem an introduction token someone handed you (POST /introductions/:token/redeem). If they are a stranger, this stages a link proposal from them to you — approve it with ziggs_agreement_respond, then open a room with ziggs_chat_open using the `from.agentId` this returns (the party principal on a link is not an address; their agent is the door). If you already share an org or an estate, it tells you that instead of minting a pointless link. One use — a second redeem is refused. Trust nothing about an identity claimed in the venue itself: what makes this real is that the token resolved on Ziggs.',
+    },
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token you were given (starts with zint_).',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.redeem(String(args['token'] ?? '').trim());
+        const staged = intro.outcome === 'link_pending';
+        return {
+            introduction: intro,
+            message: staged
+                ? `Redeemed. ${intro.from.label} now has a pending link with you (${intro.agreementId}). It becomes real when both people approve it — a link is reach only, and shares no context by itself.`
+                : intro.outcome === 'already_teammates'
+                    ? 'Redeemed, and there was nothing to link: you already answer to the same org or the same person. Talk to them directly.'
+                    : 'Redeemed. You two are already linked, so nothing new was proposed.',
+            // An already-linked or already-teammates redemption is not a dead end: the
+            // relationship exists, so the next move is simply to talk. Leaving the
+            // plan empty there read as "nothing to do" on the branch a returning
+            // counterparty is most likely to land on.
+            readPlan: !staged
+                ? intro.counterparty?.agentId
+                    ? [
+                        nextCall(env, 'chat_open', { participantId: intro.counterparty.agentId }, 'you already have a relationship — this is the door to their agent'),
+                    ]
+                    : []
+                : [
+                    nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your side approves it here'),
+                    // The minter's AGENT, not their principal. A link's party principal
+                    // can be a persona face, which the chat rail refuses as an address
+                    // ("a face is display state and names no single party") — so the
+                    // door to that person is the agent that carried the introduction.
+                    ...(intro.from.agentId
+                        ? [
+                            nextCall(env, 'chat_open', { participantId: intro.from.agentId }, 'once the link is live, this is the door to the agent that introduced itself'),
+                        ]
+                        : []),
+                ],
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const listIntroductionsCapability = {
+    key: 'introduction_list',
+    names: { sdk: 'introduction_list', mcp: 'ziggs_introduction_list' },
+    title: 'Introductions you handed out',
+    descriptions: {
+        sdk: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs.',
+        mcp: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs. Take one back with ziggs_introduction_revoke.',
+    },
+    annotation: 'read-only',
+    params: {
+        limit: { type: 'number', description: 'How many to return (default 50).' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const limit = args['limit'];
+        const items = await client.listMine(limit);
+        return {
+            count: items.length,
+            introductions: items,
+            open: items.filter((i) => i.status === 'open').length,
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const revokeIntroductionCapability = {
+    key: 'introduction_revoke',
+    names: { sdk: 'introduction_revoke', mcp: 'ziggs_introduction_revoke' },
+    title: 'Take back an introduction',
+    descriptions: {
+        sdk: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open.',
+        mcp: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open — once redeemed, end the link it staged with ziggs_agreement_revoke instead.',
+    },
+    // A write, not a destructive act: nobody holds anything from an unredeemed
+    // hello, so taking one back removes no access and loses no data. The
+    // destructive annotation is reserved for the two tools that end live access.
+    annotation: 'write',
+    params: {
+        token: {
+            type: 'string',
+            required: true,
+            description: 'The introduction token to take back.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new IntroductionsClient(creds.operatorKey, creds.agentId);
+        const intro = await client.revoke(String(args['token'] ?? '').trim());
+        return {
+            introduction: intro,
+            message: 'Taken back. Anyone still holding that string gets nothing.',
+        };
+    },
+};
+export const INTRODUCTION_CAPABILITIES = [
+    mintIntroductionCapability,
+    redeemIntroductionCapability,
+    listIntroductionsCapability,
+    revokeIntroductionCapability,
+];

package/dist/capabilities/links.d.ts

@@ -1,4 +1,5 @@
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+export declare function webAppOrigin(env: CapabilityEnv): string;
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *

package/dist/capabilities/links.js

@@ -2,7 +2,7 @@ import { createLink, listAgreements } from '../http/AgreementClient.js';
 import { nextCall, peerPrincipalForCourier, } from './nextCall.js';
 import { fullCreds } from './types.js';
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-function webAppOrigin(env) {
+export function webAppOrigin(env) {
     return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
 }
 /**

package/dist/http/ChatClient.d.ts

@@ -16,7 +16,17 @@ export declare function openConversation(participantId: string, creds: Creds, {
     reused?: boolean;
 }>;
 export interface SendChatMessageInput {
-    chatId: string;
+    /**
+     * Chat to send in. Required unless `to` names a person you already
+     * share a conversation with.
+     */
+    chatId?: string;
+    /**
+     * User or agent id of someone you already have a conversation with.
+     * Resolves that pair room and sends. Does not open contact. Ignored
+     * when `chatId` is set (`chatId` wins).
+     */
+    to?: string;
     /**
      * Recipient id. Optional: when omitted, the backend infers the
      * receiver if the chat has exactly one other member (one agent, or one
@@ -67,7 +77,8 @@ export type AddChatMemberResult = {
  */
 export declare function addChatMember(input: AddChatMemberInput, creds: Creds): Promise<AddChatMemberResult>;
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;

package/dist/http/ChatClient.js

@@ -78,17 +78,27 @@ export async function addChatMember(input, creds) {
     return { chat: data['chat'] };
 }
 /**
- * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
+ * an existing participant and `chatId` is omitted.
  */
 export async function sendChatMessage(input, creds) {
     assertCreds(creds, 'send chat message');
+    const chatId = typeof input.chatId === 'string' ? input.chatId.trim() : '';
+    const to = typeof input.to === 'string' ? input.to.trim() : '';
+    if (!chatId && !to) {
+        throw new Error('chatId or to is required for send chat message');
+    }
     const entryType = input.entryType ?? 'message';
     const contentType = input.contentType ?? 'text';
-    const res = await fetch(`${getBackendUrl()}/chats/${encodeURIComponent(input.chatId)}/messages`, {
+    const personSend = !chatId && Boolean(to);
+    const url = personSend
+        ? `${getBackendUrl()}/chats/messages`
+        : `${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`;
+    const res = await fetch(url, {
         method: 'POST',
         headers: buildHeaders(creds),
         body: JSON.stringify({
-            chatId: input.chatId,
+            ...(personSend ? { to } : { chatId }),
             messageId: input.messageId,
             text: input.text,
             entryType,
@@ -109,7 +119,7 @@ export async function sendChatMessage(input, creds) {
         success: Boolean(data?.['success']),
         message: String(data?.['message'] ?? 'ok'),
         messageId: String(data?.['messageId'] ?? input.messageId),
-        chatId: String(data?.['chatId'] ?? input.chatId),
+        chatId: String(data?.['chatId'] ?? chatId),
     };
 }
 export async function listMyChats(creds) {

package/dist/http/IntroductionsClient.d.ts

@@ -0,0 +1,60 @@
+/** What became of one hello. `expired` is derived by the server, not stored. */
+export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' | 'expired';
+export type IntroductionOutcome = 'link_pending' | 'already_teammates' | 'already_linked';
+export interface IntroductionView {
+    token: string;
+    status: IntroductionStatus;
+    outcome: IntroductionOutcome | null;
+    from: {
+        label: string;
+        agentId: string | null;
+        orgId: string;
+    };
+    venue: string | null;
+    venueRef: string | null;
+    note: string | null;
+    agreementId: string | null;
+    redeemedBy: {
+        agentId: string | null;
+        orgId: string | null;
+    } | null;
+    expiresAt: string;
+    /** The public page the string points at. This is what you hand over. */
+    url: string;
+    /**
+     * Returned to a redeemer only: the two ids the meeting is now worth, and what
+     * each is for. `agentId` is where messages go; `principal` is who can be a
+     * party to an agreement. Passing one where the other belongs is refused as if
+     * the agent did not exist, which is the wall this field exists to remove.
+     */
+    counterparty?: {
+        principal: string;
+        agentId: string | null;
+        label: string;
+        nextStep: string;
+    };
+}
+export interface MintIntroductionInput {
+    venue?: string;
+    venueRef?: string;
+    note?: string;
+}
+/**
+ * Introduction tokens — the one object to exchange when you meet an
+ * agent somewhere Ziggs does not own.
+ *
+ * The token carries no authority, which is why minting one is free: it widens
+ * nobody's reach. Redeeming one stages a link proposal the two humans sign.
+ */
+export declare class IntroductionsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    mint(input?: MintIntroductionInput): Promise<IntroductionView>;
+    redeem(token: string): Promise<IntroductionView>;
+    decline(token: string): Promise<IntroductionView>;
+    revoke(token: string): Promise<IntroductionView>;
+    listMine(limit?: number): Promise<IntroductionView[]>;
+    private call;
+}

package/dist/http/IntroductionsClient.js

@@ -0,0 +1,54 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * Introduction tokens — the one object to exchange when you meet an
+ * agent somewhere Ziggs does not own.
+ *
+ * The token carries no authority, which is why minting one is free: it widens
+ * nobody's reach. Redeeming one stages a link proposal the two humans sign.
+ */
+export class IntroductionsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey) {
+            throw new Error('IntroductionsClient: operatorKey is required');
+        }
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    async mint(input = {}) {
+        return this.call('POST', '/introductions', input, 'mint');
+    }
+    async redeem(token) {
+        return this.call('POST', `/introductions/${encodeURIComponent(token)}/redeem`, {}, 'redeem');
+    }
+    async decline(token) {
+        return this.call('POST', `/introductions/${encodeURIComponent(token)}/decline`, {}, 'decline');
+    }
+    async revoke(token) {
+        return this.call('DELETE', `/introductions/${encodeURIComponent(token)}`, undefined, 'revoke');
+    }
+    async listMine(limit) {
+        const query = limit != null ? `?limit=${encodeURIComponent(String(limit))}` : '';
+        return this.call('GET', `/introductions${query}`, undefined, 'listMine');
+    }
+    async call(method, path, body, label) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                ...buildOperatorHeaders(this.operatorKey, this.agentId),
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `IntroductionsClient.${label} failed: ${res.status}`);
+        }
+        return JSON.parse(text);
+    }
+}

package/dist/http/TaskClient.d.ts

@@ -13,6 +13,7 @@ export interface TaskWriteConfirm {
     structureChanged?: boolean;
     stepId?: string;
     stepStatus?: string;
+    patchedCount?: number;
     resultRecorded?: boolean;
     terminalState?: string;
     [key: string]: unknown;
@@ -23,6 +24,20 @@ export interface TaskWriteConfirm {
  * subcontract inputs rather than teaching those routes to keep one.
  */
 export type PlanReviewTiming = 'with_proposal' | 'before_execution';
+export interface CreateTaskGraphNodeData {
+    nodeId: string;
+    agreementId: string;
+    description: string;
+    title?: string;
+    assigneeId?: string;
+    waitsOn?: string[];
+    joinKind?: 'all' | 'any';
+}
+export interface CreateTaskGraphData {
+    nodes: CreateTaskGraphNodeData[];
+    inputArtifactIds?: string[];
+    review?: 'before_execution';
+}
 export interface CreateTaskData {
     description: string;
     /**
@@ -55,6 +70,8 @@ export interface CreateTaskData {
      * the shape in its own control flow where nothing else can see it.
      */
     waitsOn?: string[];
+    /** Atomically declare a native work graph beneath the returned root task. */
+    graph?: CreateTaskGraphData;
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
@@ -91,6 +108,13 @@ export interface PlanReplaceStep {
     result?: unknown;
 }
 export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<TaskWriteConfirm>;
+/** Named-step progress — only the listed steps change. */
+export type PlanStepPatch = {
+    stepId: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped';
+    result?: unknown;
+};
+export declare function updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[], creds: Creds): Promise<TaskWriteConfirm>;
 export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<TaskWriteConfirm>;
@@ -135,6 +159,7 @@ export declare class TaskClient {
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<TaskWriteConfirm>;
     updateTaskPlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<TaskWriteConfirm>;
+    updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[]): Promise<TaskWriteConfirm>;
     reportTask(taskId: string, message?: string): Promise<TaskWriteConfirm>;
     setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<TaskWriteConfirm>;
     listTasks(options?: ListTasksOptions): Promise<ListTasksResult>;

package/dist/http/TaskClient.js

@@ -55,6 +55,7 @@ function extractWriteConfirm(data) {
                 : {}),
             ...(typeof d['stepId'] === 'string' ? { stepId: d['stepId'] } : {}),
             ...(typeof d['stepStatus'] === 'string' ? { stepStatus: d['stepStatus'] } : {}),
+            ...(typeof d['patchedCount'] === 'number' ? { patchedCount: d['patchedCount'] } : {}),
             ...(d['resultRecorded'] === true ? { resultRecorded: true } : {}),
             ...(typeof d['terminalState'] === 'string'
                 ? { terminalState: d['terminalState'] }
@@ -152,10 +153,29 @@ export async function getActiveTasksForAgent(agentId, creds) {
     const data = await res.json().catch(() => null);
     const fromAgent = Array.isArray(data?.['tasks']) ? data['tasks'] : [];
     if (fromAgent.length > 0)
-        return fromAgent;
+        return workable(fromAgent);
     // Fallback when /agents/:id/tasks is empty but party-agreement tasks exist.
     return getActiveTasksForAgentViaPartyAgreements(agentId, creds);
 }
+/**
+ * Drop the tasks the platform created but deliberately did not deliver.
+ *
+ * `heldByDeps` is a DELIVERY condition, not a task state: a task waiting on its
+ * `waitsOn` edges is genuinely `active`, so `?state=active` returns it and the
+ * assignee's own work list hands over a task nobody woke it for. Every caller of
+ * this function is asking "what can I act on now", and for a withheld row the
+ * answer is nothing — `updateTaskState` refuses it with `dependencies_unmet`.
+ * Two of AgentHost's three callers do worse than waste a wake: the needs gate
+ * and the unmet-access sweep both FAIL the tasks they find, so a withheld node
+ * was one missing grant away from being failed before its turn came.
+ *
+ * Filtered here rather than at `/agents/:id/tasks`, which is also the route the
+ * UI lists an agent's work with — a person looking at the graph should see the
+ * withheld node sitting there waiting, which is the whole point of a join.
+ */
+function workable(tasks) {
+    return tasks.filter((t) => t.heldByDeps !== true);
+}
 async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
     const { listAgreements } = await import('./AgreementClient.js');
     const agreements = await listAgreements({ status: 'active' }, creds);
@@ -175,7 +195,7 @@ async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
         return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
     }));
     const merged = lists.flat();
-    return merged.filter((t) => !t.assigneeId || t.assigneeId === agentId);
+    return workable(merged.filter((t) => !t.assigneeId || t.assigneeId === agentId));
 }
 // Backend deliberately has no `/chats/:id/tasks` route — it's composable
 // from links → per-agreement tasks. We do the composition here so callers
@@ -263,6 +283,34 @@ export async function replaceTaskPlan(taskId, steps, creds) {
         throw new Error('Invalid response: task write confirm not found');
     return confirm;
 }
+export async function updateTaskPlanSteps(taskId, patches, creds) {
+    if (!taskId)
+        throw new Error('updateTaskPlanSteps: taskId is required');
+    if (!patches || !Array.isArray(patches) || patches.length === 0) {
+        throw new Error('updateTaskPlanSteps: patches must name at least one step');
+    }
+    for (const patch of patches) {
+        if (!patch?.stepId)
+            throw new Error('updateTaskPlanSteps: each patch needs a stepId');
+        if (!patch?.status)
+            throw new Error('updateTaskPlanSteps: each patch needs a status');
+    }
+    assertCreds(creds, 'plan step patch');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ patches }),
+    });
+    if (!res.ok) {
+        const responseBody = await res.text().catch(() => '');
+        throwApiError(res, responseBody, `Plan step patch failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
+}
 export async function updateTaskPlanStep(taskId, stepId, status, result, creds) {
     if (!taskId)
         throw new Error('updateTaskPlanStep: taskId is required');
@@ -406,6 +454,7 @@ export class TaskClient {
     getSubtasks(parentTaskId) { return getSubtasks(parentTaskId, this.creds); }
     replaceTaskPlan(taskId, steps) { return replaceTaskPlan(taskId, steps, this.creds); }
     updateTaskPlanStep(taskId, stepId, status, result) { return updateTaskPlanStep(taskId, stepId, status, result, this.creds); }
+    updateTaskPlanSteps(taskId, patches) { return updateTaskPlanSteps(taskId, patches, this.creds); }
     reportTask(taskId, message) { return reportTask(taskId, message, this.creds); }
     setTaskSatisfaction(taskId, satisfaction) { return setTaskSatisfaction(taskId, satisfaction, this.creds); }
     listTasks(options) { return listTasks(options ?? {}, this.creds); }

package/dist/http/index.d.ts

@@ -11,6 +11,8 @@ export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, par
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
+export { IntroductionsClient } from './IntroductionsClient.js';
+export type { IntroductionView, IntroductionStatus, IntroductionOutcome, MintIntroductionInput, } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';

package/dist/http/index.js

@@ -9,6 +9,7 @@ export { ArtifactsClient,
 artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
+export { IntroductionsClient } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 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, partySideIds, partyActorIds, } from './types.js';
 export type { PrincipalPresentation } from './types.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 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, partySideIds, partyActorIds, } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';

package/dist/types.d.ts

@@ -79,6 +79,16 @@ export interface Task {
      * from "nobody has picked it up" — this one is waiting on purpose.
      */
     heldByDeps?: boolean;
+    joinKind?: 'all' | 'any';
+    graph?: {
+        nodes: Array<{
+            nodeId: string;
+            taskId: string;
+        }>;
+        review?: 'before_execution';
+    } | null;
+    graphNodeId?: string | null;
+    heldByGraphReview?: boolean;
     plan?: {
         steps?: PlanStep[];
     };
@@ -148,6 +158,8 @@ export interface AgreementApprovalEntry {
     role?: string;
     status?: string;
     respondedAt?: string | null;
+    /** Why a pending slot is held (e.g. 'formation-gate', 'contact-basis'), when the server said. */
+    heldReason?: string | null;
 }
 export interface Agreement {
     agreementId: string;

package/package.json

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

package/dist/relay/provisionRelayWorkers.d.ts

@@ -1,119 +0,0 @@
-import type { Agreement, Creds } from '../types.js';
-import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, type DelegateContextGrantResult, type GrantView } from '../http/index.js';
-/** Minimal relay step shape — keep field names aligned with agents/coordinators/relayTypes.ts */
-export interface RelayStepInput {
-    stepId: string;
-    order: number;
-    assigneeId: string;
-    description: string;
-    /** Standing offer agreementId to claim for this worker (optional). */
-    offerAgreementId?: string;
-}
-export interface RelayPayloadShape {
-    inputArtifactIds?: string[];
-    steps: Array<{
-        stepId: string;
-        order: number;
-        agreementId: string;
-        assigneeId: string;
-        description: string;
-    }>;
-}
-export type ProvisionMethod = 'existing' | 'claim' | 'delegate';
-export type StepProvisionStatus = 'active' | 'pending_approval';
-/**
- * What happened to the coordinator's pass on this worker contract.
- *
- *  - `granted`  — the coordinator may create work citing this contract.
- *  - `reused`   — it already held one; nothing was minted.
- *  - `pending_approval` — the pass needs a person. An agent cannot MINT a root
- *    agreement grant at all: `POST /context/grants` requires the `context:grant`
- *    operator scope, which a delegate never holds ("no re-mint or grant will
- *    satisfy this"). So an initiator agent's only route is delegating the
- *    participation grant it holds — and handing a slice to a third party in
- *    another org opens a card that owner must approve.
- *  - `deferred` — the contract itself is not active yet, so there is no
- *    participation grant to delegate from. Provision again after it activates.
- *  - `failed`   — named so the caller stops rather than kicking off a run whose
- *    branches will each be refused one at a time.
- */
-export type GrantProvisionStatus = 'granted' | 'reused' | 'pending_approval' | 'deferred' | 'failed';
-export interface StepGrantProvision {
-    status: GrantProvisionStatus;
-    grantId?: string;
-    /** The approval card's agreement id, when a person has to say yes. */
-    approvalAgreementId?: string;
-    error?: string;
-}
-export type ProvisionedRelayStep = RelayPayloadShape['steps'][number] & {
-    provisionMethod: ProvisionMethod;
-    status: StepProvisionStatus;
-    /**
-     * The coordinator's pass on this step's contract. Handing over an agreement
-     * id is not enough: membership in work is a grant, and the coordinator is not
-     * a party to this contract, so nothing about it reaches the coordinator
-     * otherwise.
-     */
-    grant: StepGrantProvision;
-};
-export interface RelayProvisionDeps {
-    getMyAgreements: typeof getMyAgreements;
-    pullOffers: typeof pullOffers;
-    claimOpenAgreement: typeof claimOpenAgreement;
-    delegateAgreement: typeof delegateAgreement;
-    /**
-     * Grants on one agreement scope. `role` picks which side: `holder` is what
-     * this initiator holds (the participation grant to delegate FROM), `issuer` is
-     * what it has already caused (so a re-provision reuses rather than re-mints).
-     */
-    listAgreementGrants: (args: {
-        agreementId: string;
-        role: 'holder' | 'issuer';
-    }, creds: Creds) => Promise<GrantView[]>;
-    delegateAgreementGrant: (args: {
-        parentGrantId: string;
-        holderId: string;
-        agreementId: string;
-    }, creds: Creds) => Promise<DelegateContextGrantResult>;
-}
-export interface ProvisionRelayWorkersInput {
-    creds: Creds;
-    hireAgreementId: string;
-    /**
-     * The coordinator that will create the work. Required, because provisioning a
-     * worker FOR a coordinator is two acts and this names who the second one is
-     * for: without an `agreement`-scope grant on each worker contract, the
-     * coordinator's very first `task_create` is refused with "holds no grant on
-     * agreement …" and every branch of the run fails the same way.
-     */
-    coordinatorId: string;
-    chatId?: string;
-    steps: RelayStepInput[];
-    inputArtifactIds?: string[];
-}
-export interface ProvisionRelayWorkersResult {
-    payload: RelayPayloadShape;
-    steps: ProvisionedRelayStep[];
-    /**
-     * Everything a person still has to approve before kickoff — agreement
-     * activations AND grant hand-overs, in one list. They gate the run
-     * identically, so splitting them would just make a caller check two.
-     */
-    pendingApprovals: string[];
-    readyForKickoff: boolean;
-}
-type AgreementWithParent = Agreement & {
-    parentAgreementId?: string;
-};
-export declare function findExistingWorkerDelegation(hireAgreementId: string, assigneeId: string, agreements: AgreementWithParent[]): AgreementWithParent | null;
-export declare function findOpenOfferForAgent(assigneeId: string, offers: Agreement[]): Agreement | null;
-/**
- * The default grant plumbing, built on the two clients that own these routes.
- *
- * A thin function seam rather than the clients themselves, so a test can drive
- * provisioning without a backend — the same reason the agreement calls are
- * injected.
- */
-export declare function defaultRelayProvisionDeps(): RelayProvisionDeps;
-export declare function provisionRelayWorkers(input: ProvisionRelayWorkersInput, deps?: RelayProvisionDeps): Promise<ProvisionRelayWorkersResult>;
-export {};

package/dist/relay/provisionRelayWorkers.js

@@ -1,267 +0,0 @@
-import { ContextGrantsClient, GrantsClient, claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
-function providerAgentId(agreement) {
-    return agreement.parties?.provider?.actor ?? null;
-}
-function isActiveAgreement(agreement) {
-    return agreement.status === 'active';
-}
-export function findExistingWorkerDelegation(hireAgreementId, assigneeId, agreements) {
-    const matches = agreements.filter((a) => {
-        if (a.parentAgreementId !== hireAgreementId)
-            return false;
-        if (!isActiveAgreement(a))
-            return false;
-        return providerAgentId(a) === assigneeId;
-    });
-    matches.sort((a, b) => {
-        const ta = a.updatedAt ?? a.createdAt ?? '';
-        const tb = b.updatedAt ?? b.createdAt ?? '';
-        return tb.localeCompare(ta);
-    });
-    return matches[0] ?? null;
-}
-export function findOpenOfferForAgent(assigneeId, offers) {
-    return (offers.find((o) => {
-        if (o.status !== 'open' && o.status !== 'active')
-            return false;
-        return providerAgentId(o) === assigneeId;
-    }) ?? null);
-}
-/**
- * The default grant plumbing, built on the two clients that own these routes.
- *
- * A thin function seam rather than the clients themselves, so a test can drive
- * provisioning without a backend — the same reason the agreement calls are
- * injected.
- */
-export function defaultRelayProvisionDeps() {
-    return {
-        getMyAgreements,
-        pullOffers,
-        claimOpenAgreement,
-        delegateAgreement,
-        listAgreementGrants: async ({ agreementId, role }, creds) => {
-            const client = new GrantsClient(creds.operatorKey, creds.agentId);
-            return client.listAllGrants({
-                scopeKind: 'agreement',
-                scopeId: agreementId,
-                role,
-                health: 'active',
-            });
-        },
-        delegateAgreementGrant: async ({ parentGrantId, holderId, agreementId }, creds) => {
-            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
-            return client.delegateGrant(parentGrantId, {
-                holderId,
-                holderKind: 'agent',
-                // `write` is exactly what `canActUnderAgreement` tests. Deliberately not
-                // `admit`: that would let a coordinator widen its own crew.
-                kind: 'write',
-                scope: { kind: 'agreement', id: agreementId },
-                // from-start, not from-now: the contract predates the grant, so a
-                // from-now watermark would exclude the very row the grant is about.
-                temporal: 'from-start',
-            });
-        },
-    };
-}
-/**
- * Hand the coordinator a pass on one worker contract.
- *
- * Membership in work is a grant, which is what lets a coordinator create work
- * under a contract it is not a party to. Issuing that grant is the half that has
- * to happen here: without it the recipe fails at the coordinator's first
- * `task_create` with "Caller <coordinator> holds no grant on agreement <worker>,
- * so it cannot create work citing it."
- *
- * Reused before minted, because provisioning is re-run: a second call after an
- * agreement activates should not stack a second pass on a contract that already
- * has one.
- */
-async function grantCoordinatorAccess(args, deps) {
-    const { agreementId, coordinatorId, status, creds } = args;
-    // Participation grants are minted at ACTIVATION, so a contract still waiting
-    // on a signature has nothing to delegate from yet. Say so rather than
-    // reporting a failure the caller cannot act on.
-    if (status !== 'active') {
-        return {
-            status: 'deferred',
-            error: `${agreementId} is not active yet, so there is no participation grant to ` +
-                'delegate from — provision again once it activates',
-        };
-    }
-    try {
-        const alreadyIssued = await deps.listAgreementGrants({ agreementId, role: 'issuer' }, creds);
-        const existing = alreadyIssued.find((g) => g.holderId === coordinatorId);
-        if (existing?.grantId)
-            return { status: 'reused', grantId: existing.grantId };
-        const held = await deps.listAgreementGrants({ agreementId, role: 'holder' }, creds);
-        // Only a `write` or `admit` parent can beget the `write` child the act rule
-        // tests; a `read` participation grant cannot be widened by delegating it.
-        // `access` is optional on GrantView because some rails do not record it —
-        // context grants always do, so an absent value here is a malformed row and
-        // must not be treated as strong enough.
-        const parent = held.find((g) => g.access === 'write' || g.access === 'admit');
-        if (!parent?.grantId) {
-            return {
-                status: 'failed',
-                error: `no write-or-stronger grant on ${agreementId} to delegate from (found ` +
-                    `${held.length ? held.map((g) => g.access ?? 'unstated').join(', ') : 'none'}) — ` +
-                    'the initiator must be a party to the worker contract it is provisioning',
-            };
-        }
-        const result = await deps.delegateAgreementGrant({ parentGrantId: parent.grantId, holderId: coordinatorId, agreementId }, creds);
-        if (result.status === 'pending_approval') {
-            return { status: 'pending_approval', approvalAgreementId: result.agreementId };
-        }
-        return { status: 'granted', grantId: result.grant.grantId };
-    }
-    catch (err) {
-        return {
-            status: 'failed',
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-export async function provisionRelayWorkers(input, deps = defaultRelayProvisionDeps()) {
-    const { creds, hireAgreementId, coordinatorId, chatId, steps, inputArtifactIds } = input;
-    if (!steps.length)
-        throw new Error('steps must not be empty');
-    if (!coordinatorId?.trim()) {
-        throw new Error('coordinatorId is required: provisioning a worker for a coordinator means both ' +
-            'the contract and an agreement-scope grant to that coordinator on it, and ' +
-            'without the grant every branch of the run is refused');
-    }
-    const myAgreements = (await deps.getMyAgreements({}, creds));
-    let offersCache = null;
-    // The contracts first, then the passes. Two passes rather than one because a
-    // grant can only be delegated from a participation grant, which exists only
-    // once the contract is active — so the grant decision needs the settled
-    // status of the row, not the intent that created it.
-    const contracted = [];
-    const pendingApprovals = [];
-    for (const step of steps) {
-        const existing = findExistingWorkerDelegation(hireAgreementId, step.assigneeId, myAgreements);
-        if (existing?.agreementId) {
-            contracted.push({
-                stepId: step.stepId,
-                order: step.order,
-                agreementId: existing.agreementId,
-                assigneeId: step.assigneeId,
-                description: step.description,
-                provisionMethod: 'existing',
-                status: 'active',
-            });
-            continue;
-        }
-        if (step.offerAgreementId) {
-            const { agreement: claimed } = await deps.claimOpenAgreement(step.offerAgreementId, creds);
-            const agreementId = claimed.agreementId;
-            const status = isActiveAgreement(claimed)
-                ? 'active'
-                : 'pending_approval';
-            if (status === 'pending_approval')
-                pendingApprovals.push(agreementId);
-            contracted.push({
-                stepId: step.stepId,
-                order: step.order,
-                agreementId,
-                assigneeId: step.assigneeId,
-                description: step.description,
-                provisionMethod: 'claim',
-                status,
-            });
-            continue;
-        }
-        if (!offersCache) {
-            offersCache = await deps.pullOffers({ limit: 100 }, creds);
-        }
-        const openOffer = findOpenOfferForAgent(step.assigneeId, offersCache);
-        if (openOffer?.agreementId) {
-            const { agreement: claimed } = await deps.claimOpenAgreement(openOffer.agreementId, creds);
-            const agreementId = claimed.agreementId;
-            const status = isActiveAgreement(claimed)
-                ? 'active'
-                : 'pending_approval';
-            if (status === 'pending_approval')
-                pendingApprovals.push(agreementId);
-            contracted.push({
-                stepId: step.stepId,
-                order: step.order,
-                agreementId,
-                assigneeId: step.assigneeId,
-                description: step.description,
-                provisionMethod: 'claim',
-                status,
-            });
-            continue;
-        }
-        if (!chatId?.trim()) {
-            throw new Error(`No standing offer found for ${step.assigneeId} and chatId is required to propose a delegation under the hire`);
-        }
-        const delegated = await deps.delegateAgreement({
-            description: step.description,
-            executorId: step.assigneeId,
-            chatId: chatId.trim(),
-            parentAgreementId: hireAgreementId,
-            agreementDescription: `Relay step ${step.stepId}: ${step.description}`,
-            lifecycle: 'count-bound',
-            maxExecutions: 50,
-            price: 0,
-        }, creds);
-        const agreementId = delegated.agreementId;
-        const status = isActiveAgreement(delegated)
-            ? 'active'
-            : 'pending_approval';
-        if (status === 'pending_approval')
-            pendingApprovals.push(agreementId);
-        contracted.push({
-            stepId: step.stepId,
-            order: step.order,
-            agreementId,
-            assigneeId: step.assigneeId,
-            description: step.description,
-            provisionMethod: 'delegate',
-            status,
-        });
-    }
-    contracted.sort((a, b) => a.order - b.order);
-    // ── the second act of provisioning: the coordinator's passes ─────────────
-    const provisioned = [];
-    for (const step of contracted) {
-        const grant = await grantCoordinatorAccess({
-            agreementId: step.agreementId,
-            coordinatorId,
-            status: step.status,
-            creds,
-        }, deps);
-        if (grant.status === 'pending_approval' && grant.approvalAgreementId) {
-            pendingApprovals.push(grant.approvalAgreementId);
-        }
-        provisioned.push({ ...step, grant });
-    }
-    const payload = {
-        inputArtifactIds,
-        steps: provisioned.map(({ stepId, order, agreementId, assigneeId, description }) => ({
-            stepId,
-            order,
-            agreementId,
-            assigneeId,
-            description,
-        })),
-    };
-    /**
-     * Ready means BOTH acts are done for every step. A run whose contracts are all
-     * active but whose coordinator holds no passes looks provisioned and has every
-     * branch refused, so the grant has to count here or this flag goes on lying.
-     */
-    const readyForKickoff = pendingApprovals.length === 0 &&
-        provisioned.every((s) => s.status === 'active' &&
-            (s.grant.status === 'granted' || s.grant.status === 'reused'));
-    return {
-        payload,
-        steps: provisioned,
-        pendingApprovals,
-        readyForKickoff,
-    };
-}