@canonmsg/agent-tools 0.9.1 → 0.10.0

package/dist/communication-tool.js

@@ -36,14 +36,15 @@ const DIRECT_SELECTION_SCHEMA = {
 export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAME) {
     return {
         name,
-        description: 'Find discoverable agents or communicate in Canon. Message a known conversation, start/continue a '
-            + 'direct conversation, create a group, forward an exact message, share a '
-            + 'contact, or manage group members. Canon '
-            + 'enforces the recipient and agent-deployer policies; a new direct '
-            + 'conversation or group member may require approval.',
+        description: 'Find agents, list current conversations with their participants, message an explicit conversation, '
+            + 'start_conversation with a person or agent (new by default), create_conversation with an optional title, '
+            + 'manage_participants, leave, forward a message or share a contact. Check the current participants '
+            + 'before selecting an existing conversation. Canon enforces admission and operator permissions.',
         inputSchema: {
             type: 'object',
             oneOf: [
+                { type: 'object', required: ['action'], additionalProperties: false, properties: { action: { const: 'list_conversations' }, limit: { type: 'integer', minimum: 1, maximum: 100 } } },
+                { type: 'object', required: ['action', 'conversationId'], additionalProperties: false, properties: { action: { const: 'leave_conversation' }, conversationId: NON_EMPTY_ID } },
                 {
                     type: 'object',
                     required: ['action'],
@@ -84,7 +85,7 @@ export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAM
                     required: ['action', 'principalId', 'text'],
                     additionalProperties: false,
                     properties: {
-                        action: { const: 'start_direct' },
+                        action: { enum: ['start_conversation', 'start_direct'] },
                         principalId: NON_EMPTY_ID,
                         text: MESSAGE_TEXT,
                         selection: DIRECT_SELECTION_SCHEMA,
@@ -93,10 +94,10 @@ export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAM
                 },
                 {
                     type: 'object',
-                    required: ['action', 'name', 'memberIds'],
+                    required: ['action', 'memberIds'],
                     additionalProperties: false,
                     properties: {
-                        action: { const: 'create_group' },
+                        action: { enum: ['create_conversation', 'create_group'] },
                         name: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.groupNameChars },
                         memberIds: {
                             type: 'array',
@@ -141,7 +142,7 @@ export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAM
                     required: ['action', 'conversationId', 'userId', 'operation'],
                     additionalProperties: false,
                     properties: {
-                        action: { const: 'manage_group_members' },
+                        action: { enum: ['manage_participants', 'manage_group_members'] },
                         conversationId: NON_EMPTY_ID,
                         userId: NON_EMPTY_ID,
                         operation: { enum: ['add', 'remove'] },
@@ -164,6 +165,17 @@ function hasOnlyKeys(record, allowed) {
 export function parseCommunicateToolInput(value) {
     if (!isRecord(value))
         throw new Error('communicate arguments must be an object');
+    if (value.action === 'list_conversations') {
+        if (!hasOnlyKeys(value, new Set(['action', 'limit'])) || (value.limit !== undefined && (!Number.isInteger(value.limit) || value.limit < 1 || value.limit > 100)))
+            throw new Error('list_conversations requires an optional limit from 1 to 100');
+        return { action: 'list_conversations', ...(typeof value.limit === 'number' ? { limit: value.limit } : {}) };
+    }
+    if (value.action === 'leave_conversation') {
+        const conversationId = readRequiredString(value.conversationId);
+        if (!hasOnlyKeys(value, new Set(['action', 'conversationId'])) || !conversationId)
+            throw new Error('leave_conversation requires conversationId');
+        return { action: 'leave_conversation', conversationId };
+    }
     if (value.action === 'discover_agents') {
         if (!hasOnlyKeys(value, new Set(['action', 'query', 'limit', 'cursor']))) {
             throw new Error('discover_agents contains unsupported fields');
@@ -194,21 +206,21 @@ export function parseCommunicateToolInput(value) {
             ...(typeof value.cursor === 'string' ? { cursor: value.cursor } : {}),
         };
     }
-    if (value.action === 'create_group') {
+    if (value.action === 'create_group' || value.action === 'create_conversation') {
         if (!hasOnlyKeys(value, new Set(['action', 'name', 'memberIds']))) {
             throw new Error('create_group contains unsupported fields');
         }
-        const name = readRequiredString(value.name);
-        if (!name)
-            throw new Error('communicate.name is required');
+        const name = value.name === undefined ? undefined : readRequiredString(value.name);
+        if (name === null)
+            throw new Error('communicate.name must be a non-empty string when supplied');
         if (!Array.isArray(value.memberIds)
             || value.memberIds.length === 0
             || !value.memberIds.every((entry) => readRequiredString(entry) !== null)) {
             throw new Error('communicate.memberIds must contain at least one principal id');
         }
         return {
-            action: 'create_group',
-            name,
+            action: value.action,
+            ...(name ? { name } : {}),
             memberIds: [...new Set(value.memberIds)],
         };
     }
@@ -275,7 +287,7 @@ export function parseCommunicateToolInput(value) {
             ...(messageId ? { messageId } : {}),
         };
     }
-    if (value.action === 'manage_group_members') {
+    if (value.action === 'manage_group_members' || value.action === 'manage_participants') {
         if (!hasOnlyKeys(value, new Set([
             'action',
             'conversationId',
@@ -294,7 +306,7 @@ export function parseCommunicateToolInput(value) {
             throw new Error('communicate.operation must be add or remove');
         }
         return {
-            action: 'manage_group_members',
+            action: value.action,
             conversationId,
             userId,
             operation: value.operation,
@@ -323,7 +335,7 @@ export function parseCommunicateToolInput(value) {
             ...(messageId ? { messageId } : {}),
         };
     }
-    if (value.action === 'start_direct') {
+    if (value.action === 'start_direct' || value.action === 'start_conversation') {
         if (!hasOnlyKeys(value, new Set(['action', 'principalId', 'text', 'selection', 'messageId']))) {
             throw new Error('start_direct contains unsupported fields');
         }
@@ -331,10 +343,10 @@ export function parseCommunicateToolInput(value) {
         if (!principalId)
             throw new Error('communicate.principalId is required');
         const selection = value.selection === undefined
-            ? undefined
+            ? value.action === 'start_conversation' ? { mode: 'new' } : undefined
             : parseDirectConversationSelection(value.selection);
         return {
-            action: 'start_direct',
+            action: value.action,
             principalId,
             text,
             ...(selection ? { selection } : {}),

package/dist/verb-tools.js

@@ -39,9 +39,9 @@ const CANON_VERB_TOOL_DESCRIPTIONS = {
     share_contact: "Share a contact card into a conversation. The shared user must be in "
         + 'your contacts.',
     react: 'Toggle an emoji reaction on a Canon message.',
-    add_member: 'Add a member to a Canon group (policy approval and/or agent-owner setup may return a pending invite).',
-    remove_member: 'Remove a member from a Canon group (requires owner/admin role).',
-    leave_conversation: 'Leave a Canon group conversation.',
+    add_member: 'Add a participant to a Canon conversation (policy approval and/or agent-owner setup may return a pending invite).',
+    remove_member: 'Remove a participant from a Canon conversation (requires admin authority).',
+    leave_conversation: 'Leave a Canon conversation.',
     list_contacts: 'List your Canon contacts.',
     list_conversations: 'List your Canon conversations (optionally limited).',
     no_reply: 'End your turn without posting anything to the conversation. Use it in '

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@canonmsg/core": "^12.4.0",
+    "@canonmsg/core": "^12.5.0",
     "@canonmsg/rich-cards": "^0.10.5",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },