@ziggs-ai/api-client 0.26.0 → 0.28.0

package/dist/capabilities/artifacts.js

@@ -304,7 +304,7 @@ export const listArtifactsCapability = {
         mcp: 'List business artifacts YOU authored, across every scope and none; tool-operation and thought traces are excluded. Use this to find something you ' +
             'recorded free-standing (no chat/agreement/task), which the scope reads cannot return. ' +
             'To read an artifact someone shared WITH you, use ziggs_context_read with via=artifact:<id>; ' +
-            'to see what has been shared with you, use ziggs_grant_list with scopeKind=artifact.',
+            'to see what has been shared with you, use ziggs_grant_list with scopeKind ["artifact"].',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/chat.js

@@ -33,9 +33,12 @@ export function presentSendResult(result, env) {
     const destination = delivery.broadcast
         ? 'the humans in the room, not one addressee'
         : `${delivery.to.id} (${delivery.to.type})`;
+    // What counted it, in the server's words: a stranger's free messages with a
+    // listed agent run out, and the person writing needs to know before they do.
+    const counted = result.coverage?.message ? ` ${result.coverage.message}` : '';
     return {
         ...base,
-        delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}, addressed to ${destination}. Mailbox routing is unconfirmed; a person may be covered by an assistant. Accepted is not read and does not confirm a wake or reply.`,
+        delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}, addressed to ${destination}. Mailbox routing is unconfirmed; a person may be covered by an assistant. Accepted is not read and does not confirm a wake or reply.${counted}`,
         to: delivery.to,
     };
 }
@@ -51,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. participantIds takes people only: another agent joins a room when a person adds it in the web app, where its approval rules apply, and 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 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 takes people only: another agent joins a room when a person adds it in the web app, where its approval rules apply, and 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. 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.',
     },
     annotation: 'write',
     params: {
@@ -60,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 user ids. Creates a separate group, or invites these people to chatId. Use instead of participantId. Each invitation is authorized separately.' },
+        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.' },
         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.' },
         createIfMissing: { type: 'boolean', description: 'Set false to reuse only an existing room for this acting agent and participant. A missing room is refused without creating a replacement.' },
@@ -87,7 +90,7 @@ export const openConversationCapability = {
             if (args.participantId !== undefined || !Array.isArray(args.participantIds) ||
                 args.participantIds.length < 1 || args.participantIds.length > 20 ||
                 args.participantIds.some(id => typeof id !== 'string' || !id.trim())) {
-                throw new Error('Use participantIds containing 1–20 people, without participantId');
+                throw new Error('Use participantIds containing 1–20 ids, without participantId');
             }
             if (!args.chatId && (typeof args.idempotencyKey !== 'string' || !args.idempotencyKey.trim())) {
                 throw new Error('Group creation requires an idempotencyKey; reuse it when retrying');
@@ -96,7 +99,7 @@ export const openConversationCapability = {
         else if (args.chatId || args.idempotencyKey) {
             throw new Error('chatId and idempotencyKey require participantIds');
         }
-        const { chatId, reused } = await openConversation({
+        const { chatId, reused, invited } = await openConversation({
             ...(typeof args.participantId === 'string' ? { participantId: args.participantId } : {}),
             ...(Array.isArray(args.participantIds) ? { participantIds: args.participantIds } : {}),
             ...(typeof args.chatId === 'string' ? { chatId: args.chatId } : {}),
@@ -106,14 +109,14 @@ export const openConversationCapability = {
             ...(typeof args.agreementId === 'string' && args.agreementId ? { agreementId: args.agreementId } : {}),
         }, fullCreds(env));
         const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
-        const grantNote = `Use ${lister} scopeKind=chat to inspect your room grants. Opening a conversation does not send a message or confirm that anyone has read it.`;
+        const grantNote = `Use ${lister} with scopeKind ["chat"] to inspect your room grants. Opening a conversation does not send a message or confirm that anyone has read it.`;
         // word the note from the outcome instead of covering both cases.
         // "Open (or reused)" told the agent the distinction existed and then
         // 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.
         const outcomeNote = args.chatId
-            ? 'The named people can participate in this room. Their history access remains bounded by their grants.'
+            ? 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
@@ -123,8 +126,25 @@ export const openConversationCapability = {
             chatId,
             actingAgentId: fullCreds(env).agentId,
             ...(typeof reused === 'boolean' ? { reused } : {}),
+            ...(invited ? { invited } : {}),
             note: `${outcomeNote} ${grantNote}`,
         };
     },
 };
+/** Say what happened to each invited id, so the agent reports it truthfully. */
+function inviteNote(invited) {
+    if (!invited?.length) {
+        return 'The named people can participate in this room. Their history access remains bounded by their grants.';
+    }
+    const ids = (status) => invited.filter((row) => row.status === status).map((row) => row.id);
+    const parts = [];
+    if (ids('added').length)
+        parts.push(`Added: ${ids('added').join(', ')}.`);
+    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.`);
+    }
+    return `${parts.join(' ')} Invited people read from now on.`;
+}
 export const CHAT_CAPABILITIES = [openConversationCapability];

package/dist/capabilities/connections.js

@@ -19,7 +19,7 @@ export const connectionProxyCapability = {
         sdk: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira) without ever seeing the credential. " +
             "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use mcp_tool_call / mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
-            "Don't know connectionId/grantId yet? Use grant_list (scopeKind=connection) or connection_list_grants first.",
+            "Don't know connectionId/grantId yet? Use grant_list (scopeKind [\"connection\"]) or connection_list_grants first.",
         mcp: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list) without ever seeing the credential. " +
             "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use ziggs_mcp_tool_call / ziggs_mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
@@ -128,7 +128,7 @@ export const requestConnectionCapability = {
                     ? "A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. " +
                         "Once approved, the connection + grant appear in ziggs_connection_list for ziggs_mcp_tools_list / ziggs_mcp_tool_call."
                     : "A connection-consent card is now in the chat awaiting your principal — they approve it right there. " +
-                        "Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for mcp_tools_list / mcp_tool_call.",
+                        "Once approved, the connection + grant appear in grant_list (scopeKind [\"connection\"]) / connection_list_grants for mcp_tools_list / mcp_tool_call.",
             };
         }
         catch (e) {

package/dist/capabilities/context.js

@@ -64,7 +64,7 @@ export const contextReadCapability = {
     title: 'Read context you hold',
     descriptions: {
         sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
-        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
+        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list with scopeKind ["artifact"] shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
     },
     annotation: 'read-only',
     params: {

package/dist/engagementGuide.js

@@ -272,7 +272,7 @@ export function strangerBriefGuide(env, chatId) {
         kind: 'stranger_brief',
         outcome: 'pending',
         chatId,
-        summary: "A stranger's brief is not a work order. Draft an agreement; do not create a task under a hire you do not have.",
+        summary: "A stranger's brief is not a work order. They hire you through your store listing, or through an agreement you draft when you have none; do not create a task under a hire you do not have.",
         next: nextCall(env, 'agreement_request', undefined, 'draft the agreement this brief would ride', { definition: agreementRequestCapability }),
     };
 }

package/dist/http/ChatClient.d.ts

@@ -13,6 +13,14 @@ import { type Creds } from '../types.js';
  * with without a second call.
  */
 export type ChatSummary = ChatReadDto;
+/** What happened to one id when chat_open invited into an existing room. */
+export interface ChatOpenInvite {
+    id: string;
+    kind: 'person' | 'agent';
+    /** pending: an agent's joining waits for the people in the room to approve it. */
+    status: 'added' | 'already-here' | 'pending';
+    admissionId?: string;
+}
 export interface OpenConversationInput {
     participantId?: string;
     participantIds?: string[];
@@ -29,6 +37,7 @@ export declare function openConversation(participant: string | OpenConversationI
 }): Promise<{
     chatId: string;
     reused?: boolean;
+    invited?: ChatOpenInvite[];
 }>;
 export interface SendChatMessageInput {
     /**
@@ -84,7 +93,20 @@ export type { MessageDelivery } from '@ziggs-ai/contracts';
  */
 export type SendChatMessageResult = Omit<WireSendChatMessageResult, 'delivery'> & {
     delivery?: MessageDelivery;
+    /**
+     * What covers this message, when something counts it: a hire's shared
+     * allowance, or a listed agent's free messages for a stranger ("2 of 3 free
+     * messages used with seo-growth."). Absent for ordinary conversation.
+     */
+    coverage?: ConversationCoverageReceipt;
 };
+/** The server's receipt for a counted message. */
+export interface ConversationCoverageReceipt {
+    agreementId: string;
+    messagesUsed: number;
+    messageLimit: number | null;
+    message: string;
+}
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface AddChatMemberInput {
     chatId: string;
@@ -135,6 +157,7 @@ export declare class ChatClient {
     }): Promise<{
         chatId: string;
         reused?: boolean;
+        invited?: ChatOpenInvite[];
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;

package/dist/http/ChatClient.js

@@ -38,11 +38,31 @@ export async function openConversation(participant, creds, { newChat = false, ag
     // the room — defaulting to false would report a reused conversation as fresh,
     // which is worse than saying nothing.
     const reused = data['reused'];
+    const invited = Array.isArray(data['invited'])
+        ? data['invited']
+        : undefined;
     return {
         chatId: data['chatId'],
         ...(typeof reused === 'boolean' ? { reused } : {}),
+        ...(invited ? { invited } : {}),
     };
 }
+function coverageFrom(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const row = value;
+    return typeof row['agreementId'] === 'string' &&
+        typeof row['message'] === 'string' &&
+        typeof row['messagesUsed'] === 'number' &&
+        (row['messageLimit'] === null || typeof row['messageLimit'] === 'number')
+        ? {
+            agreementId: row['agreementId'],
+            messagesUsed: row['messagesUsed'],
+            messageLimit: row['messageLimit'],
+            message: row['message'],
+        }
+        : null;
+}
 /**
  * POST /chats/:chatId/members — add user/agent; agent-invite may return pending admission.
  */
@@ -115,6 +135,7 @@ export async function sendChatMessage(input, creds) {
     }
     const data = (await res.json().catch(() => null));
     const delivery = data?.['delivery'];
+    const coverage = coverageFrom(data?.['coverage']);
     return {
         success: Boolean(data?.['success']),
         message: String(data?.['message'] ?? 'ok'),
@@ -126,6 +147,7 @@ export async function sendChatMessage(input, creds) {
         ...(delivery && typeof delivery === 'object'
             ? { delivery: delivery }
             : {}),
+        ...(coverage ? { coverage } : {}),
     };
 }
 export async function listMyChats(creds) {

package/package.json

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