@canonmsg/agent-tools 0.5.3 → 0.7.0

package/README.md

@@ -2,7 +2,12 @@
 
 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 seventeen `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`, `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, 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.
 
 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,259 @@
+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, or forward an exact message. 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,
+                    },
+                },
+            ],
+        },
+    };
+}
+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 } : {}),
+        };
+    }
+    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) {
+    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;
+    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,2 +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, } from './verb-mcp.js';
+export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, 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,2 +1,3 @@
-export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, stampSendToTurnComplete, } from './verb-tools.js';
+export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, 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

@@ -23,6 +23,13 @@ import type { CanonClient, CanonVerbName } from '@canonmsg/core';
 import { type VerbExecutionContext } from './verb-tools.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 {
+    /**
+     * Add the compact principal-neutral `communicate` tool. The broad `send_to`
+     * verb is never model-visible; all conversation-scoped verbs remain unchanged.
+     */
+    communication?: boolean;
+}
 export declare function createCanonVerbMcpServer(getClient: () => CanonClient | null, 
 /**
  * Lazy per-call execution context (host sessions are conversation-scoped:
@@ -37,4 +44,4 @@ getContext?: () => VerbExecutionContext | undefined,
  * un-deployed server, so `no_reply` degrades to "silent turn, error shown to
  * the model" rather than "silence never happens".
  */
-onVerbCall?: (verb: CanonVerbName, args: Record<string, unknown>, context: VerbExecutionContext | undefined) => void): McpServer;
+onVerbCall?: (verb: CanonVerbName, args: Record<string, unknown>, context: VerbExecutionContext | undefined) => void, options?: CanonVerbMcpServerOptions): McpServer;

package/dist/verb-mcp.js

@@ -20,7 +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 { canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, } 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, 
@@ -37,7 +38,7 @@ getContext,
  * un-deployed server, so `no_reply` degrades to "silent turn, error shown to
  * the model" rather than "silence never happens".
  */
-onVerbCall) {
+onVerbCall, options = {}) {
     // The Agent SDK's mcpServers option expects the high-level McpServer class,
     // but its registerTool API wants Zod shapes — so the contract's JSON-Schema
     // projections are installed directly on the underlying protocol server
@@ -45,14 +46,18 @@ onVerbCall) {
     // 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();
     // 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.
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: canonVerbToolDefinitions({
-            interaction: 'waiting',
-            conversationScoped: Boolean(getContext),
-        }),
+        tools: [
+            ...canonVerbToolDefinitions({
+                interaction: 'waiting',
+                conversationScoped: Boolean(getContext),
+            }),
+            ...(options.communication ? communication.tools : []),
+        ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const client = getClient();
@@ -63,6 +68,13 @@ onVerbCall) {
             };
         }
         const name = request.params.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)) {
             return {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
@@ -72,7 +84,7 @@ onVerbCall) {
         const rawArgs = request.params.arguments && typeof request.params.arguments === 'object'
             ? { ...request.params.arguments }
             : {};
-        const verbArgs = name === 'send_to' ? stampSendToTurnComplete(rawArgs) : rawArgs;
+        const verbArgs = rawArgs;
         const context = getContext?.();
         try {
             onVerbCall?.(name, verbArgs, context);

package/dist/verb-tools.d.ts

@@ -47,13 +47,6 @@ export interface VerbProjectionOptions {
 /** 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';

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,10 +39,6 @@ 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.',
@@ -124,20 +116,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',
@@ -376,23 +354,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.5.3",
+  "version": "0.7.0",
   "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
   "type": "module",
   "main": "dist/index.js",
@@ -40,8 +40,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@canonmsg/core": "^10.4.0",
-    "@canonmsg/rich-cards": "^0.10.2",
+    "@canonmsg/core": "^11.0.0",
+    "@canonmsg/rich-cards": "^0.10.3",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {