@ziggs-ai/api-client 0.23.0 → 0.23.1

package/dist/capabilities/chat.js

@@ -51,15 +51,15 @@ 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. Calling it again for the same participant returns the SAME chat, 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. 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. Calling it again for the same participant returns the SAME chat; 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. With none of those the call is refused and names the levers. 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 or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, 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. Calling it again for the same participant returns the SAME chat; 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. 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.',
     },
     annotation: 'write',
     params: {
         participantId: {
             type: 'string',
             required: true,
-            description: 'Known user or agent id from search, a directory, a chat, or an agreement. No existing chat is required; do not guess ids.',
+            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.',
         },
         newChat: {
             type: 'boolean',

package/dist/capabilities/discovery.js

@@ -5,15 +5,15 @@ export const agentSearchCapability = {
     names: { sdk: 'agent_search', mcp: 'ziggs_agent_search' },
     title: 'Search for agents',
     descriptions: {
-        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND your own org-mates. A link does NOT make the other person\'s agents findable — how they staff their side is theirs, and it changes without telling anyone; reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
-        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND your own org-mates — so you can find a teammate\'s assistant by the teammate\'s name or by its own name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you; a same-org hit carries `person` (the teammate\'s userId and name), and ziggs_chat_open with that userId reaches the person themselves. A link does NOT make the other person\'s agents findable: a link makes the PERSON addressable, never their staffing list. To reach someone you are linked with, take their peer id from ziggs_link_list and ziggs_chat_open with that; their agents become known to you by turning up in rooms. Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and a linked person\'s unpublished agent is one of those. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `managed`, or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
+        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store, your org\'s own agents and your own agents, and it matches your teammates by name: a teammate comes back under `people` as a person to message (chat_open with their userId), never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
+        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store, your org\'s own agents and your own agents. It also matches your teammates by name: a teammate comes back under `people` (userId and name) as a person to message with ziggs_chat_open participantId=<userId>, never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: take a linked person\'s peer id from ziggs_link_list and ziggs_chat_open with that. Passing an EXACT agent id resolves that one agent when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and another person\'s unpublished agent is one of those. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org` (your org\'s own agent), `managed` (yours), or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
         query: {
             type: 'string',
             required: true,
-            description: 'Keyword/natural-language search (published store + your org-mates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)',
+            description: "Keyword/natural-language search (published store, your org's own agents, your own agents, and teammates by name) OR an exact agent id (resolves that agent when you can reach it)",
         },
         limit: { type: 'number', description: 'Max results (default server-side)' },
         minScore: { type: 'number', description: 'Minimum match score filter' },
@@ -31,27 +31,37 @@ export const agentSearchCapability = {
         if (!result.success) {
             throw new Error(result.error ?? result.message ?? 'search failed');
         }
+        const chatOpen = env.surface === 'mcp' ? 'ziggs_chat_open' : 'chat_open';
+        const linkList = env.surface === 'mcp' ? 'ziggs_link_list' : 'link_list';
+        const people = result.people ?? [];
+        const messageThem = people.length
+            ? {
+                people,
+                peopleNote: `These are teammates whose name matched. Message the person with ${chatOpen} participantId=<userId>; which of their agents answers is theirs to decide.`,
+            }
+            : {};
         if (!result.agents?.length) {
             // a bare {count: 0} reads as "discovery is down" to LLM
             // callers — say what was searched and how to recover instead.
             return {
                 count: 0,
                 agents: [],
+                ...messageThem,
                 searched: [
                     'published store: agents by name, description and tags',
-                    'your org: agents by name, description and tags',
-                    'your org: people by name (returns their agents, with person.userId)',
+                    "your org's own agents and your own agents: by name, description and tags",
+                    'your org: people by name (returned under people, to message as people)',
                 ],
-                hint: 'Zero hits means nothing matched these terms; discovery itself is up. ' +
-                    'People are not agents: a teammate\'s assistant is found by the teammate\'s name or by its own name, and a hit carries person.userId. ' +
-                    'To reach the person themselves, open a chat with that user id (chat_open participantId). ' +
+                hint: 'Zero agents means no agent matched these terms; discovery itself is up. ' +
+                    "People are not agents: a teammate is found by their name and comes back under people, never as their agents. " +
+                    `To reach them, open a chat with that user id (${chatOpen} participantId). ` +
                     'Matching is lexical, so try shorter or different keywords. ' +
                     'If you already know the agent, pass its exact agent id as the query to resolve it directly. ' +
                     'Searching for someone you are LINKED with will always miss: a link makes the person addressable, ' +
-                    'not their agents. Take their peer id from link_list and open a chat with the person instead.',
+                    `not their agents. Take their peer id from ${linkList} and open a chat with the person instead.`,
             };
         }
-        return { count: result.agents.length, agents: result.agents };
+        return { count: result.agents.length, agents: result.agents, ...messageThem };
     },
     sdkOptions: { isGenericFallback: true },
 };

package/dist/http/AgentSearchClient.d.ts

@@ -5,9 +5,18 @@ export interface AgentSearchOptions {
 export interface AgentSearchResult {
     success: boolean;
     agents?: AgentProfile[];
+    /**
+     * Teammates whose name matched, as people to message. Their agents are not
+     * listed: someone else's agent is reached through the person it answers for.
+     */
+    people?: AgentSearchPerson[];
     error?: string;
     message?: string;
 }
+export interface AgentSearchPerson {
+    userId: string;
+    displayName: string;
+}
 export interface AgentProfile {
     agentId: string;
     name: string;

package/dist/http/AgentSearchClient.js

@@ -33,8 +33,8 @@ export class AgentSearchClient {
                 runtimeLog.warn('AgentSearchClient', `⚠️ searchAgents failed agent=${this.agentId} ${response.status} ${response.statusText} url=${url} body=${errorText.slice(0, 200)}`);
                 return { success: false, error: `Search failed: ${response.status}`, message: errorText };
             }
-            const { results = [] } = await response.json();
-            return { success: true, agents: results };
+            const { results = [], people = [] } = await response.json();
+            return { success: true, agents: results, people };
         }
         catch (error) {
             runtimeLog.warn('AgentSearchClient', `⚠️ searchAgents error agent=${this.agentId} url=${url} message=${error.message}`);

package/package.json

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