@canonmsg/agent-tools 0.3.4 → 0.5.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 sixteen `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` — 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 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`.
 
 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.
 
@@ -34,7 +34,7 @@ const result = await executeCanonVerbTool(client, 'send_to', {
 
 A bare `CanonClient` targets production; pass a base URL from `resolveCanonRuntimeConnection({ environmentId: 'canon-dev-v1' })` to point at dev.
 
-For an MCP mount, `createCanonVerbMcpServer(getClient, getContext?)` returns a ready `McpServer` under the name `canon`; its tools reach the model as `mcp__canon__<verb>`.
+For an MCP mount, `createCanonVerbMcpServer(getClient, getContext?, onVerbCall?)` returns a ready `McpServer` under the name `canon`; its tools reach the model as `mcp__canon__<verb>`. `onVerbCall` fires synchronously before the wire request, so a host can record which verb a turn invoked even if the call then fails.
 
 ## Notes
 

package/dist/verb-mcp.d.ts

@@ -19,7 +19,7 @@
  * Detached approvals still return pending immediately.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { CanonClient } from '@canonmsg/core';
+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";
@@ -29,4 +29,12 @@ export declare function createCanonVerbMcpServer(getClient: () => CanonClient |
  * active conversation, current turn, turn responder). Read at call time —
  * the session object outlives any single turn.
  */
-getContext?: () => VerbExecutionContext | undefined): McpServer;
+getContext?: () => VerbExecutionContext | undefined, 
+/**
+ * Observation seam: the only place a host learns that a verb tool actually
+ * executed (canUseTool fires before dispatch and can still be denied). It
+ * runs BEFORE the POST on purpose — a host flag set here survives an
+ * 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;

package/dist/verb-mcp.js

@@ -29,7 +29,15 @@ export function createCanonVerbMcpServer(getClient,
  * active conversation, current turn, turn responder). Read at call time —
  * the session object outlives any single turn.
  */
-getContext) {
+getContext, 
+/**
+ * Observation seam: the only place a host learns that a verb tool actually
+ * executed (canUseTool fires before dispatch and can still be denied). It
+ * runs BEFORE the POST on purpose — a host flag set here survives an
+ * un-deployed server, so `no_reply` degrades to "silent turn, error shown to
+ * the model" rather than "silence never happens".
+ */
+onVerbCall) {
     // 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
@@ -66,6 +74,12 @@ getContext) {
             : {};
         const verbArgs = name === 'send_to' ? stampSendToTurnComplete(rawArgs) : rawArgs;
         const context = getContext?.();
+        try {
+            onVerbCall?.(name, verbArgs, context);
+        }
+        catch {
+            // A host bookkeeping bug must never break tool dispatch.
+        }
         const result = await executeCanonVerbTool(client, name, verbArgs, {
             waitForResult: true,
             signal: extra?.signal,

package/dist/verb-tools.d.ts

@@ -77,6 +77,8 @@ export interface VerbExecutionContext {
     turnId?: string;
     /** Default responder (e.g. the author of the turn being served). */
     responseUserId?: string;
+    /** Canon message id of the inbound message that triggered this turn. */
+    sourceMessageId?: string;
 }
 export interface ExecuteVerbToolOptions {
     /**

package/dist/verb-tools.js

@@ -53,6 +53,10 @@ const CANON_VERB_TOOL_DESCRIPTIONS = {
     list_contacts: 'List your Canon contacts.',
     list_contact_requests: 'List pending inbound contact requests (read-only awareness).',
     list_conversations: 'List your Canon conversations (optionally limited).',
+    no_reply: 'End your turn without posting anything to the conversation. Use it in '
+        + 'groups when you have nothing to add — no message is created, so no '
+        + 'other member or agent is triggered. Optional private reason (logged, '
+        + 'never shown). After calling this, produce no further text.',
 };
 /**
  * Posture-specific completion sentences for the blocking interactive verbs.
@@ -90,6 +94,15 @@ export function canonVerbToolDefinitions(options = {}) {
                 delete properties[field];
             inputSchema = { ...inputSchema, properties };
         }
+        if (verb === 'no_reply') {
+            // Binding-owned like turnId: injected from turn context, never asked
+            // of the model — a guessed id is worse than none.
+            const properties = {
+                ...(inputSchema.properties ?? {}),
+            };
+            delete properties.messageId;
+            inputSchema = { ...inputSchema, properties };
+        }
         // The contract marks conversationId optional because bindings default it
         // to the active conversation — a projection without one must require it
         // from the model instead. Context-bound fields are either injected by
@@ -167,6 +180,25 @@ const DEFAULT_INTERACTION_TIMEOUT_MS = 5 * 60 * 1000;
  * without a conversation.
  */
 export function normalizeVerbToolArgs(verb, args, context, now = Date.now()) {
+    if (verb === 'no_reply') {
+        const completed = { ...args };
+        // messageId is binding-owned (like turnId on interaction verbs): the
+        // model never knows the triggering id more reliably than the binding,
+        // and a wrong id misattributes the silence record.
+        delete completed.messageId;
+        if (typeof context?.sourceMessageId === 'string' && context.sourceMessageId) {
+            completed.messageId = context.sourceMessageId;
+        }
+        // Silence carries a conversation for the server's durable silence marker
+        // (/runtime-silence/{convoId}/{agentId}), so it defaults like an
+        // interaction verb but never FAILS without one — a turn can decline to
+        // reply from a binding that has no active conversation.
+        if ((typeof completed.conversationId !== 'string' || !completed.conversationId)
+            && typeof context?.conversationId === 'string' && context.conversationId) {
+            completed.conversationId = context.conversationId;
+        }
+        return { args: completed };
+    }
     if (!INTERACTION_VERBS.has(verb))
         return { args };
     const completed = { ...args };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.3.4",
+  "version": "0.5.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": "^9.1.0",
-    "@canonmsg/rich-cards": "^0.9.0",
+    "@canonmsg/core": "^10.2.0",
+    "@canonmsg/rich-cards": "^0.9.1",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {