@canonmsg/agent-tools 0.6.0 → 0.8.0

package/README.md

@@ -2,7 +2,13 @@
 
 Model-facing tool definitions for the canonical Canon verbs, plus the dispatch that executes them.
 
-This is the public tool surface of Canon's verb layer. All eighteen `canon.verbs.v1` verbs — `send_to`, `request_input`, `request_approval`, `check_approval`, `send_card`, `request_card`, `share_contact`, `react`, `forward`, `create_group`, `add_member`, `remove_member`, `leave_conversation`, `list_contacts`, `list_contact_requests`, `list_conversations`, `cancel_contact_request`, `no_reply` — are projected here as JSON-Schema tool definitions and dispatched over one endpoint: `POST /agent/verbs/:verb`.
+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, 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`. Everything dispatches through the canonical
+`POST /agent/verbs/:verb` endpoints.
 
 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.
 

package/dist/communication-tool.d.ts

@@ -0,0 +1,20 @@
+import { type CanonClient, type CommunicateInput } from '@canonmsg/core';
+import type { VerbToolDefinition, VerbToolResult } from './verb-tools.js';
+export declare const CANON_COMMUNICATE_TOOL_NAME = "communicate";
+/**
+ * The complete model-facing communication surface. It is exported separately
+ * from the in-conversation verb list so each runtime can opt into it.
+ */
+export declare function canonCommunicateToolDefinition(name?: string): VerbToolDefinition;
+/** Runtime validation mirrors the strict schema for bindings that dispatch directly. */
+export declare function parseCommunicateToolInput(value: unknown): CommunicateInput;
+export declare function executeCanonCommunicateTool(client: CanonClient, args: unknown): Promise<VerbToolResult>;
+export interface CanonCommunicationBinding {
+    tools: ReadonlyArray<VerbToolDefinition>;
+    isToolName(name: string): boolean;
+    execute(client: CanonClient, toolName: string, args: unknown): Promise<VerbToolResult>;
+}
+/** A one-tool binding that runtimes may mount without adding any other tools. */
+export declare function createCanonCommunicationBinding(options?: {
+    toolName?: string;
+}): CanonCommunicationBinding;

package/dist/communication-tool.js

@@ -0,0 +1,346 @@
+import { parseDirectConversationSelection, VERB_LIMITS, } from '@canonmsg/core';
+export const CANON_COMMUNICATE_TOOL_NAME = 'communicate';
+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 };
+const DIRECT_SELECTION_SCHEMA = {
+    oneOf: [
+        {
+            type: 'object',
+            required: ['mode'],
+            additionalProperties: false,
+            properties: { mode: { const: 'latest_or_new' } },
+        },
+        {
+            type: 'object',
+            required: ['mode'],
+            additionalProperties: false,
+            properties: { mode: { const: 'new' } },
+        },
+        {
+            type: 'object',
+            required: ['mode', 'conversationId'],
+            additionalProperties: false,
+            properties: {
+                mode: { const: 'specific' },
+                conversationId: NON_EMPTY_ID,
+            },
+        },
+    ],
+};
+/**
+ * The complete model-facing communication surface. It is exported separately
+ * from the in-conversation verb list so each runtime can opt into it.
+ */
+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, 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', 'conversationId', 'text'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'message_existing' },
+                        conversationId: NON_EMPTY_ID,
+                        text: MESSAGE_TEXT,
+                        messageId: NON_EMPTY_ID,
+                    },
+                },
+                {
+                    type: 'object',
+                    required: ['action', 'principalId', 'text'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'start_direct' },
+                        principalId: NON_EMPTY_ID,
+                        text: MESSAGE_TEXT,
+                        selection: DIRECT_SELECTION_SCHEMA,
+                        messageId: NON_EMPTY_ID,
+                    },
+                },
+                {
+                    type: 'object',
+                    required: ['action', 'name', 'memberIds'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'create_group' },
+                        name: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.groupNameChars },
+                        memberIds: {
+                            type: 'array',
+                            minItems: 1,
+                            maxItems: VERB_LIMITS.groupMembers - 1,
+                            uniqueItems: true,
+                            items: NON_EMPTY_ID,
+                        },
+                    },
+                },
+                {
+                    type: 'object',
+                    required: [
+                        'action',
+                        'sourceConversationId',
+                        'targetConversationId',
+                        'messageId',
+                    ],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'forward_message' },
+                        sourceConversationId: NON_EMPTY_ID,
+                        targetConversationId: NON_EMPTY_ID,
+                        messageId: NON_EMPTY_ID,
+                        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'] },
+                    },
+                },
+            ],
+        },
+    };
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function readRequiredString(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+function hasOnlyKeys(record, allowed) {
+    return Object.keys(record).every((key) => allowed.has(key));
+}
+/** Runtime validation mirrors the strict schema for bindings that dispatch directly. */
+export function parseCommunicateToolInput(value) {
+    if (!isRecord(value))
+        throw new Error('communicate arguments must be an object');
+    if (value.action === 'create_group') {
+        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');
+        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,
+            memberIds: [...new Set(value.memberIds)],
+        };
+    }
+    if (value.action === 'forward_message') {
+        if (!hasOnlyKeys(value, new Set([
+            'action',
+            'sourceConversationId',
+            'targetConversationId',
+            'messageId',
+            'text',
+        ]))) {
+            throw new Error('forward_message contains unsupported fields');
+        }
+        const sourceConversationId = readRequiredString(value.sourceConversationId);
+        const targetConversationId = readRequiredString(value.targetConversationId);
+        const messageId = readRequiredString(value.messageId);
+        if (!sourceConversationId)
+            throw new Error('communicate.sourceConversationId is required');
+        if (!targetConversationId)
+            throw new Error('communicate.targetConversationId is required');
+        if (!messageId)
+            throw new Error('communicate.messageId is required');
+        if (value.text !== undefined && typeof value.text !== 'string') {
+            throw new Error('communicate.text must be a string');
+        }
+        return {
+            action: 'forward_message',
+            sourceConversationId,
+            targetConversationId,
+            messageId,
+            ...(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
+        : readRequiredString(value.messageId);
+    if (!text)
+        throw new Error('communicate.text is required');
+    if (value.messageId !== undefined && !messageId) {
+        throw new Error('communicate.messageId must be a non-empty string');
+    }
+    if (value.action === 'message_existing') {
+        if (!hasOnlyKeys(value, new Set(['action', 'conversationId', 'text', 'messageId']))) {
+            throw new Error('message_existing contains unsupported fields');
+        }
+        const conversationId = readRequiredString(value.conversationId);
+        if (!conversationId)
+            throw new Error('communicate.conversationId is required');
+        return {
+            action: 'message_existing',
+            conversationId,
+            text,
+            ...(messageId ? { messageId } : {}),
+        };
+    }
+    if (value.action === 'start_direct') {
+        if (!hasOnlyKeys(value, new Set(['action', 'principalId', 'text', 'selection', 'messageId']))) {
+            throw new Error('start_direct contains unsupported fields');
+        }
+        const principalId = readRequiredString(value.principalId);
+        if (!principalId)
+            throw new Error('communicate.principalId is required');
+        const selection = value.selection === undefined
+            ? undefined
+            : parseDirectConversationSelection(value.selection);
+        return {
+            action: 'start_direct',
+            principalId,
+            text,
+            ...(selection ? { selection } : {}),
+            ...(messageId ? { messageId } : {}),
+        };
+    }
+    throw new Error('communicate.action is invalid');
+}
+function renderResult(result) {
+    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',
+                text: `communicate: ${result.status}${id ? ` (${id})` : ''}\n${JSON.stringify(result, null, 2)}`,
+            }],
+    };
+}
+export async function executeCanonCommunicateTool(client, args) {
+    let input;
+    try {
+        input = parseCommunicateToolInput(args);
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Invalid communicate arguments: ${error.message}`,
+                }],
+            isError: true,
+        };
+    }
+    return renderResult(await client.communicate(input));
+}
+/** A one-tool binding that runtimes may mount without adding any other tools. */
+export function createCanonCommunicationBinding(options = {}) {
+    const toolName = options.toolName?.trim() || CANON_COMMUNICATE_TOOL_NAME;
+    return {
+        tools: [canonCommunicateToolDefinition(toolName)],
+        isToolName: (name) => name === toolName,
+        execute: (client, name, args) => {
+            if (name !== toolName) {
+                return Promise.resolve({
+                    content: [{ type: 'text', text: `Unsupported Canon communication tool: ${name}` }],
+                    isError: true,
+                });
+            }
+            return executeCanonCommunicateTool(client, args);
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, stampSendToTurnComplete, type ExecuteVerbToolOptions, type VerbExecutionContext, type VerbProjectionOptions, type VerbToolDefinition, type VerbToolResult, } from './verb-tools.js';
-export { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer, createOwnerBoundCanonCommunicationMcpServer, type CanonVerbMcpServerOptions, } from './verb-mcp.js';
-export { OWNER_BOUND_CANON_COMMUNICATION_VERBS, createOwnerBoundCanonCommunicationBinding, type OwnerBoundCanonCommunicationBinding, type OwnerBoundCanonCommunicationToolNames, type OwnerBoundCanonCommunicationVerb, type OwnerBoundCanonContactTarget, type OwnerBoundCanonTurnContext, } from './owner-bound-communication.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';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, stampSendToTurnComplete, } from './verb-tools.js';
-export { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer, createOwnerBoundCanonCommunicationMcpServer, } from './verb-mcp.js';
-export { OWNER_BOUND_CANON_COMMUNICATION_VERBS, createOwnerBoundCanonCommunicationBinding, } from './owner-bound-communication.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';

package/dist/verb-mcp.d.ts

@@ -21,17 +21,14 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CanonClient, CanonVerbName } from '@canonmsg/core';
 import { type VerbExecutionContext } from './verb-tools.js';
