@canonmsg/agent-tools 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+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';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CANON_TOOL_VERBS, canonVerbToolDefinitions, executeCanonVerbTool, isCanonToolVerb, normalizeVerbToolArgs, stampSendToTurnComplete, } from './verb-tools.js';
+export { CANON_VERB_MCP_SERVER_NAME, createCanonVerbMcpServer, } from './verb-mcp.js';

package/dist/verb-mcp.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-process MCP server exposing the canonical Canon verbs — used by
+ * canon-claude host sessions, and reusable by any Node runtime that can
+ * mount an MCP server instance.
+ *
+ * The Agent SDK accepts `{ type: 'sdk', name, instance }` in
+ * options.mcpServers, where instance is a real @modelcontextprotocol/sdk
+ * Server. That lets this mount reuse the exact JSON-Schema tool projections
+ * from verb-tools.ts (the SDK's own `tool()` helper wants Zod shapes — not
+ * needed here). Tools surface to the model as `mcp__canon__<verb>`;
+ * the claude host's tool-policy special-cases that prefix so HITL/read
+ * verbs never recursively raise Canon approval cards.
+ *
+ * This mount is a WAITING binding: its consumers' turns already block on
+ * native HITL (canUseTool approvals, AskUserQuestion input cards), so
+ * blocking interactive verbs poll to the intent-level result the contract
+ * promises — submitted / allow / deny / timeout — instead of returning the
+ * accepted half, and the projected descriptions advertise exactly that.
+ * Detached approvals still return pending immediately.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanonClient } 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";
+export declare function createCanonVerbMcpServer(getClient: () => CanonClient | null, 
+/**
+ * Lazy per-call execution context (host sessions are conversation-scoped:
+ * active conversation, current turn, turn responder). Read at call time —
+ * the session object outlives any single turn.
+ */
+getContext?: () => VerbExecutionContext | undefined): McpServer;

package/dist/verb-mcp.js

@@ -0,0 +1,80 @@
+/**
+ * In-process MCP server exposing the canonical Canon verbs — used by
+ * canon-claude host sessions, and reusable by any Node runtime that can
+ * mount an MCP server instance.
+ *
+ * The Agent SDK accepts `{ type: 'sdk', name, instance }` in
+ * options.mcpServers, where instance is a real @modelcontextprotocol/sdk
+ * Server. That lets this mount reuse the exact JSON-Schema tool projections
+ * from verb-tools.ts (the SDK's own `tool()` helper wants Zod shapes — not
+ * needed here). Tools surface to the model as `mcp__canon__<verb>`;
+ * the claude host's tool-policy special-cases that prefix so HITL/read
+ * verbs never recursively raise Canon approval cards.
+ *
+ * This mount is a WAITING binding: its consumers' turns already block on
+ * native HITL (canUseTool approvals, AskUserQuestion input cards), so
+ * blocking interactive verbs poll to the intent-level result the contract
+ * promises — submitted / allow / deny / timeout — instead of returning the
+ * accepted half, and the projected descriptions advertise exactly that.
+ * Detached approvals still return pending immediately.
+ */
+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';
+/** MCP server name — verbs appear to the model as `mcp__canon__<verb>`. */
+export const CANON_VERB_MCP_SERVER_NAME = 'canon';
+export function createCanonVerbMcpServer(getClient, 
+/**
+ * Lazy per-call execution context (host sessions are conversation-scoped:
+ * active conversation, current turn, turn responder). Read at call time —
+ * the session object outlives any single turn.
+ */
+getContext) {
+    // 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
+    // (safe: registerTool is never called, so McpServer installs no competing
+    // tool handlers).
+    const mcpServer = new McpServer({ name: CANON_VERB_MCP_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
+    const server = mcpServer.server;
+    // 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({
+            interaction: 'waiting',
+            conversationScoped: Boolean(getContext),
+        }),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const client = getClient();
+        if (!client) {
+            return {
+                content: [{ type: 'text', text: 'Canon not connected' }],
+                isError: true,
+            };
+        }
+        const name = request.params.name;
+        if (!isCanonToolVerb(name)) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        const rawArgs = request.params.arguments && typeof request.params.arguments === 'object'
+            ? { ...request.params.arguments }
+            : {};
+        const verbArgs = name === 'send_to' ? stampSendToTurnComplete(rawArgs) : rawArgs;
+        const context = getContext?.();
+        const result = await executeCanonVerbTool(client, name, verbArgs, {
+            waitForResult: true,
+            signal: extra?.signal,
+            ...(context ? { context } : {}),
+        });
+        return {
+            content: result.content.map((item) => ({ type: 'text', text: item.text })),
+            ...(result.isError ? { isError: true } : {}),
+        };
+    });
+    return mcpServer;
+}

