@ziggs-ai/api-client 0.28.1 → 0.30.0

package/dist/capabilities/agreements.d.ts

@@ -1,4 +1,4 @@
-import type { ClaimedKind } from '../http/AgreementClient.js';
+import type { ClaimedKind, ClaimRoom } from '../http/AgreementClient.js';
 import type { Agreement } from '../types.js';
 import { type NextCallOutcome, type WorkContext } from './nextCall.js';
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
@@ -7,12 +7,13 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  * return `{agreement, kind}` while MCP returned `{status, kind, message,
  * agreement}` — same HTTP call, two answers.
  */
-export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv): {
+export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv, room?: ClaimRoom): {
     status: string;
     outcome: NextCallOutcome;
     kind: ClaimedKind;
     message: string;
     agreement: Agreement;
+    room?: ClaimRoom;
     workContext?: WorkContext;
 };
 /**

package/dist/capabilities/agreements.js

@@ -16,7 +16,28 @@ function claimedWhat(kind) {
  * return `{agreement, kind}` while MCP returned `{status, kind, message,
  * agreement}` — same HTTP call, two answers.
  */
-export function presentClaimResult(agreement, kind, env) {
+export function presentClaimResult(agreement, kind, env, room) {
+    const out = presentClaim(agreement, kind, env);
+    if (!room)
+        return out;
+    return { ...out, message: `${out.message} ${roomWords(room)}`, room };
+}
+/**
+ * The room the hire was made in, in words. "Ready" is said only
+ * when the agent is in; a failure says the hire and its charge stand and names
+ * the call that resumes admission.
+ */
+function roomWords(room) {
+    if (room.status === 'ready') {
+        return `The agent is in room ${room.chatId} now.`;
+    }
+    if (room.status === 'awaiting_approval') {
+        return `Once it is approved, the agent joins room ${room.chatId} with no further step; the room shows the proposal to the person who can answer it.`;
+    }
+    const retry = room.recovery ? ` Resume with ${room.recovery.method} ${room.recovery.path}.` : '';
+    return `The hire is active, but the agent is not in room ${room.chatId} yet${room.message ? ` (${room.message})` : ''}. Do not claim again.${retry}`;
+}
+function presentClaim(agreement, kind, env) {
     const workContext = workContextFromEnv(env);
     if (kind === 'link') {
         return {
@@ -68,8 +89,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 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.',
+        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. To hire an agent into a room, claim its listing with that room\'s chatId.',
+        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. To hire an agent into a room, claim its listing with that room\'s chatId.',
     },
     annotation: 'write',
     params: {
@@ -88,12 +109,16 @@ export const agreementClaimCapability = {
             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.',
         },
+        chatId: {
+            type: 'string',
+            description: 'The room this hire is for — only when claiming an agent\'s listing. When the hire activates the agent joins that exact room, with no invitation and no second approval; if it waits for a yes, the room shows it as a proposal. You must be in the room. The answer\'s room.status says where it stands.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}) });
-        return presentClaimResult(agreement, kind, env);
+        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}) });
+        return presentClaimResult(agreement, kind, env, room);
     },
 };
 export const AGREEMENT_CAPABILITIES = [agreementClaimCapability];

package/dist/capabilities/chat.js

@@ -54,8 +54,8 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Start or reuse a conversation',
     descriptions: {
-        sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. A new group is opened with people. With chatId, participantIds may also name agents: each joins through the same admission as the web app, so it must be reachable (your own, one of your company, published, or already engaged), and an agent you invite waits until the people in the room approve it in the app; the result lists each id as added, already-here or pending. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
-        mcp: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. A new group is opened with people. With chatId, participantIds may also name agents: each joins through the same admission as the web app, so it must be reachable (your own, one of your company, published, or already engaged), and an agent you invite waits until the people in the room approve it in the app; the result lists each id as added, already-here or pending. Your own missing seat is asked for with ziggs_access_request. Reach another person through their user id, not an unpublished agent of theirs. For missing access to a known room, use ziggs_access_request; opening another room does not recover its history. Opening does not send a message; ziggs_chat_send must name its intended receiverId to guarantee a target.',
+        sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
+        mcp: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with ziggs_access_request. Reach another person through their user id, not an unpublished agent of theirs. For missing access to a known room, use ziggs_access_request; opening another room does not recover its history. Opening does not send a message; ziggs_chat_send must name its intended receiverId to guarantee a target.',
     },
     annotation: 'write',
     params: {
@@ -63,7 +63,7 @@ export const openConversationCapability = {
             type: 'string',
             description: 'Known user or agent id from search, a directory, a chat, or an agreement. For a teammate or a linked person, their user id, not an agent of theirs. No existing chat is required; do not guess ids.',
         },
-        participantIds: { type: 'array', items: { type: 'string' }, description: '1–20 known ids. Without chatId: people, for a separate group. With chatId: people or agents to invite into that room (an agent waits for the room\'s people to approve). Use instead of participantId. Each invitation is authorized separately.' },
+        participantIds: { type: 'array', items: { type: 'string' }, description: '1–20 known ids. With or without chatId, people and agents; an agent without your approval authority waits for one person in the room to say yes. Use instead of participantId. Each invitation is authorized separately.' },
         chatId: { type: 'string', description: 'Existing room to invite participantIds into. Never creates another room. Omit creation options and agreementId.' },
         idempotencyKey: { type: 'string', description: 'Required for group creation: a unique key for this conversation, reused unchanged on retries. A different participant set needs a new key.' },
         name: { type: 'string', description: 'Name for a new group, 1–80 characters. Pair rooms and team channels take no name. A retry of the same idempotencyKey keeps the first name. Rename later is PATCH /chats/:chatId by someone who can admit people.' },
@@ -120,13 +120,17 @@ export const openConversationCapability = {
         // withheld it — worse than silence, because the agent cannot even tell
         // there is something to look up. A backend too old to report it keeps the
         // old both-cases wording, and `reused` is simply absent from the result.
+        // A new group that named agents reports each of them too.
+        const created = reused === false ? 'Created a new conversation with the named participants, so there is no history to catch up on.' : null;
         const outcomeNote = args.chatId
             ? inviteNote(invited)
-            : reused === true
-                ? 'Reused the conversation you already had with the named participants, so it may already hold history — read it before you speak.'
-                : reused === false
-                    ? 'Created a new conversation with the named participants, so there is no history to catch up on.'
-                    : 'Conversation is open (or reused).';
+            : created && invited?.length
+                ? `${created} ${inviteNote(invited)}`
+                : reused === true
+                    ? 'Reused the conversation you already had with the named participants, so it may already hold history — read it before you speak.'
+                    : reused === false
+                        ? 'Created a new conversation with the named participants, so there is no history to catch up on.'
+                        : 'Conversation is open (or reused).';
         return {
             chatId,
             actingAgentId: fullCreds(env).agentId,
@@ -149,7 +153,7 @@ function inviteNote(invited) {
     if (ids('already-here').length)
         parts.push(`Already in the room: ${ids('already-here').join(', ')}.`);
     if (ids('pending').length) {
-        parts.push(`Waiting for the people in the room to approve: ${ids('pending').join(', ')}. They see it in the app; the agent cannot read or write here until then, and asking again does not make a second request.`);
+        parts.push(`Proposed in the room, waiting for one person there to say yes: ${ids('pending').join(', ')}. The first answer decides; the agent cannot read or write here until then, and asking again does not make a second request.`);
     }
     return `${parts.join(' ')} Invited people read from now on.`;
 }

package/dist/capabilities/context.js

@@ -1,3 +1,4 @@
+import { presentResourceActions } from './resourceActions.js';
 import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
 import { ContextOpenClient } from '../http/ContextOpenClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
@@ -306,9 +307,16 @@ function presentOpenResult(result, env) {
     });
     return {
         ...result,
-        actions: result.access.continuation?.request ? [requestAccessAction(result.access.continuation.request, env)] : result.ref.kind === 'artifact' && result.outcome === 'unreadable' ? [requestAccessAction({ scopeKind: 'artifact', scopeId: result.ref.id, permission: 'read', durationHours: 24 }, env)] : resumeActions,
+        actions: result.actions
+            ? [...presentResourceActions(result.actions, env.surface),
+                ...resumeActions.map(a => ({ ...a, action: 'resume', state: 'not_evaluated' }))]
+            : result.access.continuation?.request
+                ? [requestAccessAction(result.access.continuation.request, env)]
+                : result.ref.kind === 'artifact' && result.outcome === 'unreadable'
+                    ? [requestAccessAction({ scopeKind: 'artifact', scopeId: result.ref.id, permission: 'read', durationHours: 24 }, env)]
+                    : resumeActions,
         actingAgentId: fullCreds(env).agentId,
-        ...(result.ref.kind === 'artifact' && result.outcome !== 'ok' ? {
+        ...(!result.actions && result.ref.kind === 'artifact' && result.outcome !== 'ok' ? {
             requestAccessHint: `If a source you already read supplied this artifact reference and its human owner, ${requestTool} scopeKind=artifact can ask that owner for temporary read access without a prior grant. It needs a conversation with the owner; ${chatTool} can open or reuse one, subject to authorization. Discover the request tool's schema before calling it. This response does not confirm existence or ownership. A request grants no access until the human owner approves.`,
         } : {}),
     };
@@ -318,8 +326,8 @@ export const openCapability = {
     names: { sdk: 'open', mcp: 'ziggs_open' },
     title: 'Open a returned resource',
     descriptions: {
-        sdk: 'Open an artifact, chat, task, or agreement you were given an id for. Pass exactly one of artifactId, chatId, taskId, agreementId. Do not pick a grant id or reconstruct type/via — the server resolves the read path and rechecks authorization every time. Read-only: this never requests access or records an approval. Reading is not reply, share, delegate, approve, or original-file download. Extraction pending/failed is not an empty document.',
-        mcp: 'Open an artifact, chat, task, or agreement from an ordinary returned id (inbox, find, task result). Pass exactly one of artifactId, chatId, taskId, agreementId. Do not call ziggs_grant_list first, do not pick a grant id, and do not reconstruct type/via — the server resolves the path and rechecks every call. A saved id is not authority. Read-only: never requests access or approves. Hidden and unknown look the same; a discoverable-but-unreadable row names an owner-decision, which this call does not execute. Text access is not a file download. Extraction pending/failed is not an empty document.',
+        sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document.',
+        mcp: 'Read a returned artifact, chat, task, or agreement: pass exactly one corresponding id. No preliminary grant lookup. The backend returns scoped actions, required inputs and recovery calls; this read executes none of them. Hidden and unknown look the same. Extraction pending/failed is not an empty document.',
     },
     annotation: 'read-only',
     params: {
@@ -341,8 +349,8 @@ export const accessExplainCapability = {
     names: { sdk: 'access_explain', mcp: 'ziggs_access_explain' },
     title: 'Explain access to a resource',
     descriptions: {
-        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Says whether you can read, and that reading does not imply reply, share, delegate, approve, or download. Does not return content and does not request or approve anything.',
-        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Names the owner-decision route when you cannot read a discoverable resource; this call never executes that request. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
+        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Returns scoped action states, required inputs and recovery calls. Does not return content and does not request or approve anything.',
+        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Returns scoped actions and recovery calls; this call never executes them. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
     },
     annotation: 'read-only',
     params: OPEN_ID_PARAMS,

package/dist/capabilities/index.d.ts

@@ -18,3 +18,4 @@ export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapabilit
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, type SendPresentation, } from './chat.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
+export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/index.js

@@ -18,3 +18,4 @@ export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapabilit
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
+export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/nextCall.d.ts

@@ -4,7 +4,9 @@ import type { CapabilityDefinition, CapabilityEnv } from './types.js';
  * One next step: the tool the calling surface registers, any args already
  * known, and why.
  *
- * Ready means a caller can run it verbatim. Incomplete means a required
+ * Ready means the call has complete arguments and no declared hold; it is
+ * not an authorization decision. The server checks permission on execution.
+ * Incomplete means a required
  * argument is missing or an address field is not an address — the suggestion
  * still names the tool, and `missing` says what has to be filled first.
  *
@@ -19,7 +21,7 @@ export interface NextCall {
     args?: Record<string, unknown>;
     /** One clause: what running this achieves, or what is still missing. */
     why: string;
-    /** True only when every required argument is present and addressable. */
+    /** Arguments are complete and no hold is declared; does not prove authority. */
     ready: boolean;
     /** Required argument names that are absent or not an address. */
     missing?: readonly string[];

package/dist/capabilities/resourceActions.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceAction } from '../http/ContextOpenClient.js';
+/** Bind canonical tool names without changing the backend's decision or scope. */
+export declare function presentResourceActions(actions: ResourceAction[], surface: 'sdk' | 'mcp'): ResourceAction[];

package/dist/capabilities/resourceActions.js

@@ -0,0 +1,9 @@
+/** Bind canonical tool names without changing the backend's decision or scope. */
+export function presentResourceActions(actions, surface) {
+    const toolName = (name) => surface === 'mcp' && !name.startsWith('ziggs_') ? `ziggs_${name}` : name;
+    const call = (value) => ({ ...value, tool: toolName(value.tool) });
+    return actions.map(action => ({ ...action,
+        ...(action.tool ? { tool: toolName(action.tool) } : {}),
+        ...(action.recovery ? { recovery: call(action.recovery) } : {}),
+    }));
+}

package/dist/http/AgreementClient.d.ts

@@ -190,8 +190,8 @@ export declare function resolveMyPendingApprovalPartyId(agreement: Agreement, op
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
  *
- * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
- * principal when approving as human, delegate agent id when impersonating.
+ * Use the partyId from the server's approvalAction. Agents need covering
+ * approval authority even for their own slot; the server rechecks it on PUT.
  * Canonical for hire, service, link, and request proposals.
  */
 export declare function approveAgreementAsParty(agreementId: string, partyId: string, status: 'approved' | 'rejected', creds: Creds): Promise<Agreement>;
@@ -318,11 +318,31 @@ export interface ClaimOptions {
      * verifies the claim against the acting agent and never guesses one.
      */
     mandateAgreementId?: string;
+    /**
+     * The room a hire of a listing is made in. On activation its
+     * agent joins that room; the claimer must take part in it.
+     */
+    chatId?: string;
+}
+/**
+ * Where a hire made in a room stands on getting its agent in.
+ * `ready` only once the agent is in; `admission_failed` names the action that
+ * resumes it without hiring or charging again.
+ */
+export interface ClaimRoom {
+    chatId: string;
+    status: 'awaiting_approval' | 'ready' | 'admission_failed';
+    message?: string;
+    recovery?: {
+        method: string;
+        path: string;
+    };
 }
 export declare function claimAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     ok: boolean;
     agreement: Agreement;
     kind?: ClaimedKind;
+    room?: ClaimRoom;
 }>;
 /**
  * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
@@ -367,6 +387,7 @@ export declare class AgreementClient {
         ok: boolean;
         agreement: Agreement;
         kind?: ClaimedKind;
+        room?: ClaimRoom;
     }>;
     linkToChat(id: string, chatId: string, linkType?: ChatLinkType): Promise<unknown>;
     listChats(id: string): Promise<unknown[]>;

package/dist/http/AgreementClient.js

@@ -53,6 +53,7 @@ export function linkSummary(a) {
         // chat with. Dropping it here is what that looked like: the server sent the
         // peer and the allow-list ate it before any caller saw it.
         ...(a.peer ? { peer: a.peer } : {}),
+        ...(a.approvalAction ? { approvalAction: a.approvalAction } : {}),
         ...(a.description ? { description: a.description } : {}),
         // Seat bookkeeping on an open invite — link state, not commerce.
         ...(a.linkInvite ? { linkInvite: a.linkInvite } : {}),
@@ -222,7 +223,11 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     if (!agreement) {
         throw new Error(`Agreement ${agreementId} not found`);
     }
-    const partyId = resolveMyPendingApprovalPartyId(agreement, {
+    const approval = agreement.approvalAction;
+    if (approval && (approval.state !== 'available' || !approval.partyId)) {
+        throw new Error(`${approval.explanation}${opts.appUrl ? ` Review: ${opts.appUrl}` : ''}`);
+    }
+    const partyId = approval?.partyId ?? resolveMyPendingApprovalPartyId(agreement, {
         ownerUserId: opts.ownerUserId,
         agentId: creds.agentId,
     });
@@ -288,8 +293,8 @@ export function resolveMyPendingApprovalPartyId(agreement, opts) {
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
  *
- * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
- * principal when approving as human, delegate agent id when impersonating.
+ * Use the partyId from the server's approvalAction. Agents need covering
+ * approval authority even for their own slot; the server rechecks it on PUT.
  * Canonical for hire, service, link, and request proposals.
  */
 export async function approveAgreementAsParty(agreementId, partyId, status, creds) {
@@ -548,7 +553,7 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}) }),
+        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.chatId ? { chatId: opts.chatId } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

package/dist/http/ContextOpenClient.d.ts

@@ -14,16 +14,25 @@ export interface ContextOpenBody {
     after?: string;
     limit?: number;
 }
-export interface ContextOpenAbilities {
-    read: boolean;
-    reply: boolean;
-    share: boolean;
-    delegate: boolean;
-    approve: boolean;
-    download: boolean;
+/** Backend-evaluated action, scoped to a resource. Never a permission token. */
+export interface ResourceActionCall {
+    tool: string;
+    args: Record<string, unknown>;
+    required?: string[];
+}
+export interface ResourceAction extends Partial<ResourceActionCall> {
+    action: string;
+    state: 'available' | 'needs_decision' | 'unavailable' | 'not_evaluated';
+    reasonCode?: string;
+    reason?: unknown;
+    scope?: {
+        kind: string;
+        id: string;
+        agreementId?: string;
+    };
+    recovery?: ResourceActionCall;
 }
 export interface ContextOpenAccess {
-    abilities: ContextOpenAbilities;
     summary: string;
     document?: {
         empty: boolean;
@@ -42,6 +51,8 @@ export interface ContextOpenAccess {
     };
 }
 export interface ContextOpenResult {
+    /** Optional for servers predating resource action projections. */
+    actions?: ResourceAction[];
     outcome: ContextOpenOutcome;
     ref: ContextOpenRef;
     access: ContextOpenAccess;

package/dist/http/ContextReadClient.d.ts

@@ -57,6 +57,8 @@ export interface ContextSnapshotParticipant {
     [key: string]: unknown;
 }
 export interface ContextSnapshotResult {
+    /** Server-resolved orientation; writes recheck authority. */
+    workBrief?: Record<string, unknown>;
     work?: Record<string, unknown>;
     history: unknown[];
     agreements: unknown[];

package/dist/http/agreementFlows.d.ts

@@ -1,4 +1,4 @@
-import { type ClaimedKind, type ClaimOptions, type ProposeTerms } from './AgreementClient.js';
+import { type ClaimedKind, type ClaimOptions, type ClaimRoom, type ProposeTerms } from './AgreementClient.js';
 import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 /**
  * one propose grammar. Direct, broadcast (request and standing
@@ -38,4 +38,5 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
 export declare function claimOpenAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     agreement: Agreement;
     kind: ClaimedKind;
+    room?: ClaimRoom;
 }>;

package/dist/http/agreementFlows.js

@@ -75,8 +75,8 @@ export async function proposeUnified(input, creds) {
 export async function claimOpenAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
         throw new Error('agreementId is required');
-    const { agreement, kind } = await claimAgreement(agreementId, creds, opts);
+    const { agreement, kind, room } = 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' };
+    return { agreement, kind: kind ?? 'request', ...(room ? { room } : {}) };
 }

package/dist/http/index.d.ts

@@ -10,7 +10,7 @@ export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, List
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextOpenClient, CONTEXT_OPEN_KINDS } from './ContextOpenClient.js';
-export type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBody, ContextOpenAbilities, ContextOpenAccess, ContextOpenResult, ContextExplainResult, } from './ContextOpenClient.js';
+export type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBody, ResourceAction, ResourceActionCall, ContextOpenAccess, ContextOpenResult, ContextExplainResult, } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, }
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.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, InboxPeek, InboxReadOptions, } from './types.js';
-export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, ClaimRoom, } from './http/AgreementClient.js';
 export { decisionWords } from './decisionWords.js';
 export type { DecisionOutcome, DecisionWords, DecisionWordsInput, } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';

package/dist/types.d.ts

@@ -176,6 +176,11 @@ export interface AgreementApprovalEntry {
     heldReason?: string | null;
 }
 export interface Agreement {
+    approvalAction?: {
+        state: 'available' | 'needs_decision' | 'unavailable';
+        partyId?: string;
+        explanation: string;
+    };
     agreementId: string;
     parentAgreementId?: string | null;
     rootAgreementId?: string | null;

package/package.json

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