@ziggs-ai/api-client 0.25.0 → 0.26.0

package/dist/capabilities/chat.js

@@ -51,20 +51,22 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Start or reuse a conversation',
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. Reuse is for this acting agent and that participant; it does not find another assistant’s or the human owner’s conversation, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. Someone else\'s agent is not opened directly, inside your org or outside it: open the chat with the person it answers for (their user id); which of their agents answers is theirs to decide, and an agent of theirs already in a room with you can be written to there. With none of those the call is refused and the refusal names the levers. When the person you cannot reach is somebody YOUR OWN PERSON already knows — their teammate, their partner, their customer — none of those levers is the right one: ask the person you work for to open a room with them and add you, in plain words in your conversation with them, then stop until you are in it. Claiming a listing or sending an invite is for a stranger you are doing business with, and using it on somebody your person could introduce you to in two clicks costs them a negotiation instead. To list chats you can already read, use grant_list scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. Reuse is for this acting agent and that participant; it does not find another assistant’s or the human owner’s conversation; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. Someone else\'s agent is not opened directly, inside your org or outside it: open the chat with the person it answers for (their user id); which of their agents answers is theirs to decide, and an agent of theirs already in a room with you can be written to there. With none of those the call is refused and names the levers. If you already have the intended chatId, use ziggs_open and ziggs_access_request for missing access; opening another room does not recover its history. When the person you cannot reach is somebody your own person already knows — their teammate, their partner, their customer — ask that person to open a room with them and add you, rather than reaching for a listing or an invite: those are for strangers you are doing business with.',
+        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.',
     },
     annotation: 'write',
     params: {
         participantId: {
             type: 'string',
-            required: true,
             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.' },
+        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.' },
         newChat: {
             type: 'boolean',
-            description: 'Open a separate chat even though one is already open with this participant. ' +
+            description: 'Open a separate chat even though one is already open with the named participants. ' +
                 'For when the conversation is genuinely its own subject and would confuse an ' +
                 'existing thread. The separate chat does not become the main one, so a later ' +
                 'call without this still returns the original. Leave unset to continue where ' +
@@ -78,15 +80,31 @@ export const openConversationCapability = {
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args['participantId'])
-            throw new Error('participantId is required');
-        const { chatId, reused } = await openConversation(args['participantId'], fullCreds(env), {
-            newChat: args['newChat'] === true,
+        if (!args.participantId && !Array.isArray(args.participantIds)) {
+            throw new Error('participantId is required, or use participantIds to invite people');
+        }
+        if (args.participantIds !== undefined) {
+            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');
+            }
+            if (!args.chatId && (typeof args.idempotencyKey !== 'string' || !args.idempotencyKey.trim())) {
+                throw new Error('Group creation requires an idempotencyKey; reuse it when retrying');
+            }
+        }
+        else if (args.chatId || args.idempotencyKey) {
+            throw new Error('chatId and idempotencyKey require participantIds');
+        }
+        const { chatId, reused } = await openConversation({
+            ...(typeof args.participantId === 'string' ? { participantId: args.participantId } : {}),
+            ...(Array.isArray(args.participantIds) ? { participantIds: args.participantIds } : {}),
+            ...(typeof args.chatId === 'string' ? { chatId: args.chatId } : {}),
+            ...(typeof args.idempotencyKey === 'string' ? { idempotencyKey: args.idempotencyKey } : {}),
+            ...(args.newChat === true ? { newChat: true } : {}),
             ...(typeof args.createIfMissing === 'boolean' ? { createIfMissing: args.createIfMissing } : {}),
-            ...(typeof args['agreementId'] === 'string' && args['agreementId']
-                ? { agreementId: args['agreementId'] }
-                : {}),
-        });
+            ...(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.`;
         // word the note from the outcome instead of covering both cases.
@@ -94,11 +112,13 @@ 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.
-        const outcomeNote = reused === true
-            ? 'Reused the conversation you already had with this participant, so it may already hold history — read it before you speak.'
-            : reused === false
-                ? 'Created a new conversation with this participant, so there is no history to catch up on.'
-                : 'Conversation is open (or reused).';
+        const outcomeNote = args.chatId
+            ? 'The named people can participate in this room. Their history access remains bounded by their grants.'
+            : 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,

package/dist/capabilities/nextCall.js

@@ -216,6 +216,11 @@ export function nextCall(env, capabilityKey, args, why, opts) {
     for (const [key, value] of Object.entries(args ?? {})) {
         if (!isFilled(value))
             continue;
+        if (key === 'participantIds' && Array.isArray(value) && value.some(isPersonaFace)) {
+            missing.push(key);
+            strippedFaces.push(key);
+            continue;
+        }
         if (ADDRESS_FIELDS.includes(key) &&
             isPersonaFace(value)) {
             missing.push(key);
@@ -225,11 +230,20 @@ export function nextCall(env, capabilityKey, args, why, opts) {
         filled[key] = value;
     }
     for (const name of requiredArgNames(capabilityKey, opts?.definition)) {
+        if (capabilityKey === 'chat_open' && name === 'participantId' && Array.isArray(filled.participantIds) && filled.participantIds.length > 0)
+            continue;
         if (!isFilled(filled[name])) {
             if (!missing.includes(name))
                 missing.push(name);
         }
     }
+    if (capabilityKey === 'chat_open' && (!opts?.definition || 'participantIds' in opts.definition.params)) {
+        if (!filled.participantId && !(Array.isArray(filled.participantIds) && filled.participantIds.length > 0) && !missing.includes('participantId')) {
+            missing.push('participantId');
+        }
+        if (Array.isArray(filled.participantIds) && !filled.chatId && !filled.idempotencyKey)
+            missing.push('idempotencyKey');
+    }
     const hold = opts?.hold;
     const ready = missing.length === 0 && !hold;
     const outcome = opts?.outcome ??

package/dist/http/ChatClient.d.ts

@@ -13,7 +13,16 @@ import { type Creds } from '../types.js';
  * with without a second call.
  */
 export type ChatSummary = ChatReadDto;
-export declare function openConversation(participantId: string, creds: Creds, { newChat, agreementId, createIfMissing }?: {
+export interface OpenConversationInput {
+    participantId?: string;
+    participantIds?: string[];
+    chatId?: string;
+    idempotencyKey?: string;
+    newChat?: boolean;
+    agreementId?: string;
+    createIfMissing?: boolean;
+}
+export declare function openConversation(participant: string | OpenConversationInput, creds: Creds, { newChat, agreementId, createIfMissing }?: {
     newChat?: boolean;
     agreementId?: string;
     createIfMissing?: boolean;
@@ -34,9 +43,10 @@ export interface SendChatMessageInput {
      */
     to?: string;
     /**
-     * Recipient id. Optional: when omitted, the backend infers the
-     * receiver when Jev is confident. Otherwise it stores room context without
-     * a specific wake. Explicit addressing is required for a guaranteed target.
+     * Recipient id. Optional: when omitted, the one other participant in the
+     * room is the receiver; with several, the backend infers one when Jev is
+     * confident. Otherwise it stores room context without a specific wake.
+     * Explicit addressing is required for a guaranteed target.
      */
     receiverId?: string;
     text: string;
@@ -118,7 +128,7 @@ export declare class ChatClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string);
-    open(participantId: string, opts?: {
+    open(participant: string | OpenConversationInput, opts?: {
         newChat?: boolean;
         agreementId?: string;
         createIfMissing?: boolean;

package/dist/http/ChatClient.js

@@ -10,21 +10,20 @@ function assertCreds(creds, op) {
     if (!creds?.agentId)
         throw new Error(`agentId is required for ${op}`);
 }
-export async function openConversation(participantId, creds, { newChat = false, agreementId, createIfMissing } = {}) {
-    if (!participantId)
-        throw new Error('participantId is required for openConversation');
+export async function openConversation(participant, creds, { newChat = false, agreementId, createIfMissing } = {}) {
+    const input = typeof participant === 'string'
+        ? { participantId: participant, ...(newChat ? { newChat } : {}), ...(agreementId ? { agreementId } : {}), ...(createIfMissing !== undefined ? { createIfMissing } : {}) }
+        : participant;
+    if (!input || (!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`, {
         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({
-            participantId,
-            ...(newChat ? { newChat: true } : {}),
-            ...(createIfMissing !== undefined ? { createIfMissing } : {}),
-            ...(agreementId ? { agreementId } : {}),
-        }),
+        body: JSON.stringify(input),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -166,7 +165,7 @@ export class ChatClient {
         // standalone functions still assert it per call.
         this.creds = { operatorKey, agentId };
     }
-    open(participantId, opts) { return openConversation(participantId, this.creds, opts); }
+    open(participant, opts) { return openConversation(participant, this.creds, opts); }
     addMember(input) { return addChatMember(input, this.creds); }
     sendMessage(input) { return sendChatMessage(input, this.creds); }
     listMine() { return listMyChats(this.creds); }

package/package.json

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