@ziggs-ai/api-client 0.22.1 → 0.22.3

package/dist/capabilities/chat.js

@@ -49,7 +49,7 @@ export function presentSendResult(result, env) {
 export const openConversationCapability = {
     key: 'chat_open',
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
-    title: 'Open a chat',
+    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.',
@@ -59,7 +59,7 @@ export const openConversationCapability = {
         participantId: {
             type: 'string',
             required: true,
-            description: 'User or agent id to converse with (from agent search — do not guess ids)',
+            description: 'Known user or agent id from search, a directory, a chat, or an agreement. No existing chat is required; do not guess ids.',
         },
         newChat: {
             type: 'boolean',

package/dist/capabilities/context.js

@@ -286,10 +286,18 @@ function openBodyFromArgs(args) {
         body.limit = args['limit'];
     return body;
 }
-function presentOpenResult(result) {
+function presentOpenResult(result, env) {
     // Never attach a ready write. An unreadable row already carries
     // access.continuation (owner-decision); this call must not execute it.
-    return { ...result, actions: [] };
+    const requestTool = env.surface === 'mcp' ? 'ziggs_context_request' : 'context_request';
+    const chatTool = env.surface === 'mcp' ? 'ziggs_chat_open' : 'chat_open';
+    return {
+        ...result,
+        actions: [],
+        ...(result.ref.kind === 'artifact' && result.outcome !== 'ok' ? {
+            requestAccessHint: `If a source you already read supplied this artifact reference and its human owner, ${requestTool} can ask that owner for temporary read access without a prior grant. It needs a conversation with the owner; ${chatTool} can open or reuse one, subject to authorization. Discover the request tool's schema before calling it. This response does not confirm existence or ownership. A request grants no access until the human owner approves.`,
+        } : {}),
+    };
 }
 export const openCapability = {
     key: 'open',
@@ -310,7 +318,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)));
+        return presentOpenResult(await client.open(openBodyFromArgs(args)), env);
     },
 };
 export const accessExplainCapability = {
@@ -328,7 +336,7 @@ export const accessExplainCapability = {
         const creds = fullCreds(env);
         const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
         const result = await client.explain(openBodyFromArgs(args));
-        return presentOpenResult(result);
+        return presentOpenResult(result, env);
     },
 };
 export const CONTEXT_CAPABILITIES = [

package/package.json

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