-import { type OwnerBoundCanonTurnContext } from './owner-bound-communication.js';
 /** MCP server name — verbs appear to the model as `mcp__canon__<verb>`. */
 export declare const CANON_VERB_MCP_SERVER_NAME = "canon";
 export interface CanonVerbMcpServerOptions {
     /**
-     * Replace the five communication verbs with the strict owner-bound
-     * projection. Other canonical verbs retain their existing scoped behavior.
+     * Add the compact principal-neutral `communicate` tool. The broad `send_to`
+     * verb is never model-visible; all conversation-scoped verbs remain unchanged.
      */
-    ownerBoundCommunication?: {
-        getContext: () => OwnerBoundCanonTurnContext | null | undefined;
-    };
+    communication?: boolean;
 }
 export declare function createCanonVerbMcpServer(getClient: () => CanonClient | null, 
 /**
@@ -48,9 +45,3 @@ getContext?: () => VerbExecutionContext | undefined,
  * the model" rather than "silence never happens".
  */
 onVerbCall?: (verb: CanonVerbName, args: Record<string, unknown>, context: VerbExecutionContext | undefined) => void, options?: CanonVerbMcpServerOptions): McpServer;
-/**
- * In-process MCP projection for a foreground owner turn. Unlike the full
- * canonical server, this exposes only the admission-aware communication
- * surface and rejects calls when the host cannot prove owner/source context.
- */
-export declare function createOwnerBoundCanonCommunicationMcpServer(getClient: () => CanonClient | null, getContext: () => OwnerBoundCanonTurnContext | null | undefined, onVerbCall?: (verb: CanonVerbName, args: Record<string, unknown>) => void): McpServer;

package/dist/verb-mcp.js

@@ -20,8 +20,8 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, stampSendToTurnComplete, } from './verb-tools.js';
-import { OWNER_BOUND_CANON_COMMUNICATION_VERBS, createOwnerBoundCanonCommunicationBinding, } from './owner-bound-communication.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';
 export function createCanonVerbMcpServer(getClient, 
@@ -46,27 +46,21 @@ onVerbCall, options = {}) {
     // tool handlers).
     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.
-    const ownerBinding = options.ownerBoundCommunication
-        ? createOwnerBoundCanonCommunicationBinding()
-        : null;
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const canonical = canonVerbToolDefinitions({
-            interaction: 'waiting',
-            conversationScoped: Boolean(getContext),
-        });
-        if (!ownerBinding)
-            return { tools: canonical };
-        const ownerVerbs = new Set(OWNER_BOUND_CANON_COMMUNICATION_VERBS);
-        return {
-            tools: [
-                ...canonical.filter((definition) => !ownerVerbs.has(definition.name)),
-                ...ownerBinding.tools,
-            ],
-        };
-    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            ...canonVerbToolDefinitions({
+                interaction: 'waiting',
+                conversationScoped: Boolean(getContext),
+                compactCommunication,
+            }),
+            ...(options.communication ? communication.tools : []),
+        ],
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const client = getClient();
         if (!client) {
@@ -76,7 +70,15 @@ onVerbCall, options = {}) {
             };
         }
         const name = request.params.name;
