@canonmsg/agent-tools 0.3.4 → 0.4.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.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.
@@ -167,6 +171,17 @@ const DEFAULT_INTERACTION_TIMEOUT_MS = 5 * 60 * 1000;
  * without a conversation.
  */
 export function normalizeVerbToolArgs(verb, args, context, now = Date.now()) {
+    if (verb === 'no_reply') {
+        // Silence carries a conversation for the server's audit line only, 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 args.conversationId === 'string' && args.conversationId)
+            return { args };
+        if (typeof context?.conversationId === 'string' && context.conversationId) {
+            return { args: { ...args, conversationId: context.conversationId } };
+        }
+        return { args };
+    }
     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.4.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.0.0",
+    "@canonmsg/rich-cards": "^0.9.1",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {