@ziggs-ai/api-client 0.42.3 → 0.42.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## 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`.
+
 ## 0.42.3
 
 ## 0.42.2

package/dist/capabilities/mcpBriefs.js

@@ -53,12 +53,12 @@ const BRIEFS = {
         changes: 'nothing is approved or rejected. The decision stays pending.',
     },
     ziggs_session_list: {
-        does: 'Lists your open windows: name, app, awake or not, and the executions each holds. Sibling windows of the same assistant key.',
+        does: 'Lists your open windows: name, app, awake or not, and the conversations each holds. Sibling windows of the same assistant key.',
         returns: 'sessions[] for this assistant',
-        next: 'ziggs_session_hold to route an execution to this window',
+        next: 'ziggs_session_hold to route a conversation to this window',
     },
     ziggs_session_hold: {
-        does: 'Routes an authorized execution to this window (the X-Ziggs-Session host). Removes its routing hint from siblings.',
+        does: 'Keeps a conversation in this window: later messages of its thread come here, with what nobody handled yet. Takes it off any sibling. Writing in a thread already holds it.',
         changes: 'changes session routing, not authority or responsibility',
     },
     ziggs_context_snapshot: {
@@ -67,7 +67,7 @@ const BRIEFS = {
     },
     // Agreements
     ziggs_agreement_list: {
-        does: 'Lists the agreements you can reach, including hires. scope mine keeps only agreements you are a party to.',
+        does: 'Lists the agreements you can reach, including hires, as short rows (ziggs_agreement_get has the full one). scope mine keeps only agreements you are a party to.',
     },
     ziggs_agreement_get: {
         does: 'Reads one agreement: parties, terms, status, and approvalAction (who may decide a pending slot).',
@@ -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/payments.d.ts

@@ -20,8 +20,7 @@ import { type CapabilityDefinition } from './types.js';
  * getting paid under an agreement.
  *
  * Balance stays readable, because "see your points" is the intended
- * experience. Note that `ZIGGS_MCP_CORE_ONLY` gates this whole group off
- * including balance, so it is not the lever for this on its own.
+ * experience.
  */
 export declare const paymentBalanceCapability: CapabilityDefinition;
 export declare const PAYMENT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/payments.js

@@ -27,8 +27,7 @@ function client(env) {
  * getting paid under an agreement.
  *
  * Balance stays readable, because "see your points" is the intended
- * experience. Note that `ZIGGS_MCP_CORE_ONLY` gates this whole group off
- * including balance, so it is not the lever for this on its own.
+ * experience.
  */
 export const paymentBalanceCapability = {
     key: 'payment_balance',

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/dist/http/SessionsClient.d.ts

@@ -8,11 +8,12 @@ export interface AssistantSessionRow {
     lastSeenAt: string;
     expiresAt: string;
     workspaceIds: string[];
-    heldExecutionIds: string[];
+    /** Conversations this window holds, each by the first message of its thread. */
+    heldThreadIds: string[];
     awake: boolean;
 }
 /**
- * List sibling windows and hold an execution in this one.
+ * List sibling windows and hold a conversation in this one.
  * Uses the same session headers as the inbox so "this window" is the
  * X-Ziggs-Session the host already sends.
  */
@@ -23,12 +24,14 @@ export declare class SessionsClient {
     private url;
     list(): Promise<AssistantSessionRow[]>;
     /**
-     * Hold `executionContextId` in this window (omit sessionId; server resolves from
-     * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
+     * Hold a conversation in this window (omit sessionId; the server resolves
+     * the window from X-Ziggs-Session), move it to `sessionId`, or pass null to
+     * release it. `messageId` is any message of the conversation: the hold is on
+     * its thread, and mail of that thread nobody handled yet moves with it.
      */
-    hold(executionContextId: string, sessionId?: string | null): Promise<{
+    hold(messageId: string, sessionId?: string | null): Promise<{
         success: true;
-        executionContextId: string;
+        rootMessageId: string;
         sessionId: string | null;
     }>;
 }

package/dist/http/SessionsClient.js

@@ -2,7 +2,7 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 import { buildCredsHeaders } from './operatorHeaders.js';
 /**
- * List sibling windows and hold an execution in this one.
+ * List sibling windows and hold a conversation in this one.
  * Uses the same session headers as the inbox so "this window" is the
  * X-Ziggs-Session the host already sends.
  */
@@ -48,14 +48,16 @@ export class SessionsClient {
         return Array.isArray(rows) ? rows : [];
     }
     /**
-     * Hold `executionContextId` in this window (omit sessionId; server resolves from
-     * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
+     * Hold a conversation in this window (omit sessionId; the server resolves
+     * the window from X-Ziggs-Session), move it to `sessionId`, or pass null to
+     * release it. `messageId` is any message of the conversation: the hold is on
+     * its thread, and mail of that thread nobody handled yet moves with it.
      */
-    async hold(executionContextId, sessionId) {
-        if (!executionContextId?.trim())
-            throw new Error('SessionsClient.hold: executionContextId is required');
+    async hold(messageId, sessionId) {
+        if (!messageId?.trim())
+            throw new Error('SessionsClient.hold: messageId is required');
         const body = {
-            executionContextId: executionContextId.trim(),
+            messageId: messageId.trim(),
         };
         if (sessionId !== undefined)
             body.sessionId = sessionId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.42.3",
+  "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": [