-        if (!isCanonToolVerb(name)) {
+        if (options.communication && communication.isToolName(name)) {
+            const result = await communication.execute(client, name, request.params.arguments);
+            return {
+                content: result.content.map((item) => ({ type: 'text', text: item.text })),
+                ...(result.isError ? { isError: true } : {}),
+            };
+        }
+        if (!isCanonToolVerb(name)
+            || (compactCommunication && isCommunicateReplacedVerb(name))) {
             return {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                 isError: true,
@@ -85,25 +87,7 @@ onVerbCall, options = {}) {
         const rawArgs = request.params.arguments && typeof request.params.arguments === 'object'
             ? { ...request.params.arguments }
             : {};
-        if (ownerBinding && ownerBinding.verbForToolName(name)) {
-            try {
-                onVerbCall?.(name, rawArgs, getContext?.());
-            }
-            catch {
-                // A host bookkeeping bug must never break tool dispatch.
-            }
-            const result = await ownerBinding.execute({
-                client,
-                toolName: name,
-                arguments: rawArgs,
-                context: options.ownerBoundCommunication.getContext(),
-            });
-            return {
-                content: result.content.map((item) => ({ type: 'text', text: item.text })),
-                ...(result.isError ? { isError: true } : {}),
-            };
-        }
-        const verbArgs = name === 'send_to' ? stampSendToTurnComplete(rawArgs) : rawArgs;
+        const verbArgs = rawArgs;
         const context = getContext?.();
         try {
             onVerbCall?.(name, verbArgs, context);
@@ -123,50 +107,3 @@ onVerbCall, options = {}) {
     });
     return mcpServer;
 }
-/**
- * In-process MCP projection for a foreground owner turn. Unlike the full
- * canonical server, this exposes only the admission-aware communication
- * surface and rejects calls when the host cannot prove owner/source context.
- */
-export function createOwnerBoundCanonCommunicationMcpServer(getClient, getContext, onVerbCall) {
-    const binding = createOwnerBoundCanonCommunicationBinding();
-    const mcpServer = new McpServer({ name: CANON_VERB_MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
-    const server = mcpServer.server;
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: binding.tools }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const client = getClient();
-        if (!client) {
-            return {
-                content: [{ type: 'text', text: 'Canon not connected' }],
-                isError: true,
-            };
-        }
-        const verb = binding.verbForToolName(request.params.name);
-        if (!verb) {
-            return {
-                content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
-                isError: true,
-            };
-        }
-        const args = request.params.arguments && typeof request.params.arguments === 'object'
-            ? { ...request.params.arguments }
-            : {};
-        try {
-            onVerbCall?.(verb, args);
-        }
-        catch {
-            // Host bookkeeping cannot break dispatch.
-        }
-        const result = await binding.execute({
-            client,
-            toolName: request.params.name,
-            arguments: args,
-            context: getContext(),
-        });
-        return {
-            content: result.content.map((item) => ({ type: 'text', text: item.text })),
-            ...(result.isError ? { isError: true } : {}),
-        };
-    });
-    return mcpServer;
-}

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,17 +46,15 @@ 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[];
 export declare function isCanonToolVerb(name: string): name is CanonVerbName;