package/dist/verb-tools.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Canonical verb tools — shared projections of canon.verbs.v1 for runtime
+ * bindings (extracted once two real projections — the Claude channel server
+ * and the claude host in-process mount — proved the boundary).
+ *
+ * Tool definitions are PROJECTIONS of the contract: names from
+ * canonVerbToolName-free plain verb names (the MCP server supplies the
+ * namespace), input schemas extracted self-contained from the contract
+ * bundle (card verbs composed with the full canon.card.v1 document schema),
+ * and dispatch = project intent -> wire -> POST /agent/verbs/:verb.
+ * Developing a capability = add a verb to the contract + endpoint; this
+ * module picks it up by listing it below.
+ *
+ * Interactive-verb posture is a BINDING choice, declared twice in matching
+ * halves — VerbProjectionOptions shapes what the model is TOLD, and
+ * ExecuteVerbToolOptions shapes what the dispatch DOES:
+ * - waiting bindings (the claude host, whose turns already block on native
+ *   HITL) poll the consume endpoints after acceptance and return the
+ *   intent-level result (submitted / allow / deny / timeout) the contract
+ *   promises;
+ * - non-waiting bindings (the channel server — an MCP side-channel whose
+ *   tool calls must not block on a human for minutes) return the server's
+ *   accepted half, explicitly documented, with the answer arriving as an
+ *   inbound notification and check_approval covering detached decisions.
+ */
+import { type CanonClient, type CanonVerbName } from '@canonmsg/core';
+export declare const CANON_TOOL_VERBS: CanonVerbName[];
+export interface VerbToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * How a binding projects the verbs to its model. Must match the dispatch
+ * half (ExecuteVerbToolOptions): interaction 'waiting' pairs with
+ * waitForResult, conversationScoped pairs with a VerbExecutionContext.
+ */
+export interface VerbProjectionOptions {
+    /** Interactive-verb posture the descriptions advertise (default 'notify'). */
+    interaction?: 'waiting' | 'notify';
+    /**
+     * Whether the binding injects an active conversation. Unscoped projections
+     * (default) mark conversationId required from the model instead.
+     */
+    conversationScoped?: boolean;
+}
+/** MCP tool definitions projected from the contract, shaped per binding. */
+export declare function canonVerbToolDefinitions(options?: VerbProjectionOptions): VerbToolDefinition[];
+export declare function isCanonToolVerb(name: string): name is CanonVerbName;
+/**
+ * Outbound sends from a Claude surface are completed turns: stamp
+ * turnSemantics 'turn_complete' into send_to messageOptions.metadata unless
+ * the caller already set turn semantics. Shared by the channel server and
+ * the host-mode MCP mount.
+ */
+export declare function stampSendToTurnComplete(args: Record<string, unknown>): Record<string, unknown>;
+export interface VerbToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Binding-supplied execution context. The semantic schemas deliberately mark
+ * conversationId/inputId/deadlines optional because the BINDING owns them —
+ * a model saying request_input({prompt}) is valid, and this context is what
+ * turns it into a complete server request. Conversation-scoped bindings (the
+ * claude host, one session per conversation) inject all three; unscoped
+ * bindings (the channel server) leave conversationId to the model and the
+ * projected schema marks it required instead.
+ */
+export interface VerbExecutionContext {
+    /** Active conversation, injected when the intent omits conversationId. */
+    conversationId?: string;
+    /** Active turn id, stamped on interaction creates for correlation. */
+    turnId?: string;
+    /** Default responder (e.g. the author of the turn being served). */
+    responseUserId?: string;
+}
+export interface ExecuteVerbToolOptions {
+    /**
+     * Poll the consume endpoint after a blocking interactive verb is accepted
+     * and return the intent-level result instead of the accepted half.
+     */
+    waitForResult?: boolean;
+    pollMs?: number;
+    /** Hard cap on waiting regardless of the request's expiresAt. */
+    maxWaitMs?: number;
+    signal?: AbortSignal;
+    /** Binding execution context for context-bound intent fields. */
+    context?: VerbExecutionContext;
+}
+/**
+ * Complete a verb intent's context-bound fields before projection:
+ * conversationId/turnId/responseUserId from the binding context, generated
+ * request ids and default deadlines where the server requires them
+ * (blocking input/approval/card requests use Canon's five-minute HITL
+ * default; detached approvals use the long-lived 72-hour window; card ids are
+ * client-generated for cancellation/reconciliation). Returns
+ * the completed args, or an error string when the intent is unroutable
+ * without a conversation.
+ */
+export declare function normalizeVerbToolArgs(verb: CanonVerbName, args: Record<string, unknown>, context: VerbExecutionContext | undefined, now?: number): {
+    args: Record<string, unknown>;
+} | {
+    error: string;
+};
+/**
+ * Execute a verb tool call: byte-limit precheck, project the intent to the
+ * wire (json codec), POST to /agent/verbs/:verb, unwrap the result.
+ */
+export declare function executeCanonVerbTool(client: CanonClient, verb: CanonVerbName, args: Record<string, unknown>, options?: ExecuteVerbToolOptions): Promise<VerbToolResult>;

package/dist/verb-tools.js

@@ -0,0 +1,408 @@
+/**
+ * Canonical verb tools — shared projections of canon.verbs.v1 for runtime
+ * bindings (extracted once two real projections — the Claude channel server
+ * and the claude host in-process mount — proved the boundary).
+ *
+ * Tool definitions are PROJECTIONS of the contract: names from
+ * canonVerbToolName-free plain verb names (the MCP server supplies the
+ * namespace), input schemas extracted self-contained from the contract
+ * bundle (card verbs composed with the full canon.card.v1 document schema),
+ * and dispatch = project intent -> wire -> POST /agent/verbs/:verb.
+ * Developing a capability = add a verb to the contract + endpoint; this
+ * module picks it up by listing it below.
+ *
+ * Interactive-verb posture is a BINDING choice, declared twice in matching
+ * halves — VerbProjectionOptions shapes what the model is TOLD, and
+ * ExecuteVerbToolOptions shapes what the dispatch DOES:
+ * - waiting bindings (the claude host, whose turns already block on native
+ *   HITL) poll the consume endpoints after acceptance and return the
+ *   intent-level result (submitted / allow / deny / timeout) the contract
+ *   promises;
+ * - non-waiting bindings (the channel server — an MCP side-channel whose
+ *   tool calls must not block on a human for minutes) return the server's
+ *   accepted half, explicitly documented, with the answer arriving as an
+ *   inbound notification and check_approval covering detached decisions.
+ */
+import { randomUUID } from 'node:crypto';
+import { findVerbByteLimitViolations, getVerbInputSchema, projectVerbIntentToWire, VERB_LIMITS, } from '@canonmsg/core';
+import { RUNTIME_CARD_JSON_SCHEMA_V1 } from '@canonmsg/rich-cards';
+/** Verbs exposed to models, with binding-level descriptions. */
+const CANON_VERB_TOOL_DESCRIPTIONS = {
+    send_to: 'Send a Canon message to another conversation or user. Supports a private '
+        + 'selfContext note (with sourceConversationId) so you recognize your own '
+        + 'cross-conversation transfer later. Admission-aware for user targets: '
+        + 'may return requested/pending (contact request) instead of messaged.',
+    request_input: 'Ask a human in a Canon conversation a structured question (input card).',
+    request_approval: 'Ask a human to allow/deny an action via a Canon approval card. Use '
+        + "mode 'detached' and poll with check_approval for long-lived approvals.",
+    check_approval: "Fetch the decision of a detached approval. 'unknown' is NOT a denial — "
+        + 'only resolved carries a decision.',
+    send_card: 'Display a canon.card.v1 card (no actions) in a Canon conversation — '
+        + 'fire-and-forget.',
+    request_card: 'Show an interactive canon.card.v1 card (>= 1 actions block).',
+    share_contact: "Share a contact card into a conversation. The shared user must be in "
+        + 'your contacts.',
+    react: 'Toggle an emoji reaction on a Canon message.',
+    forward: 'Forward an existing Canon message into another conversation, with an optional caption.',
+    create_group: 'Create a Canon group conversation. Directly-addable members join at '
+        + 'creation; approval-required members become pending invites '
+        + '(result.pending); policy-denied members are skipped (result.skipped).',
+    add_member: 'Add a member to a Canon group (approval-required members become a pending invite).',
+    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_conversations: 'List your Canon conversations (optionally limited).',
+};
+/**
+ * Posture-specific completion sentences for the blocking interactive verbs.
+ * A waiting binding returns the intent-level result inside the tool call; a
+ * notify binding returns the accepted half and the answer arrives later —
+ * telling the model the wrong one makes it either abandon answers it should
+ * consume or wait for notifications that already resolved.
+ */
+const INTERACTION_POSTURE_NOTES = {
+    waiting: {
+        request_input: 'Waits for the human and returns the answer in this tool call '
+            + '(submitted / cancelled / timeout).',
+        request_approval: 'Blocking mode waits and returns allow / deny / timeout in this tool call.',
+        request_card: 'Waits for the human and returns the submission in this tool call.',
+    },
+    notify: {
+        request_input: 'Returns the accepted request; the answer arrives as an inbound channel notification.',
+        request_approval: 'Blocking-mode acceptance also resolves via an inbound notification.',
+        request_card: 'Returns the accepted request; the submission arrives as an inbound channel notification.',
+    },
+};
+export const CANON_TOOL_VERBS = Object.keys(CANON_VERB_TOOL_DESCRIPTIONS);
+const CARD_VERBS = new Set(['send_card', 'request_card']);
+/** MCP tool definitions projected from the contract, shaped per binding. */
+export function canonVerbToolDefinitions(options = {}) {
+    const interaction = options.interaction ?? 'notify';
+    return CANON_TOOL_VERBS.map((verb) => {
+        let inputSchema = getVerbInputSchema(verb, CARD_VERBS.has(verb) ? { cardSchema: RUNTIME_CARD_JSON_SCHEMA_V1 } : undefined);
+        // 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
+        // the binding or required from the model, never silently absent.
+        if (!options.conversationScoped && isInteractionVerb(verb)) {
+            const required = new Set([...(inputSchema.required ?? [])]);
+            required.add('conversationId');
+            inputSchema = { ...inputSchema, required: [...required] };
+        }
+        const note = INTERACTION_POSTURE_NOTES[interaction][verb];
+        const base = CANON_VERB_TOOL_DESCRIPTIONS[verb] ?? verb;
+        return {
+            name: verb,
+            description: note ? `${base} ${note}` : base,
+            inputSchema,
+        };
+    });
+}
+export function isCanonToolVerb(name) {
+    return CANON_TOOL_VERBS.includes(name);
+}
+/**
+ * Outbound sends from a Claude surface are completed turns: stamp
+ * turnSemantics 'turn_complete' into send_to messageOptions.metadata unless
+ * the caller already set turn semantics. Shared by the channel server and
+ * the host-mode MCP mount.
+ */
+export function stampSendToTurnComplete(args) {
+    const options = { ...(args.messageOptions ?? {}) };
+    options.metadata = {
+        turnSemantics: 'turn_complete',
+        ...(options.metadata ?? {}),
+    };
+    return { ...args, messageOptions: options };
+}
+/** Verbs whose intents carry context-bound fields the binding must complete. */
+const INTERACTION_VERBS = new Set([
+    'request_input',
+    'request_approval',
+    'send_card',
+    'request_card',
+]);
+function isInteractionVerb(verb) {
+    return INTERACTION_VERBS.has(verb);
+}
+/**
+ * Owner-only input requests (sudo/secret kinds, sensitive, isSecret
+ * questions — mirrors interactionInput.ts ownerOnlyResponse): the server
+ * REJECTS a non-owner explicit responder for these rather than overriding
+ * it, so the binding must not volunteer the turn author — omitting the
+ * responder lets the server route to the owner.
+ */
+function isOwnerOnlyInputRequest(verb, args) {
+    if (verb !== 'request_input')
+        return false;
+    if (args.kind === 'sudo' || args.kind === 'secret')
+        return true;
+    if (args.sensitive === true)
+        return true;
+    const questions = args.questions;
+    return Array.isArray(questions)
+        && questions.some((question) => Boolean(question?.isSecret));
+}
+/** Back off long-lived defaults from the server ceiling to tolerate clock skew. */
+const DEADLINE_SKEW_MARGIN_MS = 60_000;
+const DEFAULT_INTERACTION_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Complete a verb intent's context-bound fields before projection:
+ * conversationId/turnId/responseUserId from the binding context, generated
+ * request ids and default deadlines where the server requires them
+ * (blocking input/approval/card requests use Canon's five-minute HITL
+ * default; detached approvals use the long-lived 72-hour window; card ids are
+ * client-generated for cancellation/reconciliation). Returns
+ * the completed args, or an error string when the intent is unroutable
+ * without a conversation.
+ */
+export function normalizeVerbToolArgs(verb, args, context, now = Date.now()) {
+    if (!INTERACTION_VERBS.has(verb))
+        return { args };
+    const completed = { ...args };
+    if (typeof completed.conversationId !== 'string' || !completed.conversationId) {
+        if (typeof context?.conversationId === 'string' && context.conversationId) {
+            completed.conversationId = context.conversationId;
+        }
+        else {
+            return {
+                error: `${verb} requires conversationId: this binding has no active `
+                    + 'conversation to default to, so pass it explicitly.',
+            };
+        }
+    }
+    if (completed.turnId === undefined && context?.turnId) {
+        completed.turnId = context.turnId;
+    }
+    if (verb !== 'send_card'
+        && completed.responseUserId === undefined
+        && context?.responseUserId
+        && !isOwnerOnlyInputRequest(verb, completed)) {
+        completed.responseUserId = context.responseUserId;
+    }
+    const hasDeadline = completed.expiresAt !== undefined || completed.timeoutMs !== undefined;
+    // Request ids are generated CLIENT-side (the server would generate
+    // approval/card ids itself) so that a create whose RESPONSE is lost is
+    // still cancellable — the binding knows the id it must clean up even when
+    // the 201 never arrives.
+    if (verb === 'request_input') {
+        // kind is server-REQUIRED (normalizeKind throws on absence) — a bare
+        // request_input({prompt}) is a clarify question.
+        if (completed.kind === undefined)
+            completed.kind = 'clarify';
+        if (completed.inputId === undefined)
+            completed.inputId = `input_${randomUUID()}`;
+        if (!hasDeadline) {
+            completed.expiresAt = now + DEFAULT_INTERACTION_TIMEOUT_MS;
+        }
+    }
+    if (verb === 'request_approval') {
+        if (completed.approvalId === undefined)
+            completed.approvalId = `apr_${randomUUID()}`;
+        if (!hasDeadline) {
+            completed.expiresAt =
+                completed.mode === 'detached'
+                    ? now + VERB_LIMITS.maxApprovalTimeoutMs - DEADLINE_SKEW_MARGIN_MS
+                    : now + DEFAULT_INTERACTION_TIMEOUT_MS;
+        }
+    }
+    if (CARD_VERBS.has(verb) && completed.cardId === undefined) {
+        const card = completed.card;
+        completed.cardId =
+            (typeof card?.cardId === 'string' && card.cardId) || `card_${randomUUID()}`;
+    }
+    if (verb === 'request_card' && !hasDeadline) {
+        completed.expiresAt = now + DEFAULT_INTERACTION_TIMEOUT_MS;
+    }
+    return { args: completed };
+}
+const DEFAULT_POLL_MS = 1000;
+const DEFAULT_MAX_WAIT_MS = 30 * 60 * 1000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** One consume-endpoint hit for the verb's interaction family. */
+async function consumeInteractionOnce(client, verb, conversationId, requestId, cancel) {
+    if (verb === 'request_approval') {
+        return (await client.consumeRuntimeApprovalResponse({
+            conversationId,
+            approvalId: requestId,
+            ...(cancel ? { cancel } : {}),
+        }));
+    }
+    if (verb === 'request_card') {
+        return (await client.consumeRuntimeCardResponse({
+            conversationId,
+            cardId: requestId,
+            ...(cancel ? { cancel } : {}),
+        }));
+    }
+    return (await client.consumeRuntimeInputResponse({
+        conversationId,
+        inputId: requestId,
+        ...(cancel ? { cancel } : {}),
+    }));
+}
+/**
+ * Poll the interaction consume endpoint until the accepted request resolves,
+ * expires, or the wait budget runs out; returns the contract's intent-level
+ * result. Consume is poll-safe server-side (pending reads do not consume).
+ *
+ * A wait that ends WITHOUT a resolution does not just walk away — but the
+ * server is told the truth about WHY it ended:
+ * - turn abort or a local wait budget shorter than the deadline -> consume
+ *   with cancel: true (the agent walked away; approvals fail closed to deny);
+ * - the request's own deadline -> a plain consume, which the server resolves
+ *   as TIMEOUT with the same cleanup — nobody denied anything, and the
+ *   receipt must not say they did. Falls back to cancel under clock skew.
+ * Either way the human never faces an actionable card for a dead turn, and
+ * both paths are race-safe — a response that committed first is returned
+ * instead of discarded, so the answer wins whenever one exists.
+ */
+async function waitForInteractionResult(client, verb, conversationId, accepted, options) {
+    const requestId = String(accepted.requestId ?? '');
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const horizon = Math.min(typeof accepted.expiresAt === 'number' ? accepted.expiresAt : Date.now() + DEFAULT_MAX_WAIT_MS, Date.now() + (options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS));
+    const timeoutResult = verb === 'request_approval'
+        ? { status: 'timeout', approvalId: requestId }
+        : verb === 'request_card'
+            ? { status: 'timeout', cardId: requestId }
+            : { status: 'timeout', inputId: requestId };
+    // Cancel-or-take: resolve the pending request as the family's cancelled
+    // result (deny for approvals — fail closed), or return the committed
+    // response if one raced in. Falls back to the local timeout result only
+    // when the cancel call itself fails.
+    const cancelOrTake = async () => {
+        try {
+            return await consumeInteractionOnce(client, verb, conversationId, requestId, true);
+        }
+        catch {
+            return timeoutResult;
+        }
+    };
+    // The natural deadline bound this wait: a plain consume lets the server
+    // resolve TIMEOUT (identical cleanup, honest attribution) instead of an
+    // agent cancel that approvals would record as a deny nobody made. If the
+    // server clock still sees it pending (skew), fall back to cancel.
+    const finishAtDeadline = async () => {
+        try {
+            const consumed = await consumeInteractionOnce(client, verb, conversationId, requestId, false);
+            if (consumed.status !== 'pending')
+                return consumed;
+        }
+        catch {
+            // fall through to cancel
+        }
+        return cancelOrTake();
+    };
+    const deadlineBoundsWait = typeof accepted.expiresAt === 'number' && horizon >= accepted.expiresAt;
+    while (Date.now() < horizon) {
+        if (options.signal?.aborted)
+            return cancelOrTake();
+        let consumed;
+        try {
+            consumed = await consumeInteractionOnce(client, verb, conversationId, requestId, false);
+        }
+        catch (error) {
+            if (error?.status === 404) {
+                // Definitive: no pending request and no replayable tombstone exists
+                // (consume replays resolved results, so 404 is never transient).
+                return timeoutResult;
+            }
+            // Transient consume failure: keep polling until the horizon.
+            await sleep(pollMs);
+            continue;
+        }
+        if (consumed.status !== 'pending')
+            return consumed;
+        await sleep(pollMs);
+    }
+    return deadlineBoundsWait ? finishAtDeadline() : cancelOrTake();
+}
+function statusLine(verb, value) {
+    const status = typeof value.status === 'string' ? value.status : 'ok';
+    const id = value.messageId ?? value.requestId ?? value.approvalId ?? value.cardId ?? value.conversationId;
+    return `${verb}: ${status}${id ? ` (${String(id)})` : ''}`;
+}
+/**
+ * Execute a verb tool call: byte-limit precheck, project the intent to the
+ * wire (json codec), POST to /agent/verbs/:verb, unwrap the result.
+ */
+export async function executeCanonVerbTool(client, verb, args, options = {}) {
+    const normalized = normalizeVerbToolArgs(verb, args, options.context);
+    if ('error' in normalized) {
+        return { content: [{ type: 'text', text: `Invalid arguments: ${normalized.error}` }], isError: true };
+    }
+    args = normalized.args;
+    // canonContactId is a contact-card identity, not a wire field: resolve it
+    // to a targetUserId here (the two-step the contract documents) so the
+    // advertised send_to schema is honest in every binding.
+    if (verb === 'send_to' && typeof args.canonContactId === 'string') {
+        const resolved = await client.resolveAdmission({ canonContactId: args.canonContactId });
+        if (!resolved.resolvedTargetUserId) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `send_to: unavailable\n${JSON.stringify({ status: 'unavailable', reason: 'canonContactId could not be resolved' }, null, 2)}`,
+                    }],
+                isError: true,
+            };
+        }
+        const { canonContactId: _resolved, ...rest } = args;
+        args = { ...rest, targetUserId: resolved.resolvedTargetUserId };
+    }
+    const violations = findVerbByteLimitViolations(verb, args);
+    if (violations.length > 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Invalid arguments: ${violations.map((v) => `${v.path}: ${v.message}`).join('; ')}`,
+                }],
+            isError: true,
+        };
+    }
+    const wire = projectVerbIntentToWire(verb, args, { now: Date.now() });
+    // The interactive request ids are known BEFORE the call (client-generated
+    // in normalization): if the create commits but its response is lost, the
+    // request is cancelled best-effort instead of orphaning an actionable
+    // card the binding could never clean up.
+    const interactiveRequestId = verb === 'request_input'
+        ? args.inputId
+        : verb === 'request_approval'
+            ? args.approvalId
+            : verb === 'request_card'
+                ? args.cardId
+                : undefined;
+    let response;
+    try {
+        response = await client.executeVerbWire(wire);
+    }
+    catch (error) {
+        if (typeof interactiveRequestId === 'string' && typeof args.conversationId === 'string') {
+            try {
+                await consumeInteractionOnce(client, verb, args.conversationId, interactiveRequestId, true);
+            }
+            catch {
+                // Best-effort: the create may never have committed at all.
+            }
+        }
+        throw error;
+    }
+    let value = response.result.encoding === 'json'
+        ? response.result.value
+        : { status: 'encrypted', encoding: response.result.encoding };
+    const isBlockingInteractive = (verb === 'request_input' || verb === 'request_card'
+        || (verb === 'request_approval' && args.mode !== 'detached'))
+        && value.status === 'accepted'
+        // The server marks actions-free display cards interactive:false — there
+        // is no pending node to wait on.
+        && value.interactive !== false;
+    if (isBlockingInteractive && options.waitForResult && typeof args.conversationId === 'string') {
+        value = await waitForInteractionResult(client, verb, args.conversationId, value, options);
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `${statusLine(verb, value)}\n${JSON.stringify(value, null, 2)}`,
+            }],
+    };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@canonmsg/agent-tools",
+  "version": "0.2.0",
+  "description": "Canonical Canon verb tools — shared projections of canon.verbs.v1 for runtime bindings",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../rich-cards",
+    "build": "npm run prepare:workspace-deps && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "canon",
+    "verbs",
+    "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@canonmsg/core": "^4.3.0",
+    "@canonmsg/rich-cards": "^0.8.1",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ajv": "^8.20.0",
+    "typescript": "~5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "license": "MIT"
+}