@ziggs-ai/api-client 0.42.4 → 0.42.5

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+## 0.42.5
+
 ## 0.42.4
 
 - `SessionsClient.hold(messageId, sessionId?)` holds a conversation by any message in it and returns its `rootMessageId`; it no longer takes an execution id. `AssistantSessionRow.heldThreadIds` replaces `heldExecutionIds`.

package/dist/capabilities/mcpBriefs.js

@@ -165,7 +165,7 @@ const BRIEFS = {
     ziggs_artifact_find: {
         does: 'Searches artifacts you can read by name, filename or body. coverage and notSearched say what was and was not searched.',
     },
-    ziggs_message_send: { does: 'Sends a canonical command with independent readers: a reply or work. New thread: ziggs_bucket_create, then ziggs_bucket_send.', changes: 'delivers a message and grants its readers access; a request wakes the agents it reaches' },
+    ziggs_message_send: { does: 'Sends a canonical command with independent readers: a reply or work. A first message starts in a bucket: ziggs_bucket_create, then ziggs_bucket_send.', changes: 'delivers a message and grants its readers access; a request wakes the agents it reaches' },
     ziggs_message_replies: { does: 'Reads authorized causal replies by messageId; a reference grants no access and receipt expiry does not erase history.' },
     ziggs_message_read: { does: 'Reads an exact message by messageId under current access and execution policy. Does not acknowledge its receipt.' },
     ziggs_message_list: { does: 'Queries authorized messages by participants, agreement or task. Filters select history, not authority.' },
@@ -232,7 +232,7 @@ const BRIEFS = {
     },
     // Agents, links and introductions
     ziggs_agent_search: {
-        does: 'Finds agents in the store, your workspaces and your own; teammates come back as people. A row you already hire says already hired and names that agreement and workspace.',
+        does: 'Finds agents in the store, your workspaces and your own; teammates come back as people; people you are connected with are in ziggs_link_list. A row you hire says already hired and names that agreement and workspace.',
     },
     ziggs_agent_get: {
         does: 'Reads one agent’s profile by exact id, with how to hire it: listingAgreementId to claim, acceptsProposals for a direct proposal.',
@@ -242,7 +242,7 @@ const BRIEFS = {
         changes: 'sends the invitation; a link gives reach, not work or money',
     },
     ziggs_link_list: {
-        does: 'Lists your links. peer.id is the person on the other side.',
+        does: 'Lists your links: the people you are connected with, your contacts. peer.id is the person on the other side.',
         next: 'ziggs_bucket_create with peer.id',
     },
     ziggs_introduction_mint: {
@@ -266,9 +266,9 @@ const BRIEFS = {
     },
     // Connections and points
     ziggs_connection_list: {
-        does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials. They are listed, not callable over this connection.',
+        does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials; not people (ziggs_link_list). Listed, not callable over this connection.',
         compact: {
-            does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials.',
+            does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials. Not people: those are in ziggs_link_list.',
         },
     },
     ziggs_connection_request: {

package/dist/capabilities/messaging.d.ts

@@ -1,5 +1,11 @@
-import { type CapabilityDefinition } from './types.js';
+import { type CapabilityDefinition, type CapabilityParam } from './types.js';
 export declare const readMessageCapability: CapabilityDefinition;
+/**
+ * The command's real shape, the same keys the server accepts (contracts
+ * `parseMessageCommand`), so a caller sees it in the schema and a wrong key is
+ * refused by name before it is sent.
+ */
+export declare const MESSAGE_COMMAND_PARAM: CapabilityParam;
 export declare const sendMessageCapability: CapabilityDefinition;
 export declare const readRepliesCapability: CapabilityDefinition;
 export declare const queryMessagesCapability: CapabilityDefinition;

package/dist/capabilities/messaging.js

@@ -2,7 +2,24 @@ import { MessageRecordsClient } from '../http/MessageRecordsClient.js';
 import { fullCreds } from './types.js';
 const client = (env) => { const creds = fullCreds(env); return new MessageRecordsClient(creds.operatorKey, creds.agentId, env.baseUrl); };
 export const readMessageCapability = { key: 'message_read', names: { sdk: 'message_read', mcp: 'ziggs_message_read' }, title: 'Read exact message', descriptions: { sdk: 'Read one authorized message. Returns content, intent (fyi or request), independent readers/recipients and authorized relationships. Does not acknowledge delivery.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true } }, handler: (args, env) => client(env).get(String(args.messageId)) };
-export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; intent:"fyi" or "request". A request wakes the agents it is delivered to; an fyi is delivered and filed, never woken on. Nothing records whether a request was answered: a reply is a message with relationships.replyToMessageId. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. A new conversation starts in a bucket: bucket_create with its people, then bucket_send; this tool answers a message or writes under work. Reuse operationId unchanged on retry. Refused with "Nothing authorizes giving … access to this message" means you have no contact basis for that reader (membership, a link, an agreement or a listing): ask its owner with access_request scopeKind=contact and scopeId=that reader, then send once they approve.' }, annotation: 'destructive', needsAgentId: true, params: { command: { type: 'object', required: true, description: 'MessageCommand with explicit independent audience, deliveries, intent and optional mandate.' } }, handler: (args, env) => client(env).send(args.command) };
+const principals = { type: 'object', required: true, properties: { kind: { type: 'string', enum: ['explicit'], required: true }, principalIds: { type: 'array', required: true, items: { type: 'string' } } } };
+/**
+ * The command's real shape, the same keys the server accepts (contracts
+ * `parseMessageCommand`), so a caller sees it in the schema and a wrong key is
+ * refused by name before it is sent.
+ */
+export const MESSAGE_COMMAND_PARAM = { type: 'object', required: true, properties: {
+        operationId: { type: 'string', required: true, description: 'Reuse on retry.' },
+        content: { type: 'object', required: true, properties: { text: { type: 'string', required: true } } },
+        audience: principals,
+        deliveries: principals,
+        intent: { type: 'string', required: true, enum: ['fyi', 'request'] },
+        mandate: { type: 'object', properties: { agreementId: { type: 'string', required: true }, taskId: { type: 'string' } } },
+        relationships: { type: 'object', properties: { replyToMessageId: { type: 'string' }, taskIds: { type: 'array', items: { type: 'string' } }, artifacts: { type: 'array', items: { type: 'object' } } } },
+        sources: { type: 'array', items: { type: 'object' } },
+        page: { type: 'object' },
+    } };
+export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; intent:"fyi" or "request". A request wakes the agents it is delivered to; an fyi is delivered and filed, never woken on. Nothing records whether a request was answered: a reply is a message with relationships.replyToMessageId. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. A new conversation starts in a bucket: bucket_create with its people, then bucket_send; this tool answers a message or writes under work. Reuse operationId unchanged on retry. Refused with "Nothing authorizes giving … access to this message" means you have no contact basis for that reader (membership, a link, an agreement or a listing): ask its owner with access_request scopeKind=contact and scopeId=that reader, then send once they approve.' }, annotation: 'destructive', needsAgentId: true, params: { command: MESSAGE_COMMAND_PARAM }, handler: (args, env) => client(env).send(args.command) };
 export const readRepliesCapability = { key: 'message_replies', names: { sdk: 'message_replies', mcp: 'ziggs_message_replies' }, title: 'Read replies', descriptions: { sdk: 'Read currently authorized causal replies; links never grant access. Continue using nextCursor as before.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).replies(String(args.messageId), { before: args.before, limit: args.limit }) };
 export const queryMessagesCapability = { key: 'message_list', names: { sdk: 'message_list', mcp: 'ziggs_message_list' }, title: 'Query messages', descriptions: { sdk: 'Query authorized messages. Use conversationOf with an exact message id to browse messages connected by readable reply relationships; use nextCursor as before for earlier turns. Select conversationOf independently of agreementId, taskId or participantIds. History never selects authority.' }, annotation: 'read-only', needsAgentId: true, params: { conversationOf: { type: 'string', description: 'Authorized anchor message; follows readable causal links, never a reader roster. Each result still requires read access and any execution input authorization.' }, q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string' }, taskId: { type: 'string' }, participantIds: { type: 'array', items: { type: 'string' } }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).list(args) };
 export const messageControlsCapability = { key: 'message_controls', names: { sdk: 'message_controls', mcp: 'ziggs_message_controls' }, title: 'Inspect message mandate', descriptions: { sdk: 'Discover recipients and current authority under an explicitly selected agreement/task without reading message history.' }, annotation: 'read-only', needsAgentId: true, params: { q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string', required: true }, taskId: { type: 'string' } }, handler: (args, env) => client(env).controls(String(args.agreementId), args.taskId) };

package/dist/capabilities/types.d.ts

@@ -17,6 +17,12 @@ export interface CapabilityParam {
         properties?: Record<string, unknown>;
         required?: string[];
     };
+    /**
+     * Only for type 'object': its fields, published in the tool's schema. When
+     * given, the object takes exactly these keys and a caller's other key is
+     * refused by name. Left out, the object is open.
+     */
+    properties?: Record<string, CapabilityParam>;
 }
 /**
  * Runtime context a surface adapter hands the shared handler. `creds.agentId`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.42.4",
+  "version": "0.42.5",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -31,7 +31,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "0.49.1",
+    "@ziggs-ai/contracts": "0.50.1",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [