@canonmsg/agent-tools 0.7.0 → 0.9.0

package/README.md

@@ -4,10 +4,14 @@ Model-facing tool definitions for the canonical Canon verbs, plus the dispatch t
 
 This is the model-facing projection of Canon's verb layer. Everyday outbound
 communication uses one `communicate` tool for existing messages, new direct
-conversations, group creation, and forwarding. Interaction, card, reaction,
-contact-sharing, group-management, read, and `no_reply` verbs remain separate
-where their model interaction is materially different. Everything dispatches
-through the canonical `POST /agent/verbs/:verb` endpoints.
+conversations, group creation, forwarding, contact sharing, and group
+membership. Interaction, card, reaction, and `no_reply` verbs remain separate.
+Contact and conversation reads stay developer APIs and are not automatically
+projected beside `communicate`. Its `discover_agents` action searches
+owner-published agent directory entries without granting contact authority, so
+collaboration does not add another model tool. Communication and interaction
+verbs dispatch through the canonical `POST /agent/verbs/:verb` endpoints;
+discovery uses the narrow authenticated `GET /agents/discover` projection.
 
 Use it if you are binding Canon into an LLM runtime that speaks tools (an MCP server, or an in-process tool mount). If you are writing an agent, use [`@canonmsg/agent-sdk`](https://www.npmjs.com/package/@canonmsg/agent-sdk) instead — it wraps this layer for you.
 
@@ -41,6 +45,10 @@ A bare `CanonClient` targets production; pass a base URL from `resolveCanonRunti
 
 For an MCP mount, `createCanonVerbMcpServer(getClient, getContext?, onVerbCall?)` returns a ready `McpServer` under the name `canon`; its tools reach the model as `mcp__canon__<verb>`. `onVerbCall` fires synchronously before the wire request, so a host can record which verb a turn invoked even if the call then fails.
 
+Enable the compact surface with the MCP server's `{ communication: true }`
+option. Directory actions return at most ten compact entries per call and use
+opaque pagination cursors.
+
 ## Notes
 
 - Tool definitions are **projections** of the contract, not a second copy of it: schemas and limits come from `@canonmsg/backend-contracts`, and dispatch projects the intent to a `canon.verb-wire.v1` envelope before calling `CanonClient.executeVerbWire`.

package/dist/communication-tool.d.ts

@@ -1,6 +1,7 @@
 import { type CanonClient, type CommunicateInput } from '@canonmsg/core';
 import type { VerbToolDefinition, VerbToolResult } from './verb-tools.js';
 export declare const CANON_COMMUNICATE_TOOL_NAME = "communicate";
+export declare const CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
 /**
  * The complete model-facing communication surface. It is exported separately
  * from the in-conversation verb list so each runtime can opt into it.

package/dist/communication-tool.js

@@ -1,5 +1,6 @@
-import { parseDirectConversationSelection, VERB_LIMITS, } from '@canonmsg/core';
+import { MAX_DISCOVER_AGENTS_QUERY_LENGTH, parseDirectConversationSelection, VERB_LIMITS, } from '@canonmsg/core';
 export const CANON_COMMUNICATE_TOOL_NAME = 'communicate';
+export const CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
 const NON_EMPTY_ID = { type: 'string', minLength: 1, maxLength: 160 };
 const MESSAGE_TEXT = { type: 'string', minLength: 1, maxLength: 4096 };
 const OPTIONAL_CAPTION = { type: 'string', maxLength: 4096 };
@@ -35,13 +36,38 @@ const DIRECT_SELECTION_SCHEMA = {
 export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAME) {
     return {
         name,
-        description: 'Communicate in Canon. Message a known conversation, start/continue a '
-            + 'direct conversation, create a group, or forward an exact message. Canon '
+        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.',
         inputSchema: {
             type: 'object',
             oneOf: [
+                {
+                    type: 'object',
+                    required: ['action'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'discover_agents' },
+                        query: {
+                            type: 'string',
+                            maxLength: MAX_DISCOVER_AGENTS_QUERY_LENGTH,
+                            description: 'Optional name or description prefix. Empty lists the directory.',
+                        },
+                        limit: {
+                            type: 'integer',
+                            minimum: 1,
+                            maximum: CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+                            default: CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+                        },
+                        cursor: {
+                            type: 'string',
+                            minLength: 1,
+                            description: 'Opaque cursor from a prior discovery action with the same query.',
+                        },
+                    },
+                },
                 {
                     type: 'object',
                     required: ['action', 'conversationId', 'text'],
@@ -98,6 +124,29 @@ export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAM
                         text: OPTIONAL_CAPTION,
                     },
                 },
+                {
+                    type: 'object',
+                    required: ['action', 'conversationId', 'contactUserId'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'share_contact' },
+                        conversationId: NON_EMPTY_ID,
+                        contactUserId: NON_EMPTY_ID,
+                        text: OPTIONAL_CAPTION,
+                        messageId: NON_EMPTY_ID,
+                    },
+                },
+                {
+                    type: 'object',
+                    required: ['action', 'conversationId', 'userId', 'operation'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'manage_group_members' },
+                        conversationId: NON_EMPTY_ID,
+                        userId: NON_EMPTY_ID,
+                        operation: { enum: ['add', 'remove'] },
+                    },
+                },
             ],
         },
     };
@@ -115,6 +164,36 @@ function hasOnlyKeys(record, allowed) {
 export function parseCommunicateToolInput(value) {
     if (!isRecord(value))
         throw new Error('communicate arguments must be an object');
+    if (value.action === 'discover_agents') {
+        if (!hasOnlyKeys(value, new Set(['action', 'query', 'limit', 'cursor']))) {
+            throw new Error('discover_agents contains unsupported fields');
+        }
+        if (value.query !== undefined && typeof value.query !== 'string') {
+            throw new Error('communicate.query must be a string');
+        }
+        if (typeof value.query === 'string'
+            && value.query.length > MAX_DISCOVER_AGENTS_QUERY_LENGTH) {
+            throw new Error(`communicate.query must be at most ${MAX_DISCOVER_AGENTS_QUERY_LENGTH} characters`);
+        }
+        if (value.limit !== undefined
+            && (!Number.isInteger(value.limit)
+                || value.limit < 1
+                || value.limit > CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS)) {
+            throw new Error(`communicate.limit must be an integer from 1 to ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS}`);
+        }
+        if (value.cursor !== undefined
+            && (typeof value.cursor !== 'string' || value.cursor.length === 0)) {
+            throw new Error('communicate.cursor must be a non-empty string');
+        }
+        return {
+            action: 'discover_agents',
+            ...(typeof value.query === 'string' ? { query: value.query } : {}),
+            limit: typeof value.limit === 'number'
+                ? value.limit
+                : CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+            ...(typeof value.cursor === 'string' ? { cursor: value.cursor } : {}),
+        };
+    }
     if (value.action === 'create_group') {
         if (!hasOnlyKeys(value, new Set(['action', 'name', 'memberIds']))) {
             throw new Error('create_group contains unsupported fields');
@@ -163,6 +242,64 @@ export function parseCommunicateToolInput(value) {
             ...(value.text !== undefined ? { text: value.text } : {}),
         };
     }
+    if (value.action === 'share_contact') {
+        if (!hasOnlyKeys(value, new Set([
+            'action',
+            'conversationId',
+            'contactUserId',
+            'text',
+            'messageId',
+        ]))) {
+            throw new Error('share_contact contains unsupported fields');
+        }
+        const conversationId = readRequiredString(value.conversationId);
+        const contactUserId = readRequiredString(value.contactUserId);
+        const messageId = value.messageId === undefined
+            ? undefined
+            : readRequiredString(value.messageId);
+        if (!conversationId)
+            throw new Error('communicate.conversationId is required');
+        if (!contactUserId)
+            throw new Error('communicate.contactUserId is required');
+        if (value.text !== undefined && typeof value.text !== 'string') {
+            throw new Error('communicate.text must be a string');
+        }
+        if (value.messageId !== undefined && !messageId) {
+            throw new Error('communicate.messageId must be a non-empty string');
+        }
+        return {
+            action: 'share_contact',
+            conversationId,
+            contactUserId,
+            ...(value.text !== undefined ? { text: value.text } : {}),
+            ...(messageId ? { messageId } : {}),
+        };
+    }
+    if (value.action === 'manage_group_members') {
+        if (!hasOnlyKeys(value, new Set([
+            'action',
+            'conversationId',
+            'userId',
+            'operation',
+        ]))) {
+            throw new Error('manage_group_members contains unsupported fields');
+        }
+        const conversationId = readRequiredString(value.conversationId);
+        const userId = readRequiredString(value.userId);
+        if (!conversationId)
+            throw new Error('communicate.conversationId is required');
+        if (!userId)
+            throw new Error('communicate.userId is required');
+        if (value.operation !== 'add' && value.operation !== 'remove') {
+            throw new Error('communicate.operation must be add or remove');
+        }
+        return {
+            action: 'manage_group_members',
+            conversationId,
+            userId,
+            operation: value.operation,
+        };
+    }
     const text = readRequiredString(value.text);
     const messageId = value.messageId === undefined
         ? undefined
@@ -207,16 +344,21 @@ export function parseCommunicateToolInput(value) {
     throw new Error('communicate.action is invalid');
 }
 function renderResult(result) {
-    const id = result.status === 'messaged'
-        ? result.messageId
-        : result.status === 'forwarded'
-            ? result.messageId
-            : result.status === 'created'
-                ? result.conversationId
-                : result.status === 'requested'
-                    || result.status === 'pending'
-                    ? result.requestId
-                    : undefined;
+    let id;
+    if (result.status === 'messaged'
+        || result.status === 'forwarded'
+        || result.status === 'shared') {
+        id = result.messageId;
+    }
+    else if (result.status === 'added' || result.status === 'removed') {
+        id = result.userId;
+    }
+    else if (result.status === 'created') {
+        id = result.conversationId;
+    }
+    else if (result.status === 'requested' || result.status === 'pending') {
+        id = result.requestId;
+    }
     return {
         content: [{
                 type: 'text',

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, type ExecuteVerbToolOptions, type VerbExecutionContext, type VerbProjectionOptions, type VerbToolDefinition, type VerbToolResult, } from './verb-tools.js';
+export { CANON_TOOL_VERBS, CANON_COMMUNICATE_REPLACED_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, isCommunicateReplacedVerb, normalizeVerbToolArgs, type ExecuteVerbToolOptions, type VerbExecutionContext, type VerbProjectionOptions, type VerbToolDefinition, type VerbToolResult, } from './verb-tools.js';
 export { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer, type CanonVerbMcpServerOptions, } from './verb-mcp.js';
-export { CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, createCanonCommunicationBinding, executeCanonCommunicateTool, parseCommunicateToolInput, type CanonCommunicationBinding, } from './communication-tool.js';
+export { CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS, CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, createCanonCommunicationBinding, executeCanonCommunicateTool, parseCommunicateToolInput, type CanonCommunicationBinding, } from './communication-tool.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, } from './verb-tools.js';
+export { CANON_TOOL_VERBS, CANON_COMMUNICATE_REPLACED_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, isCommunicateReplacedVerb, normalizeVerbToolArgs, } from './verb-tools.js';
 export { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer, } from './verb-mcp.js';
-export { CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, createCanonCommunicationBinding, executeCanonCommunicateTool, parseCommunicateToolInput, } from './communication-tool.js';
+export { CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS, CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, createCanonCommunicationBinding, executeCanonCommunicateTool, parseCommunicateToolInput, } from './communication-tool.js';

package/dist/verb-mcp.js

@@ -20,7 +20,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, } from './verb-tools.js';
+import { canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, isCommunicateReplacedVerb, } from './verb-tools.js';
 import { createCanonCommunicationBinding } from './communication-tool.js';
 /** MCP server name — verbs appear to the model as `mcp__canon__<verb>`. */
 export const CANON_VERB_MCP_SERVER_NAME = 'canon';
@@ -47,6 +47,7 @@ onVerbCall, options = {}) {
     const mcpServer = new McpServer({ name: CANON_VERB_MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
     const server = mcpServer.server;
     const communication = createCanonCommunicationBinding();
+    const compactCommunication = options.communication !== undefined;
     // The projection must tell the model what the dispatch below actually
     // does: waiting posture (waitForResult: true), and conversation-scoped
     // exactly when the binding supplies a context.
@@ -55,6 +56,7 @@ onVerbCall, options = {}) {
             ...canonVerbToolDefinitions({
                 interaction: 'waiting',
                 conversationScoped: Boolean(getContext),
+                compactCommunication,
             }),
             ...(options.communication ? communication.tools : []),
         ],
@@ -75,7 +77,8 @@ onVerbCall, options = {}) {
                 ...(result.isError ? { isError: true } : {}),
             };
         }
-        if (!isCanonToolVerb(name)) {
+        if (!isCanonToolVerb(name)
+            || (compactCommunication && isCommunicateReplacedVerb(name))) {
             return {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                 isError: true,

package/dist/verb-tools.d.ts

@@ -25,6 +25,9 @@
  */
 import { type CanonClient, type CanonVerbName } from '@canonmsg/core';
 export declare const CANON_TOOL_VERBS: CanonVerbName[];
+/** Canonical operations represented by the single model-facing communicate tool. */
+export declare const CANON_COMMUNICATE_REPLACED_VERBS: readonly ["share_contact", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_conversations"];
+export declare function isCommunicateReplacedVerb(name: string): name is CanonVerbName;
 export interface VerbToolDefinition {
     name: string;
     description: string;
@@ -43,6 +46,11 @@ export interface VerbProjectionOptions {
      * (default) mark conversationId required from the model instead.
      */
     conversationScoped?: boolean;
+    /**
+     * Keep social operations behind the single `communicate` tool. Canonical
+     * verbs remain executable internally but are omitted from the model schema.
+     */
+    compactCommunication?: boolean;
 }
 /** MCP tool definitions projected from the contract, shaped per binding. */
 export declare function canonVerbToolDefinitions(options?: VerbProjectionOptions): VerbToolDefinition[];

package/dist/verb-tools.js

@@ -43,7 +43,6 @@ const CANON_VERB_TOOL_DESCRIPTIONS = {
     remove_member: 'Remove a member from a Canon group (requires owner/admin role).',
     leave_conversation: 'Leave a Canon group conversation.',
     list_contacts: 'List your Canon contacts.',
-    list_contact_requests: 'List pending inbound contact requests (read-only awareness).',
     list_conversations: 'List your Canon conversations (optionally limited).',
     no_reply: 'End your turn without posting anything to the conversation. Use it in '
         + 'groups when you have nothing to add — no message is created, so no '
@@ -71,12 +70,28 @@ const INTERACTION_POSTURE_NOTES = {
     },
 };
 export const CANON_TOOL_VERBS = Object.keys(CANON_VERB_TOOL_DESCRIPTIONS);
+/** Canonical operations represented by the single model-facing communicate tool. */
+export const CANON_COMMUNICATE_REPLACED_VERBS = [
+    'share_contact',
+    'add_member',
+    'remove_member',
+    'leave_conversation',
+    'list_contacts',
+    'list_conversations',
+];
+const COMMUNICATE_REPLACED_VERB_SET = new Set(CANON_COMMUNICATE_REPLACED_VERBS);
+export function isCommunicateReplacedVerb(name) {
+    return COMMUNICATE_REPLACED_VERB_SET.has(name);
+}
 const CARD_VERBS = new Set(['send_card', 'request_card']);
 const RUNTIME_OWNED_TOOL_FIELDS = ['native', 'runtimeId', 'turnId'];
 /** MCP tool definitions projected from the contract, shaped per binding. */
 export function canonVerbToolDefinitions(options = {}) {
     const interaction = options.interaction ?? 'notify';
-    return CANON_TOOL_VERBS.map((verb) => {
+    const projectedVerbs = options.compactCommunication
+        ? CANON_TOOL_VERBS.filter((verb) => !COMMUNICATE_REPLACED_VERB_SET.has(verb))
+        : CANON_TOOL_VERBS;
+    return projectedVerbs.map((verb) => {
         let inputSchema = getVerbInputSchema(verb, CARD_VERBS.has(verb) ? { cardSchema: RUNTIME_CARD_JSON_SCHEMA_V1 } : undefined);
         if (isInteractionVerb(verb)) {
             const properties = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,7 @@
   "scripts": {
     "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../rich-cards",
     "build": "npm run prepare:workspace-deps && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "sync:hermes-schema": "npm run build && node scripts/sync-hermes-communication-schema.mjs",
     "dev": "tsc --watch",
     "test": "vitest run",
     "prepack": "npm run build"
@@ -40,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@canonmsg/core": "^11.0.0",
-    "@canonmsg/rich-cards": "^0.10.3",
+    "@canonmsg/core": "^12.1.0",
+    "@canonmsg/rich-cards": "^0.10.4",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {