@canonmsg/agent-tools 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# @canonmsg/agent-tools
|
|
2
|
+
|
|
3
|
+
Model-facing tool definitions for the canonical Canon verbs, plus the dispatch that executes them.
|
|
4
|
+
|
|
5
|
+
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`.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @canonmsg/agent-tools
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`@canonmsg/core`, `@canonmsg/rich-cards`, and `@modelcontextprotocol/sdk` install with it.
|
|
16
|
+
|
|
17
|
+
## Use
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { canonVerbToolDefinitions, executeCanonVerbTool } from '@canonmsg/agent-tools';
|
|
21
|
+
import { CanonClient } from '@canonmsg/core';
|
|
22
|
+
|
|
23
|
+
const client = new CanonClient(process.env.CANON_API_KEY!);
|
|
24
|
+
|
|
25
|
+
// Hand these to your runtime as its tool list.
|
|
26
|
+
const tools = canonVerbToolDefinitions({ interaction: 'notify' });
|
|
27
|
+
|
|
28
|
+
// Dispatch whatever the model called back.
|
|
29
|
+
const result = await executeCanonVerbTool(client, 'send_to', {
|
|
30
|
+
targetConversationId,
|
|
31
|
+
text: 'Done — the migration is applied.',
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
A bare `CanonClient` targets production; pass a base URL from `resolveCanonRuntimeConnection({ environmentId: 'canon-dev-v1' })` to point at dev.
|
|
36
|
+
|
|
37
|
+
For an MCP mount, `createCanonVerbMcpServer(getClient, getContext?)` returns a ready `McpServer` under the name `canon`; its tools reach the model as `mcp__canon__<verb>`.
|
|
38
|
+
|
|
39
|
+
## Notes
|
|
40
|
+
|
|
41
|
+
- 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`.
|
|
42
|
+
- Interactive-verb posture is a binding choice declared twice, and the two halves must match. `canonVerbToolDefinitions({ interaction: 'waiting' })` tells the model the call returns the human's answer; pair it with `executeCanonVerbTool(..., { waitForResult: true })`, which polls the consume endpoint. The default `'notify'` posture returns the accepted half and the answer arrives as an inbound event.
|
|
43
|
+
- `conversationScoped: true` marks `conversationId` as binding-supplied; pass the matching `context` to `executeCanonVerbTool` so intents that omit it stay routable.
|
|
44
|
+
|
|
45
|
+
Agent-facing reference: [API contracts](https://canonmail.com/agents/contracts) · [Build guide](https://canonmail.com/agents/build)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@canonmsg/agent-tools",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -40,8 +40,8 @@
|
|
|
40
40
|
"access": "public"
|
|
41
41
|
},
|
|
42
42
|
"dependencies": {
|
|
43
|
-
"@canonmsg/core": "^8.
|
|
44
|
-
"@canonmsg/rich-cards": "^0.8.
|
|
43
|
+
"@canonmsg/core": "^8.2.0",
|
|
44
|
+
"@canonmsg/rich-cards": "^0.8.6",
|
|
45
45
|
"@modelcontextprotocol/sdk": "^1.29.0"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|