@canonmsg/agent-tools 0.5.2 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 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 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`.
 
 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/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_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';

package/dist/index.js

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

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

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,163 @@
+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 } : {}),
+            });
+        },
+    };
+}

package/dist/verb-mcp.d.ts

@@ -21,8 +21,18 @@
 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.
+     */
+    ownerBoundCommunication?: {
+        getContext: () => OwnerBoundCanonTurnContext | null | undefined;
+    };
+}
 export declare function createCanonVerbMcpServer(getClient: () => CanonClient | null, 
 /**
  * Lazy per-call execution context (host sessions are conversation-scoped:
@@ -37,4 +47,10 @@ 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;
+/**
+ * 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

@@ -21,6 +21,7 @@
 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';
 /** 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
@@ -48,12 +49,24 @@ onVerbCall) {
     // 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({
+    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(CallToolRequestSchema, async (request, extra) => {
         const client = getClient();
         if (!client) {
@@ -72,6 +85,24 @@ onVerbCall) {
         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 context = getContext?.();
         try {
@@ -92,3 +123,50 @@ onVerbCall) {
     });
     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

@@ -79,6 +79,18 @@ 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

@@ -51,8 +51,9 @@ 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_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, '
@@ -180,6 +181,34 @@ 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
@@ -260,6 +289,9 @@ 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
   "type": "module",
   "main": "dist/index.js",
@@ -40,9 +40,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@canonmsg/core": "^10.3.1",
-    "@canonmsg/rich-cards": "^0.10.0",
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@canonmsg/core": "^10.7.0",
+    "@canonmsg/rich-cards": "^0.10.2",
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",