@canonmsg/agent-tools 0.8.0 → 0.9.1

package/README.md

@@ -7,8 +7,11 @@ 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.
+projected beside `communicate`. Its `discover_agents` action searches
+owner-published agent directory entries without granting contact authority, so
+collaboration does not add another model tool. Communication and interaction
+verbs dispatch through the canonical `POST /agent/verbs/:verb` endpoints;
+discovery uses the narrow authenticated `GET /agents/discover` projection.
 
 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.
 
@@ -42,6 +45,10 @@ A bare `CanonClient` targets production; pass a base URL from `resolveCanonRunti
 
 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.
 
+Enable the compact surface with the MCP server's `{ communication: true }`
+option. Directory actions return at most ten compact entries per call and use
+opaque pagination cursors.
+
 ## Notes
 
 - Tool definitions are **projections** of the contract, not a second copy of it: schemas and limits come from `@canonmsg/backend-contracts`, and dispatch projects the intent to a `canon.verb-wire.v1` envelope before calling `CanonClient.executeVerbWire`.

package/dist/communication-tool.d.ts

@@ -1,6 +1,7 @@
 import { type CanonClient, type CommunicateInput } from '@canonmsg/core';
 import type { VerbToolDefinition, VerbToolResult } from './verb-tools.js';
 export declare const CANON_COMMUNICATE_TOOL_NAME = "communicate";
+export declare const CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
 /**
  * The complete model-facing communication surface. It is exported separately
  * from the in-conversation verb list so each runtime can opt into it.

package/dist/communication-tool.js

@@ -1,5 +1,6 @@
-import { parseDirectConversationSelection, VERB_LIMITS, } from '@canonmsg/core';
+import { MAX_DISCOVER_AGENTS_QUERY_LENGTH, parseDirectConversationSelection, VERB_LIMITS, } from '@canonmsg/core';
 export const CANON_COMMUNICATE_TOOL_NAME = 'communicate';
+export const CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
 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 };
@@ -35,7 +36,7 @@ const DIRECT_SELECTION_SCHEMA = {
 export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAME) {
     return {
         name,
-        description: 'Communicate in Canon. Message a known conversation, start/continue a '
+        description: 'Find discoverable agents or 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 '
@@ -43,6 +44,30 @@ export function canonCommunicateToolDefinition(name = CANON_COMMUNICATE_TOOL_NAM
         inputSchema: {
             type: 'object',
             oneOf: [
+                {
+                    type: 'object',
+                    required: ['action'],
+                    additionalProperties: false,
+                    properties: {
+                        action: { const: 'discover_agents' },
+                        query: {
+                            type: 'string',
+                            maxLength: MAX_DISCOVER_AGENTS_QUERY_LENGTH,
+                            description: 'Optional name or description prefix. Empty lists the directory.',
+                        },
+                        limit: {
+                            type: 'integer',
+                            minimum: 1,
+                            maximum: CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+                            default: CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+                        },
+                        cursor: {
+                            type: 'string',
+                            minLength: 1,
+                            description: 'Opaque cursor from a prior discovery action with the same query.',
+                        },
+                    },
+                },
                 {
                     type: 'object',
                     required: ['action', 'conversationId', 'text'],
@@ -139,6 +164,36 @@ function hasOnlyKeys(record, allowed) {
 export function parseCommunicateToolInput(value) {
     if (!isRecord(value))
         throw new Error('communicate arguments must be an object');
+    if (value.action === 'discover_agents') {
+        if (!hasOnlyKeys(value, new Set(['action', 'query', 'limit', 'cursor']))) {
+            throw new Error('discover_agents contains unsupported fields');
+        }
+        if (value.query !== undefined && typeof value.query !== 'string') {
+            throw new Error('communicate.query must be a string');
+        }
+        if (typeof value.query === 'string'
+            && value.query.length > MAX_DISCOVER_AGENTS_QUERY_LENGTH) {
+            throw new Error(`communicate.query must be at most ${MAX_DISCOVER_AGENTS_QUERY_LENGTH} characters`);
+        }
+        if (value.limit !== undefined
+            && (!Number.isInteger(value.limit)
+                || value.limit < 1
+                || value.limit > CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS)) {
+            throw new Error(`communicate.limit must be an integer from 1 to ${CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS}`);
+        }
+        if (value.cursor !== undefined
+            && (typeof value.cursor !== 'string' || value.cursor.length === 0)) {
+            throw new Error('communicate.cursor must be a non-empty string');
+        }
+        return {
+            action: 'discover_agents',
+            ...(typeof value.query === 'string' ? { query: value.query } : {}),
+            limit: typeof value.limit === 'number'
+                ? value.limit
+                : CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS,
+            ...(typeof value.cursor === 'string' ? { cursor: value.cursor } : {}),
+        };
+    }
     if (value.action === 'create_group') {
         if (!hasOnlyKeys(value, new Set(['action', 'name', 'memberIds']))) {
             throw new Error('create_group contains unsupported fields');

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 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';
+export { CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS, 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, 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';
+export { CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS, CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, createCanonCommunicationBinding, executeCanonCommunicateTool, parseCommunicateToolInput, } from './communication-tool.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-tools",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
   "type": "module",
   "main": "dist/index.js",
@@ -31,18 +31,13 @@
     "agent-tools",
     "mcp"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/HeyBobChan/canon",
-    "directory": "packages/agent-tools"
-  },
-  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/agent-tools",
+  "homepage": "https://canonmail.com/agents/build#canonical-verbs",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@canonmsg/core": "^12.0.0",
-    "@canonmsg/rich-cards": "^0.10.4",
+    "@canonmsg/core": "^12.4.0",
+    "@canonmsg/rich-cards": "^0.10.5",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
@@ -51,5 +46,8 @@
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "bugs": {
+    "url": "https://canonmail.com/support"
+  }
 }