-/**
- * Outbound sends from a Claude surface are completed turns: stamp
- * turnSemantics 'turn_complete' into send_to messageOptions.metadata unless
- * the caller already set turn semantics. Shared by the channel server and
- * the host-mode MCP mount.
- */
-export declare function stampSendToTurnComplete(args: Record<string, unknown>): Record<string, unknown>;
 export interface VerbToolResult {
     content: Array<{
         type: 'text';
@@ -79,18 +80,6 @@ export interface VerbExecutionContext {
     responseUserId?: string;
     /** Canon message id of the inbound message that triggered this turn. */
     sourceMessageId?: string;
-    /**
-     * Trusted provenance for a host-bound send_to projection. When present,
-     * these fields replace any same-named model-authored values. Bindings that
-     * expose the full canonical schema simply omit it and retain existing
-     * unscoped send_to behavior.
-     */
-    sendTo?: {
-        sourceConversationId: string;
-        sourceMessageId?: string;
-        turnId?: string;
-        turnSemantics: 'turn_complete';
-    };
 }
 export interface ExecuteVerbToolOptions {
     /**

package/dist/verb-tools.js

@@ -28,10 +28,6 @@ import { findVerbByteLimitViolations, getVerbInputSchema, projectVerbIntentToWir
 import { RUNTIME_CARD_JSON_SCHEMA_V1 } from '@canonmsg/rich-cards';
 /** Verbs exposed to models, with binding-level descriptions. */
 const CANON_VERB_TOOL_DESCRIPTIONS = {
-    send_to: 'Send a Canon message to another conversation or user. Supports a private '
-        + 'selfContext note (with sourceConversationId) so you recognize your own '
-        + 'cross-conversation transfer later. Admission-aware for user targets: '
-        + 'may return requested/pending (contact request) instead of messaged.',
     request_input: 'Ask a human in a Canon conversation a structured question (input card).',
     request_approval: 'Ask a human to allow/deny an action via a Canon approval card. Use '
         + "mode 'detached' and poll with check_approval for long-lived approvals.",
@@ -43,17 +39,11 @@ 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.',
-    forward: 'Forward an existing Canon message into another conversation, with an optional caption.',
-    create_group: 'Create a Canon group conversation. Directly-addable members join at '
-        + 'creation; policy approval and agent-owner setup become pending invites '
-        + '(result.pending); hard-denied members are skipped (result.skipped).',
     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.',
     list_contacts: 'List your Canon contacts.',
-    list_contact_requests: 'List contact requests. Defaults to pending inbound; use outbound with includeResolved for reconnect recovery.',
     list_conversations: 'List your Canon conversations (optionally limited).',
-    cancel_contact_request: 'Cancel your own pending direct-message contact request.',
     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 '
         + 'other member or agent is triggered. Optional private reason (logged, '
@@ -80,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 = {
@@ -125,20 +131,6 @@ export function canonVerbToolDefinitions(options = {}) {
 export function isCanonToolVerb(name) {
     return CANON_TOOL_VERBS.includes(name);
 }
-/**
- * Outbound sends from a Claude surface are completed turns: stamp
- * turnSemantics 'turn_complete' into send_to messageOptions.metadata unless
- * the caller already set turn semantics. Shared by the channel server and
- * the host-mode MCP mount.
- */
-export function stampSendToTurnComplete(args) {
-    const options = { ...(args.messageOptions ?? {}) };
-    options.metadata = {
-        turnSemantics: 'turn_complete',
-        ...(options.metadata ?? {}),
-    };
-    return { ...args, messageOptions: options };
-}
 /** Verbs whose intents carry context-bound fields the binding must complete. */
 const INTERACTION_VERBS = new Set([
     'request_input',
@@ -181,34 +173,6 @@ const DEFAULT_INTERACTION_TIMEOUT_MS = 5 * 60 * 1000;
  * without a conversation.
  */
 export function normalizeVerbToolArgs(verb, args, context, now = Date.now()) {
-    if (verb === 'send_to' && context?.sendTo) {
-        const messageOptions = isRecord(args.messageOptions) ? { ...args.messageOptions } : {};
-        const metadata = isRecord(messageOptions.metadata) ? { ...messageOptions.metadata } : {};
-        // These names are host-owned on a bound projection. Delete first so an
-        // absent optional trusted value cannot leave a forged model value behind.
-        delete metadata.sourceConversationId;
-        delete metadata.sourceMessageId;
-        delete metadata.turnId;
-        delete metadata.turnSemantics;
-        return {
-            args: {
-                ...args,
-                sourceConversationId: context.sendTo.sourceConversationId,
-                messageOptions: {
-                    ...messageOptions,
-                    metadata: {
-                        ...metadata,
-                        sourceConversationId: context.sendTo.sourceConversationId,
-                        ...(context.sendTo.sourceMessageId
-                            ? { sourceMessageId: context.sendTo.sourceMessageId }
-                            : {}),
-                        ...(context.sendTo.turnId ? { turnId: context.sendTo.turnId } : {}),
-                        turnSemantics: context.sendTo.turnSemantics,
-                    },
-                },
-            },
-        };
-    }
     if (verb === 'no_reply') {
         const completed = { ...args };
         // messageId is binding-owned (like turnId on interaction verbs): the
@@ -289,9 +253,6 @@ export function normalizeVerbToolArgs(verb, args, context, now = Date.now()) {
     }
     return { args: completed };
 }
-function isRecord(value) {
-    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
-}
 const DEFAULT_POLL_MS = 1000;
 const DEFAULT_MAX_WAIT_MS = 30 * 60 * 1000;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -408,23 +369,6 @@ export async function executeCanonVerbTool(client, verb, args, options = {}) {
         return { content: [{ type: 'text', text: `Invalid arguments: ${normalized.error}` }], isError: true };
     }
     args = normalized.args;
-    // canonContactId is a contact-card identity, not a wire field: resolve it
-    // to a targetUserId here (the two-step the contract documents) so the
-    // advertised send_to schema is honest in every binding.
-    if (verb === 'send_to' && typeof args.canonContactId === 'string') {
-        const resolved = await client.resolveAdmission({ canonContactId: args.canonContactId });
-        if (!resolved.resolvedTargetUserId) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `send_to: unavailable\n${JSON.stringify({ status: 'unavailable', reason: 'canonContactId could not be resolved' }, null, 2)}`,
-                    }],
-                isError: true,
-            };
-        }
-        const { canonContactId: _resolved, ...rest } = args;
-        args = { ...rest, targetUserId: resolved.resolvedTargetUserId };
-    }
     const violations = findVerbByteLimitViolations(verb, args);
     if (violations.length > 0) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.6.0",
+  "version": "0.8.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": "^10.7.0",
-    "@canonmsg/rich-cards": "^0.10.2",
+    "@canonmsg/core": "^12.0.0",
+    "@canonmsg/rich-cards": "^0.10.4",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {

package/dist/owner-bound-communication.d.ts

@@ -1,36 +0,0 @@
-import type { CanonClient } from '@canonmsg/core';
-import { type VerbToolDefinition, type VerbToolResult } from './verb-tools.js';
-export declare const OWNER_BOUND_CANON_COMMUNICATION_VERBS: readonly ["send_to", "list_contacts", "list_contact_requests", "list_conversations", "cancel_contact_request"];
-export type OwnerBoundCanonCommunicationVerb = (typeof OWNER_BOUND_CANON_COMMUNICATION_VERBS)[number];
-export interface OwnerBoundCanonContactTarget {
-    targetUserId: string;
-    canonContactId?: string;
-    sourceCardMessageId?: string;
-}
-/** Trusted per-turn state supplied by a Canon host, never by the model. */
-export interface OwnerBoundCanonTurnContext {
-    isOwnerTurn: boolean;
-    conversationId: string;
-    sourceMessageId: string;
-    turnId?: string;
-    replyContactTarget?: OwnerBoundCanonContactTarget;
-}
-export type OwnerBoundCanonCommunicationToolNames = Record<OwnerBoundCanonCommunicationVerb, string>;
-export interface OwnerBoundCanonCommunicationBinding {
-    tools: ReadonlyArray<VerbToolDefinition>;
-    verbForToolName(toolName: string): OwnerBoundCanonCommunicationVerb | null;
-    execute(input: {
-        client: CanonClient;
-        toolName: string;
-        arguments: unknown;
-        context: OwnerBoundCanonTurnContext | null | undefined;
-    }): Promise<VerbToolResult>;
-}
-/**
- * Build the smallest owner-authorized Canon communication surface shared by
- * model hosts. The projection, name mapping, validation, target binding, and
- * trusted source injection live here so integrations cannot drift.
- */
-export declare function createOwnerBoundCanonCommunicationBinding(options?: {
-    toolNames?: Partial<OwnerBoundCanonCommunicationToolNames>;
-}): OwnerBoundCanonCommunicationBinding;

package/dist/owner-bound-communication.js

@@ -1,163 +0,0 @@
-import { canonVerbToolDefinitions, executeCanonVerbTool, } from './verb-tools.js';
-export const OWNER_BOUND_CANON_COMMUNICATION_VERBS = [
-    'send_to',
-    'list_contacts',
-    'list_contact_requests',
-    'list_conversations',
-    'cancel_contact_request',
-];
-const DEFAULT_TOOL_NAMES = {
-    send_to: 'send_to',
-    list_contacts: 'list_contacts',
-    list_contact_requests: 'list_contact_requests',
-    list_conversations: 'list_conversations',
-    cancel_contact_request: 'cancel_contact_request',
-};
-const CANONICAL_DEFINITIONS = new Map(canonVerbToolDefinitions().map((definition) => [definition.name, definition]));
-function isRecord(value) {
-    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
-}
-function readNonEmptyString(value) {
-    return typeof value === 'string' && value.trim() ? value.trim() : null;
-}
-function canonicalProperty(verb, property) {
-    const properties = CANONICAL_DEFINITIONS.get(verb)?.inputSchema.properties;
-    if (!isRecord(properties))
-        return {};
-    return isRecord(properties[property]) ? properties[property] : {};
-}
-function narrowSendToDefinition(name) {
-    const canonical = CANONICAL_DEFINITIONS.get('send_to');
-    return {
-        name,
-        description: `${canonical?.description ?? 'Send a Canon message.'} `
-            + 'This owner-bound projection accepts only one contact target and visible message text. '
-            + 'Canon supplies trusted source routing and may replace the target with the contact card '
-            + 'replied to by the owner. requested and pending are final results for this call; do not retry.',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-                targetUserId: {
-                    ...canonicalProperty('send_to', 'targetUserId'),
-                    description: 'Target Canon user id. Use exactly one target field.',
-                },
-                canonContactId: {
-                    ...canonicalProperty('send_to', 'canonContactId'),
-                    description: 'Stable id from a Canon contact card. Use exactly one target field.',
-                },
-                text: {
-                    ...canonicalProperty('send_to', 'text'),
-                    minLength: 1,
-                    description: 'Visible first message to the target.',
-                },
-                requestMessage: {
-                    ...canonicalProperty('send_to', 'requestMessage'),
-                    description: 'Optional note shown to the target human owner when approval is required.',
-                },
-            },
-            required: ['text'],
-            oneOf: [
-                { required: ['targetUserId'], not: { required: ['canonContactId'] } },
-                { required: ['canonContactId'], not: { required: ['targetUserId'] } },
-            ],
-        },
-    };
-}
-function parseNarrowSendToArguments(value, boundTarget) {
-    if (!isRecord(value))
-        return null;
-    const allowed = new Set(['targetUserId', 'canonContactId', 'text', 'requestMessage']);
-    if (Object.keys(value).some((key) => !allowed.has(key)))
-        return null;
-    const targetUserId = readNonEmptyString(value.targetUserId);
-    const canonContactId = readNonEmptyString(value.canonContactId);
-    const text = readNonEmptyString(value.text);
-    const requestMessage = readNonEmptyString(value.requestMessage);
-    if (!text || (!boundTarget && ((!targetUserId && !canonContactId) || (targetUserId && canonContactId)))) {
-        return null;
-    }
-    return {
-        ...(boundTarget?.canonContactId
-            ? { canonContactId: boundTarget.canonContactId }
-            : boundTarget
-                ? { targetUserId: boundTarget.targetUserId }
-                : targetUserId
-                    ? { targetUserId }
-                    : { canonContactId }),
-        text,
-        ...(requestMessage ? { requestMessage } : {}),
-    };
-}
-function invalidResult(message) {
-    return {
-        content: [{ type: 'text', text: message }],
-        isError: true,
-    };
-}
-/**
- * Build the smallest owner-authorized Canon communication surface shared by
- * model hosts. The projection, name mapping, validation, target binding, and
- * trusted source injection live here so integrations cannot drift.
- */
-export function createOwnerBoundCanonCommunicationBinding(options = {}) {
-    const toolNames = { ...DEFAULT_TOOL_NAMES, ...options.toolNames };
-    const verbByToolName = new Map();
-    for (const verb of OWNER_BOUND_CANON_COMMUNICATION_VERBS) {
-        const name = toolNames[verb];
-        if (!name || verbByToolName.has(name)) {
-            throw new Error(`Owner-bound Canon communication tool name is missing or duplicated: ${name}`);
-        }
-        verbByToolName.set(name, verb);
-    }
-    const tools = OWNER_BOUND_CANON_COMMUNICATION_VERBS.map((verb) => {
-        if (verb === 'send_to')
-            return narrowSendToDefinition(toolNames[verb]);
-        const canonical = CANONICAL_DEFINITIONS.get(verb);
-        if (!canonical)
-            throw new Error(`Missing canonical Canon verb definition: ${verb}`);
-        return {
-            ...canonical,
-            name: toolNames[verb],
-            description: verb === 'cancel_contact_request'
-                ? `${canonical.description} Only a pending outbound DM request can be cancelled.`
-                : canonical.description,
-        };
-    });
-    return {
-        tools,
-        verbForToolName: (toolName) => verbByToolName.get(toolName) ?? null,
-        execute: async ({ client, toolName, arguments: rawArguments, context }) => {
-            const verb = verbByToolName.get(toolName);
-            if (!verb)
-                return invalidResult(`Unsupported Canon communication tool: ${toolName}`);
-            if (!context?.isOwnerTurn) {
-                return invalidResult('Canon communication tools require an owner-authored foreground turn.');
-            }
-            if (!context.conversationId || !context.sourceMessageId) {
-                return invalidResult('Canon communication tools require trusted source conversation and message context.');
-            }
-            if (!isRecord(rawArguments))
-                return invalidResult(`Invalid ${verb} arguments.`);
-            let args = { ...rawArguments };
-            let executionContext;
-            if (verb === 'send_to') {
-                const parsed = parseNarrowSendToArguments(rawArguments, context.replyContactTarget);
-                if (!parsed)
-                    return invalidResult('Invalid send_to arguments.');
-                args = parsed;
-                executionContext = {
-                    sendTo: {
-                        sourceConversationId: context.conversationId,
-                        sourceMessageId: context.sourceMessageId,
-                        ...(context.turnId ? { turnId: context.turnId } : {}),
-                        turnSemantics: 'turn_complete',
-                    },
-                };
-            }
-            return executeCanonVerbTool(client, verb, args, {
-                ...(executionContext ? { context: executionContext } : {}),
-            });
-        },
-    };
-}