@ziggs-ai/api-client 0.37.16 → 0.37.17

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.37.17
+
+- Clarify the shared hiring instructions: a mandate governs the work; agent-initiated hires need a covering grant or approval on the existing agreement.
+
+- Resume an existing hire into its room with `chat_open({chatId, agreementId})`, using the same backend admission operation as the room UI. Retries do not hire or charge again.
+- Normalize current `ref` and cached typed resource identifiers in one client path for `open` and `access_explain`.
+- Share structured refusal formatting across MCP and agent runtimes, preserving recovery calls, eligible approvers, choices, and wrapped API errors. Pending invitations identify their approvers and approval room.
+- Preserve every server error code and empty approver list; stop guessing resource-access requests from the word "scope" in a 403 message. Human-only refusals direct the caller to the account owner.
+
 ## 0.37.16
 
 - `messages` can ask for the newest page. A forward delta still needs a timestamp.

package/dist/capabilities/agreementVerbs.js

@@ -85,22 +85,10 @@ function termsFrom(args) {
 function engagementKindFrom(args) {
     return args['engagementKind'] ?? 'service';
 }
-/**
- * The job an agent declares it is acting inside.
- *
- * The consent gate excuses a formation that sits inside a job a human already
- * approved, and it verifies the claim against the acting agent. What did not
- * exist was a way to MAKE the claim: `parentAgreementId` rode only on internal
- * service calls, so every agreement an agent formed arrived at the gate as an
- * outsider and waited on a human — including the ordinary case of buying the
- * help the job it was hired for needs.
- *
- * Declared by the caller, never guessed by the server. The SDK fills it in from
- * the task it is executing, so an agent doing assigned work pays nothing for it.
- */
+/** The declared job governs the work; hiring consent uses grants or agreement approval. */
 const MANDATE_PARAM = {
     type: 'string',
-    description: "The active agreement whose work this is part of — the job you are doing. It becomes this engagement's parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job. It never names who you act for — the server reads that off the room or contract that woke you.",
+    description: "The active agreement whose work this is part of — the job you are doing. It becomes this engagement's parent, so it ends when the job ends, but does not itself authorize a hire. Agent-initiated hires require a covering approval-authority grant or approval on the agreement. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job. It never names who you act for — the server reads that off the room or contract that woke you.",
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {

package/dist/capabilities/agreements.js

@@ -1,3 +1,4 @@
+import { presentResourceCall } from './resourceActions.js';
 import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
@@ -20,7 +21,11 @@ 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 };
+    const recovery = room.recovery;
+    const presented = recovery?.tool
+        ? { ...room, recovery: presentResourceCall({ ...recovery, tool: recovery.tool, args: recovery.args ?? {} }, env.surface) }
+        : room;
+    return { ...out, message: `${out.message} ${roomWords(presented)}`, room: presented };
 }
 /**
  * The room the hire was made in, in words. "Ready" is said only
@@ -32,10 +37,15 @@ function roomWords(room) {
         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.`;
+        return room.chatId
+            ? `Once approved, the agent joins room ${room.chatId}; the room shows who can answer.`
+            : 'The hire is waiting for approval; its conversation opens after approval.';
     }
-    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}`;
+    const recovery = room.recovery;
+    const retry = recovery?.tool
+        ? ` Resume with ${recovery.tool} using ${JSON.stringify(recovery.args)}.`
+        : recovery ? ` Resume with ${recovery.method} ${recovery.path}.` : '';
+    return `${room.message ?? 'The hire conversation is not ready.'} Do not claim again.${retry}`;
 }
 function presentClaim(agreement, kind, env) {
     const workContext = workContextFromEnv(env);
@@ -83,7 +93,7 @@ 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. To hire an agent into a room, claim its listing with that room\'s chatId.',
+        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-initiated hire needs a covering approval-authority grant or the existing agreement waits for the responsible principal to approve. Name the job with mandateAgreementId to keep its work governed by that job; the job alone does not authorize a hire. 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.',
     },
     annotation: 'destructive',
     params: {
@@ -92,15 +102,11 @@ export const agreementClaimCapability = {
             required: true,
             description: 'The open agreement to claim (request / offer / link invite id)',
         },
-        // The job this claim is part of. A claim is the DEFAULT way to engage, so
-        // without this the ordinary case — an agent claiming the help the job it is
-        // doing needs — waited on a human every time. It authorizes; it does not
-        // re-parent: the row belongs to whoever posted it, and a claimer cannot move
-        // somebody else's agreement into its own tree.
+        // Declare the governing work separately from consent to hire.
         parentAgreementId: { type: 'string', description: 'Place the new service-listing claim under this governing relationship or work agreement. Requires separate consent to the posted terms.' },
         mandateAgreementId: {
             type: 'string',
-            description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.',
+            description: 'The active agreement whose work this claim is part of — the job you are doing. The server checks you are a party to the job. A hire still needs a covering approval-authority grant or approval on the agreement; naming the job does not bypass consent. Leave it out when the claim belongs to no job.',
         },
         chatId: {
             type: 'string',

package/dist/capabilities/chat.js

@@ -61,9 +61,9 @@ export function presentSendResult(result, env) {
 export const openConversationCapability = {
     key: 'chat_open',
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
-    title: 'Start or reuse a conversation',
+    title: 'Open, invite to, or resume a conversation',
     descriptions: {
-        sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses your person’s conversation with one person or agent, the same room each of their agents finds; newChat opens a separate subject, which can take a name. 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"].',
+        sdk: 'Open a conversation or explicitly invite people to a room. To resume admission of an existing hire, pass only chatId and agreementId; this uses the same recovery as the room UI and never hires or charges again. participantId opens/reuses your person’s conversation with one person or agent, the same room each of their agents finds; newChat opens a separate subject, which can take a name. 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"].',
     },
     annotation: 'write',
     params: {
@@ -72,7 +72,7 @@ export const openConversationCapability = {
             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. 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.' },
+        chatId: { type: 'string', description: 'Existing room. With participantIds: invite into it. With agreementId only: resume the approved hire admission without another hire or charge.' },
         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 or a newChat room, 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.' },
         createIfMissing: { type: 'boolean', description: 'Set false to reuse only an existing room with this participant. A missing room is refused without creating a replacement.' },
@@ -86,12 +86,22 @@ export const openConversationCapability = {
         },
         agreementId: {
             type: 'string',
-            description: 'The hire this open is the working room for. On a store-claim kickoff, pass the ' +
+            description: 'With chatId: resume that existing hire’s room admission. Otherwise, the hire this open is the working room for. On a store-claim kickoff, pass the ' +
                 'claimed agreement id so the payer is stamped from-start in that room.',
         },
     },
     needsAgentId: true,
     handler: async (args, env) => {
+        if (args.chatId && args.agreementId) {
+            const result = await openConversation(args, fullCreds(env));
+            return {
+                ...result,
+                appUrl: chatAppUrl(webAppOrigin(env), result.chatId),
+                message: result.status === 'ready'
+                    ? 'The hired agent is admitted under this agreement. No new hire or charge was made.'
+                    : `Admission is still incomplete${result.reason ? `: ${result.reason}` : ''}. Retry this same call; do not claim again.`,
+            };
+        }
         if (!args.participantId && !Array.isArray(args.participantIds)) {
             throw new Error('participantId is required, or use participantIds to invite people');
         }

package/dist/capabilities/context.js

@@ -1,5 +1,4 @@
 import { isContextAccessRequest } from '../shared/contextAccessRequest.js';
-import { looksLikeHandle, parseRef } from '../handles.js';
 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';
@@ -259,29 +258,15 @@ export const contextDelegateCapability = {
 const OPEN_REF_PARAMS = {
     ref: {
         type: 'string',
-        required: true,
         description: 'What to open: a handle such as T7K2QXD (T task, A agreement, C chat, F artifact) in any case, a Ziggs web URL holding one, or an id from a prior response.',
     },
+    // Cached connector schemas still send these. Both surfaces normalize them
+    // here; the server remains the only authority on the resource and access.
+    ...Object.fromEntries(['artifactId', 'chatId', 'taskId', 'agreementId'].map(key => [key, {
+            type: 'string',
+            description: 'Use instead of ref; exactly one reference.',
+        }])),
 };
-function openBodyFromArgs(args) {
-    // A mistyped handle is refused here, before any call: its check letter
-    // fails. Any other id goes to the server, which knows older shapes.
-    const raw = typeof args.ref === 'string' ? args.ref.trim() : '';
-    const invalid = (message) => Object.assign(new Error(message), { code: 'INVALID_INPUT' });
-    if (!raw)
-        throw invalid('ref is required: a handle such as T7K2QXD, a Ziggs URL, or an id from a prior response');
-    const ref = parseRef(raw);
-    if (!ref && looksLikeHandle(raw))
-        throw invalid(`${raw} is not a handle: its check letter does not match. Check it for a typo`);
-    const body = { ref: ref?.id ?? raw };
-    if (typeof args['cursor'] === 'string')
-        body.cursor = args['cursor'];
-    if (typeof args['after'] === 'string')
-        body.after = args['after'];
-    if (typeof args['limit'] === 'number')
-        body.limit = args['limit'];
-    return body;
-}
 function presentOpenResult(result, env) {
     // Resource-routed OAuth calls let the backend select the assistant. Their
     // local credentials have no agent id, so only the response can name it.
@@ -364,7 +349,7 @@ export const openCapability = {
     handler: async (args, env) => {
         const creds = fullCreds(env);
         const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
-        return presentOpenResult(await client.open(openBodyFromArgs(args)), env);
+        return presentOpenResult(await client.open(args), env);
     },
 };
 export const accessExplainCapability = {
@@ -380,7 +365,7 @@ export const accessExplainCapability = {
     handler: async (args, env) => {
         const creds = fullCreds(env);
         const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
-        const result = await client.explain(openBodyFromArgs(args));
+        const result = await client.explain(args);
         return presentOpenResult(result, env);
     },
 };
@@ -418,7 +403,7 @@ export const accessRequestCapability = {
     title: 'Request access for yourself or named readers',
     annotation: 'destructive', needsAgentId: true,
     descriptions: {
-        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by id or the participant reference this room shows you); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. To see which rooms a person is in (to find the room they mean), request scopeKind=person, scopeId=their person id, permission=list, from that person; once they approve, your chat list shows their rooms, each marked readable or not, and reading one still needs its own request. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Choose recipientId when several approvers are offered; with one, it is selected automatically: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by id or the participant reference this room shows you); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. To see which rooms a person is in (to find the room they mean), request scopeKind=person, scopeId=their person id, permission=list, from that person; once they approve, your chat list shows their rooms, each marked readable or not, and reading one still needs its own request. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
     },
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task', 'person'] },
@@ -432,7 +417,7 @@ export const accessRequestCapability = {
         // Not required here: the server requires it, and a request without it
         // comes back refused with the people this agent may ask. Required in the
         // schema, a host refused the call before that list could arrive.
-        recipientId: { type: 'string', description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator). Without it, the refusal lists who you can ask.' },
+        recipientId: { type: 'string', description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator). Omit when only one approver is available; otherwise the response lists choices.' },
         holders: {
             type: 'array',
             description: 'Artifact only, read only: up to 20 readers, each { kind: "agent" | "user" | "org", id }. Leave yourself out to arrange it for others. Omit to ask for yourself.',
@@ -448,7 +433,7 @@ export const accessRequestCapability = {
         idempotencyKey: { type: 'string', description: 'Reuse for the same logical request' },
     },
     handler: async (args, env) => {
-        // recipientId is left to the server: it refuses a request without one
+        // recipientId is resolved by the server: it picks the sole eligible recipient
         // and lists who this agent may ask, which nothing on this side knows.
         for (const key of ['scopeKind', 'reason']) {
             if (typeof args[key] !== 'string' || !String(args[key]).trim())

package/dist/capabilities/resourceActions.d.ts

@@ -1,3 +1,4 @@
-import type { ResourceAction } from '../http/ContextOpenClient.js';
+import type { ResourceAction, ResourceActionCall } from '../http/ContextOpenClient.js';
+export declare function presentResourceCall<T extends ResourceActionCall>(value: T, surface: 'sdk' | 'mcp'): T;
 /** 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

@@ -1,9 +1,11 @@
+export function presentResourceCall(value, surface) {
+    const name = value.tool.replace(/^ziggs_/, '');
+    return { ...value, tool: surface === 'mcp' ? `ziggs_${name}` : name };
+}
 /** 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) } : {}),
+        ...(action.tool ? { tool: presentResourceCall({ tool: action.tool, args: action.args ?? {} }, surface).tool } : {}),
+        ...(action.recovery ? { recovery: presentResourceCall(action.recovery, surface) } : {}),
     }));
 }

package/dist/http/AgreementClient.d.ts

@@ -351,12 +351,14 @@ export interface ClaimOptions {
  * resumes it without hiring or charging again.
  */
 export interface ClaimRoom {
-    chatId: string;
-    status: 'awaiting_approval' | 'ready' | 'admission_failed';
+    chatId?: string;
+    status: 'awaiting_approval' | 'ready' | 'admission_failed' | 'preparation_failed' | 'unavailable';
     message?: string;
     recovery?: {
         method: string;
         path: string;
+        tool?: string;
+        args?: Record<string, unknown>;
     };
 }
 export declare function claimAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{

package/dist/http/ChatClient.d.ts

@@ -21,6 +21,14 @@ export interface ChatOpenInvite {
     /** pending: an agent's joining waits for the people in the room to approve it. */
     status: 'added' | 'already-here' | 'pending';
     admissionId?: string;
+    approvers?: Array<{
+        id: string;
+        name: string | null;
+    }>;
+    approveIn?: {
+        kind: 'chat';
+        chatId: string;
+    };
 }
 export interface OpenConversationInput {
     participantId?: string;
@@ -33,16 +41,20 @@ export interface OpenConversationInput {
     agreementId?: string;
     createIfMissing?: boolean;
 }
-export declare function openConversation(participant: string | OpenConversationInput, creds: Creds, { newChat, agreementId, createIfMissing }?: {
-    newChat?: boolean;
-    agreementId?: string;
-    createIfMissing?: boolean;
-}): Promise<{
+export interface OpenConversationResult {
     chatId: string;
     reused?: boolean;
     invited?: ChatOpenInvite[];
     name?: string;
-}>;
+    agreementId?: string;
+    status?: 'ready' | 'admission_failed';
+    reason?: string;
+}
+export declare function openConversation(participant: string | OpenConversationInput, creds: Creds, { newChat, agreementId, createIfMissing }?: {
+    newChat?: boolean;
+    agreementId?: string;
+    createIfMissing?: boolean;
+}): Promise<OpenConversationResult>;
 export interface SendChatMessageInput {
     /**
      * Chat to send in. Required unless `to` names a person you already
@@ -168,12 +180,7 @@ export declare class ChatClient {
         newChat?: boolean;
         agreementId?: string;
         createIfMissing?: boolean;
-    }): Promise<{
-        chatId: string;
-        reused?: boolean;
-        invited?: ChatOpenInvite[];
-        name?: string;
-    }>;
+    }): Promise<OpenConversationResult>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;
     listMine(): Promise<ChatReadDto[]>;

package/dist/http/ChatClient.js

@@ -15,16 +15,23 @@ export async function openConversation(participant, creds, { newChat = false, ag
     const input = typeof participant === 'string'
         ? { participantId: participant, ...(newChat ? { newChat } : {}), ...(agreementId ? { agreementId } : {}), ...(createIfMissing !== undefined ? { createIfMissing } : {}) }
         : participant;
-    if (!input || (!input.participantId && !input.participantIds?.length)) {
+    const resumeHire = !!input?.chatId && !!input.agreementId;
+    if (resumeHire && (input.participantId || input.participantIds || input.newChat !== undefined || input.name !== undefined || input.idempotencyKey !== undefined || input.createIfMissing !== undefined)) {
+        throw new Error('To resume hire admission, pass only chatId and agreementId');
+    }
+    if (!input || (!resumeHire && !input.participantId && !input.participantIds?.length)) {
         throw new Error('participantId is required, or use participantIds to invite people');
     }
     assertCreds(creds, 'open conversation');
-    const res = await fetch(`${getBackendUrl()}/chats`, {
+    const route = resumeHire
+        ? `/chats/${encodeURIComponent(input.chatId)}/hires/${encodeURIComponent(input.agreementId)}/admission`
+        : '/chats';
+    const res = await fetch(`${getBackendUrl()}${route}`, {
         method: 'POST',
         headers: buildHeaders(creds),
         // Only sent when asked for: an older backend ignores the field, so a
         // caller that never wants a separate room behaves identically either way.
-        body: JSON.stringify(input),
+        body: JSON.stringify(resumeHire ? {} : input),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -38,6 +45,9 @@ export async function openConversation(participant, creds, { newChat = false, ag
     // send it. A backend from before this field cannot be assumed to have created
     // the room — defaulting to false would report a reused conversation as fresh,
     // which is worse than saying nothing.
+    if (resumeHire && (data.chatId !== input.chatId || data.agreementId !== input.agreementId || !['ready', 'admission_failed'].includes(String(data.status)))) {
+        throw new Error('Invalid hire-admission response: expected the selected chat, hire and admission status');
+    }
     const reused = data['reused'];
     const name = data['name'];
     const invited = Array.isArray(data['invited'])
@@ -45,6 +55,11 @@ export async function openConversation(participant, creds, { newChat = false, ag
         : undefined;
     return {
         chatId: data['chatId'],
+        ...(resumeHire ? {
+            agreementId: input.agreementId,
+            status: data.status,
+            ...(typeof data.reason === 'string' ? { reason: data.reason } : {}),
+        } : {}),
         ...(typeof reused === 'boolean' ? { reused } : {}),
         ...(typeof name === 'string' && name ? { name } : {}),
         ...(invited ? { invited } : {}),

package/dist/http/ContextOpenClient.d.ts

@@ -21,6 +21,12 @@ export interface ResourceActionCall {
     tool: string;
     args: Record<string, unknown>;
     required?: string[];
+    unavailableReason?: string;
+    approvers?: Array<{
+        id: string;
+        name: string | null;
+        role: string;
+    }>;
 }
 export interface ResourceAction extends Partial<ResourceActionCall> {
     action: string;
@@ -90,3 +96,4 @@ export declare class ContextOpenClient {
     explain(body: ContextOpenBody): Promise<ContextExplainResult>;
     private post;
 }
+export declare function normalizeContextOpenBody(args: Record<string, unknown>): ContextOpenBody;

package/dist/http/ContextOpenClient.js

@@ -1,3 +1,4 @@
+import { looksLikeHandle, parseRef } from '../handles.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
@@ -31,19 +32,14 @@ export class ContextOpenClient {
         return this.post('/context/access/explain', body);
     }
     async post(path, body) {
-        const filled = ['ref', 'artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
-        if (filled.length !== 1) {
-            // A caller's input mistake, named in the caller's words: the shared
-            // INVALID_INPUT code, and no internal class name in the sentence.
-            throw Object.assign(new Error('Pass ref (a handle such as T7K2QXD, a Ziggs URL, or an id), or exactly one of artifactId, chatId, taskId, agreementId.'), { code: 'INVALID_INPUT' });
-        }
+        const normalized = normalizeContextOpenBody({ ...body });
         const url = `${this.baseUrl || getBackendUrl()}${path}`;
         const res = await fetch(url, {
             method: 'POST',
             headers: {
                 ...buildOperatorHeaders(this.operatorKey, this.agentId, { 'Content-Type': 'application/json' }, this.laneId),
             },
-            body: JSON.stringify(body),
+            body: JSON.stringify(normalized),
         });
         const text = await res.text().catch(() => '');
         if (!res.ok) {
@@ -52,3 +48,26 @@ export class ContextOpenClient {
         return JSON.parse(text);
     }
 }
+export function normalizeContextOpenBody(args) {
+    // A mistyped handle is refused here, before any call: its check letter
+    // fails. Any other id goes to the server, which knows older shapes.
+    const invalid = (message) => Object.assign(new Error(message), { code: 'INVALID_INPUT' });
+    const keys = ['ref', 'artifactId', 'chatId', 'taskId', 'agreementId'].filter(key => args[key] !== undefined);
+    if (keys.length !== 1)
+        throw invalid('Pass exactly one resource reference: ref, artifactId, chatId, taskId, or agreementId');
+    const key = keys[0];
+    const raw = typeof args[key] === 'string' ? args[key].trim() : '';
+    if (!raw)
+        throw invalid(`${key} must be a non-empty resource reference`);
+    const ref = parseRef(raw);
+    if (!ref && looksLikeHandle(raw))
+        throw invalid(`${raw} is not a handle: its check letter does not match. Check it for a typo`);
+    const body = { [key]: ref?.id ?? raw };
+    if (typeof args['cursor'] === 'string')
+        body.cursor = args['cursor'];
+    if (typeof args['after'] === 'string')
+        body.after = args['after'];
+    if (typeof args['limit'] === 'number')
+        body.limit = args['limit'];
+    return body;
+}

package/dist/index.d.ts

@@ -33,3 +33,4 @@ export { isContextAccessRequest } from './shared/contextAccessRequest.js';
 export { AssistantConnectionClient, type AssistantWorkspace, } from './http/AssistantConnectionClient.js';
 export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef, type HandleKind } from './handles.js';
+export { describeOperationError, type OperationError } from './shared/operationError.js';

package/dist/index.js

@@ -31,3 +31,4 @@ export { AssistantConnectionClient, } from './http/AssistantConnectionClient.js'
 export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
 // Short handles: T…, A…, C…, F… (task, agreement, chat, artifact).
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef } from './handles.js';
+export { describeOperationError } from './shared/operationError.js';

package/dist/shared/operationError.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One refusal shape for MCP, SDK tools, and agent runtimes.
+ *
+ * classify from the thrown {@link ApiError} fields (`status`,
+ * `code`, `body` / `message`). No client-prefix strip, no HTTP-status regex,
+ * no re-parsing a JSON body that was concatenated into the message string.
+ */
+export interface OperationError {
+    code: string;
+    message: string;
+    hint?: string;
+    /**
+     * What the caller may pick from, when the refusal is a choice: the
+     * agreements of WORK_SELECTION_REQUIRED, the workspaces of
+     * WORKSPACE_SELECTION_REQUIRED. Carried through verbatim so an assistant can
+     * ask its human instead of re-reading the message.
+     */
+    choices?: unknown[];
+    /**
+     * The call that is the next step, when the server sent one: the access
+     * request of WORK_ACCESS_REQUIRED, ready to send. Carried through verbatim,
+     * the same shape an open's action recovery has.
+     */
+    recovery?: Record<string, unknown>;
+    /** hidden | unreadable, the same outcome open and access_explain give. */
+    outcome?: string;
+    /** The resource the outcome is about. */
+    ref?: {
+        kind: string;
+        id: string;
+    };
+    /** For an unreadable resource: the request to make, as open lists it. */
+    actions?: unknown[];
+}
+/**
+ * Classify a thrown client error (or a plain string this layer raised) into a
+ * stable shape on either tool surface.
+ */
+export declare function describeOperationError(input: unknown, surface?: 'sdk' | 'mcp'): OperationError;

package/dist/shared/operationError.js

@@ -0,0 +1,165 @@
+import { isCoverageRefusal } from './apiError.js';
+import { presentResourceCall } from '../capabilities/resourceActions.js';
+/**
+ * The shared refusal vocabulary every read tool answers in (hidden,
+ * unreadable, invalid input), so an assistant can branch on the code instead
+ * of parsing each tool's sentence.
+ */
+const SHARED_REFUSALS = new Set(['RESOURCE_HIDDEN', 'RESOURCE_UNREADABLE', 'INVALID_INPUT']);
+const SCOPE_DENIED_HINT = 'For missing access to a returned artifact, chat, agreement, or task, use ' +
+    'ziggs_access_request with that original resource id and your purpose. It creates ' +
+    'a pending access approval agreement; it grants no access. After approval, ' +
+    'ziggs_open the same resource using the same agent identity. For earlier chat ' +
+    'messages request temporal=from-start; replying also requires permission=reply. ' +
+    'Do not issue yourself a grant. A new room does not show this room\'s history.';
+// a human-authority denial is not "try again with more scope": no
+// retry by this caller can ever pass it, because the guard refuses on being an
+// agent at all, before it looks at what was asked. Without a next action the
+// only strategy left is repetition, which is what agents did.
+const HUMAN_AUTHORITY_HINT = 'Ask the account owner to perform this action in their signed-in session. ' +
+    'Requesting resource access cannot authorize a human-only operation; retrying as an agent will not change that.';
+/**
+ * What covers a conversation, refused. These arrive as 429 or 403,
+ * and a 429 read as "rate limited" tells an agent to wait and retry, which can
+ * never help: the writer has to hire the agent, or their person has to set up
+ * the agreement. The backend's own code and sentence are the answer.
+ */
+const COVERAGE_HINT = 'Retry only after the condition in this refusal changes. Use the returned recovery call when present. ' +
+    'For missing resource permission, ziggs_access_request asks your customer or operator and returns who can approve; ' +
+    'funding, ended agreements, and task-only terms require the responsible party to change those terms.';
+function codeForStatus(status) {
+    if (status === 401)
+        return 'NOT_AUTHENTICATED';
+    if (status === 403)
+        return 'NOT_AUTHORIZED';
+    if (status === 404)
+        return 'NOT_FOUND';
+    if (status === 409)
+        return 'CONFLICT';
+    if (status === 429)
+        return 'RATE_LIMITED';
+    if (status >= 500)
+        return 'UPSTREAM_ERROR';
+    if (status >= 400)
+        return 'BAD_REQUEST';
+    return 'TOOL_ERROR';
+}
+/**
+ * An `ApiError` from api-client, recognised by shape rather than `instanceof`:
+ * a bundled or duplicated copy of the class would fail an identity check while
+ * carrying exactly the fields we need.
+ */
+function thrownFields(err) {
+    if (typeof err === 'string') {
+        return { message: err, status: null, code: null, choices: null };
+    }
+    if (typeof err !== 'object' || err === null) {
+        return { message: String(err), status: null, code: null, choices: null };
+    }
+    const o = err;
+    const status = typeof o.status === 'number' && o.status >= 100 && o.status < 600
+        ? o.status
+        : null;
+    const code = typeof o.code === 'string' && o.code ? o.code : null;
+    const message = typeof o.message === 'string' && o.message ? o.message : String(err);
+    return { message, status, code, choices: choicesIn(o.body) };
+}
+/** The `recovery` call of a refusal body, when the server sent one. */
+function recoveryIn(body) {
+    if (typeof body !== 'string' || !body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const recovery = parsed?.recovery;
+        if (!recovery || typeof recovery !== 'object' || Array.isArray(recovery))
+            return null;
+        return recovery;
+    }
+    catch {
+        return null;
+    }
+}
+/** The `choices` list of a refusal body, when the server sent one. */
+function choicesIn(body) {
+    if (typeof body !== 'string' || !body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        return Array.isArray(parsed?.choices)
+            ? parsed.choices
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classify a thrown client error (or a plain string this layer raised) into a
+ * stable shape on either tool surface.
+ */
+export function describeOperationError(input, surface = 'sdk') {
+    input = unwrapApiError(input);
+    const shape = classify(input);
+    const { choices } = thrownFields(input);
+    const recovery = typeof input === 'object' && input !== null
+        ? recoveryIn(input.body)
+        : null;
+    const result = {
+        ...shape,
+        ...(choices ? { choices } : {}),
+        ...(recovery ? { recovery: typeof recovery.tool === 'string'
+                ? { ...presentResourceCall(recovery, surface) }
+                : recovery } : {}),
+    };
+    if (recovery)
+        delete result.hint;
+    if (surface === 'sdk' && result.hint)
+        result.hint = result.hint.replace(/\bziggs_(\w+)/g, '$1');
+    return result;
+}
+function classify(input) {
+    const { message, status, code: machineCode } = thrownFields(input);
+    if (machineCode && SHARED_REFUSALS.has(machineCode)) {
+        return { code: machineCode, message };
+    }
+    if (machineCode === 'AGENT_LACKS_HUMAN_AUTHORITY') {
+        return {
+            code: 'AGENT_LACKS_HUMAN_AUTHORITY',
+            message,
+            hint: HUMAN_AUTHORITY_HINT,
+        };
+    }
+    // Can read the agreement, cannot work on it: the server's sentence and its
+    // recovery are the answer, and the generic scope hint would send the agent
+    // back for the read it already has.
+    if (machineCode === 'WORK_ACCESS_REQUIRED') {
+        return { code: machineCode, message };
+    }
+    if (machineCode && isCoverageRefusal(machineCode)) {
+        return { code: machineCode, message, hint: COVERAGE_HINT };
+    }
+    if (machineCode === 'NOT_AUTHORIZED_FOR_SCOPE') {
+        return {
+            code: 'NOT_AUTHORIZED_FOR_SCOPE',
+            message,
+            hint: SCOPE_DENIED_HINT,
+        };
+    }
+    // The server owns the decision. A word such as "scope" may mean a token
+    // restriction, a resource grant, or a policy boundary; prose cannot tell us
+    // which request would authorize it. Preserve every supplied machine code.
+    return { code: machineCode ?? (status === null ? 'TOOL_ERROR' : codeForStatus(status)), message };
+}
+/** Tool runners wrap failures with context. Preserve the original API refusal. */
+function unwrapApiError(input) {
+    const seen = new Set();
+    let current = input;
+    while (current && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        const row = current;
+        if (typeof row.code === 'string' || typeof row.status === 'number' || typeof row.body === 'string')
+            return current;
+        current = row.cause;
+    }
+    return input;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.16",
+  "version": "0.37.17",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {