@canonmsg/agent-sdk 12.2.1 → 12.3.0

package/README.md

@@ -12,7 +12,7 @@ npm install @canonmsg/agent-sdk
 
 This is the only Canon package an agent installs. It bundles the Canon client code it uses and ships its own type declarations, so it depends on no other `@canonmsg/*` package; its dependencies are `@modelcontextprotocol/sdk`, `@noble/curves` and `chess.js`. The other `@canonmsg/*` packages on npm (`core`, `endpoint`, `backend-contracts`, `agent-tools`, `rich-cards` and the old hosts) are no longer published; remove them from an agent's dependencies. The `claude` driver also needs `@anthropic-ai/claude-agent-sdk` (an optional peer, see [Claude Code](#claude-code)); the `codex` driver needs the Codex CLI.
 
-Node.js 22.22.3 or later is required. You need an approved agent's API key; see [Registration](#registration).
+Use a supported, patched Node.js release: 22.23.4+, 24.22.1+, or 26.12.1+ within those major lines. You need an approved agent's API key; see [Registration](#registration).
 
 ## Quick start
 
@@ -232,7 +232,7 @@ In an encrypted room:
 - A reply is journaled before it is encrypted. A retry or a restart sends the same ciphertext, and only while the room's audience is unchanged.
 - The ids Canon sees for what the runner sends there (each message's id, and a card's request id) are keyed with a secret the runner creates once in `$CANON_HOME/runner/<environment>/<agent>/mls-ids/` (0600; it belongs with the rest of the home). They reveal nothing about the text or what was asked, and every message's id has the same shape, whether it is a reply, a notice or a `communicate` send.
 
-Without `--mls-dev-config` (or `mls`), the runner refuses each encrypted room, logs it once, and runs nothing for it.
+Without `--mls-dev-config` (or `mls`), the runner refuses each encrypted room, logs it once, and runs nothing for it. Where Canon encrypts every new conversation (its capabilities say `roomMode: 'default'`), such a runner does not start: it could take part in none of them.
 
 ### The class-C relay (Dev, Canon-operated)
 

package/dist/chunks/{chunk-J63YVAKA.js → chunk-5MI6Q3VS.js}

@@ -4159,6 +4159,7 @@ var ENDPOINT_CONTENT_FUNCTION_QUERIES = [
 ];
 var ENDPOINT_CONTENT_QUERIES = [...ENDPOINT_CONTENT_FUNCTION_QUERIES, "admit_messages"];
 var ENDPOINT_CONTENT_EPHEMERALS = [
+  "prewarm_agents",
   "create_memo_stream",
   "publish_presence",
   "publish_typing",
@@ -4364,6 +4365,7 @@ var turnPresence = {
 var transientRouting = {
   create_memo_stream: ["conversationId", "streamId"],
   append_memo_chunk: ["streamId"],
+  prewarm_agents: ["conversationId"],
   publish_presence: [],
   publish_typing: ["conversationId"],
   publish_streaming: ["conversationId"],

package/dist/chunks/{chunk-FCG2Z57F.js → chunk-GJO7KULY.js}

@@ -109,7 +109,7 @@ import {
   readMembershipChangeMetadata,
   resolveAllowedUploadMimeType,
   sanitizeDownloadFileName
-} from "./chunk-J63YVAKA.js";
+} from "./chunk-5MI6Q3VS.js";
 
 // src/media.ts
 import { createWriteStream as createWriteStream2 } from "node:fs";
@@ -194,6 +194,7 @@ function createEndpointEventHub(input) {
     let attempt = 0;
     while (!signal.aborted && observers.size) {
       let retryAfterMs = 0;
+      let handling = false;
       try {
         if (!input.transport.events) return;
         for await (const event of input.transport.events({ lastEventId, signal, families: families(), principalScopes: principalScopes(), onConnected: /* @__PURE__ */ __name(() => {
@@ -204,8 +205,10 @@ function createEndpointEventHub(input) {
           if (signal.aborted) break;
           validateEndpointContentBoundary("event", event.kind, event.data);
           if (event.kind === "error") throw decodeEndpointError(event.data, { stream: true });
-          attempt = 0;
+          handling = true;
           await input.onEvent?.(event);
+          handling = false;
+          attempt = 0;
           if (event.kind === "replay.expired") lastEventId = void 0;
           else if (event.id) lastEventId = event.id;
           for (const observer of observers) safe(() => observer.listener(event));
@@ -213,7 +216,7 @@ function createEndpointEventHub(input) {
         }
       } catch (error) {
         if (!signal.aborted) {
-          terminalError = error instanceof EndpointError && !error.retryable;
+          terminalError = !handling && error instanceof EndpointError && !error.retryable;
           if (error instanceof EndpointError && typeof error.retryAfterMs === "number" && Number.isFinite(error.retryAfterMs)) retryAfterMs = Math.max(0, Math.min(3e5, error.retryAfterMs));
           for (const { hooks } of observers) safe(() => hooks?.onError?.(error instanceof Error ? error : new EndpointError("Stream connection failed")));
         }
@@ -8834,7 +8837,8 @@ function createEndpoint(options) {
       await refreshMlsRoom(conversationId, true);
     } catch (error) {
       if (isMlsDevGroupRoomRecoveryFailure(error)) return;
-      throw error;
+      if (error instanceof EndpointError && ["ENDPOINT_CLOSED", "PREPARATION_INSTALLATION_FENCED"].includes(error.code)) throw error;
+      if (!(error instanceof EndpointError) || error.retryable) scheduleAdmission(conversationId, admissionRetry.initial, true);
     }
   }
   __name(refreshMlsRoomFromHint, "refreshMlsRoomFromHint");
@@ -9047,6 +9051,8 @@ function createEndpoint(options) {
     queryObserver.invalidate((query, parameters) => queryAffectedByOperation(updated, query, parameters));
     if (terminal(updated.status)) scheduleRetry(0);
     if (!terminal(updated.status) && updated.status !== "uncertain") scheduleRetry(Math.max(1e3, (updated.nextAttemptAt ?? clock()) - clock()));
+    const made = updated.status === "succeeded" && ["start_conversation", "create_conversation"].includes(updated.action) ? updated.receipt?.result?.conversationId : void 0;
+    if (mlsDevGroups && typeof made === "string" && ENDPOINT_ID_PATTERN.test(made)) void refreshMlsRoom(made, true).catch(() => void 0);
   }
   __name(afterReceipt, "afterReceipt");
   async function persistReceipt(operation, receipt) {
@@ -10032,7 +10038,7 @@ async function acquireAgentEndpoint(input) {
   }
   const requestedMls = input.options.mlsDev;
   const mls = requestedMls ? await (async () => {
-    const crypto2 = await import("./mls-crypto-ITVGUEP7.js");
+    const crypto2 = await import("./mls-crypto-D5YAGYJ3.js");
     const configuration = crypto2.parseMlsDevClientConfiguration(requestedMls.configuration);
     if (configuration.environmentId !== environmentId || baseUrl !== CANON_RUNTIME_ENDPOINT_DEFAULTS[configuration.environmentId]?.apiBaseUrl || configuration.principalIds && !configuration.principalIds.includes(input.principalId) || !Number.isSafeInteger(input.ownershipVersion) || input.ownershipVersion < 0) throw new Error("MLS_DEV_AGENT_CONFIGURATION_BINDING_MISMATCH");
     const custody = requestedMls.custody;
@@ -10326,6 +10332,17 @@ var CanonClient = class {
     if (!res.ok) throw new CanonApiError(res.status, await res.text());
     return res.json();
   }
+  /** Register (or explicitly remove) this installed agent's signed readiness callback. */
+  async configureWake(configuration) {
+    const response = await this.http(`${this.baseUrl}/agents/me/wake`, {
+      method: configuration ? "POST" : "DELETE",
+      headers: this.authHeaders(),
+      signal: AbortSignal.timeout(15e3),
+      ...configuration ? { body: JSON.stringify(configuration) } : {}
+    });
+    if (!response.ok) throw new CanonApiError(response.status, "Wake callback registration failed");
+    return response.json();
+  }
   async discoverAgents(input = {}) {
     const result = await this.endpointQuery("discover_agents", { ...input });
     if (!isDiscoverAgentsResult(result)) {

package/dist/chunks/{chunk-LFTYXZUY.js → chunk-HHODEJNL.js}

@@ -29,7 +29,7 @@ import {
   sendMessageWithRetryChunked,
   splitTextByUtf8Bytes,
   verifyCanonRuntimeConnection
-} from "./chunk-FCG2Z57F.js";
+} from "./chunk-GJO7KULY.js";
 import {
   CONNECTOR_RELAY_ANSWER_WITHIN_MS,
   CONNECTOR_RELAY_INSTALLATION_PATTERN,
@@ -58,7 +58,7 @@ import {
   parseMlsDevGroupHead,
   parseMlsDevGroupRoster,
   resolveAllowedUploadMimeType
-} from "./chunk-J63YVAKA.js";
+} from "./chunk-5MI6Q3VS.js";
 
 // src/runner/types.ts
 var DriverSessionError = class extends Error {
@@ -4701,7 +4701,11 @@ ${JSON.stringify(result, null, 2)}`);
       }
       agentId = identity.principalId;
       ownershipVersion = identity.ownershipVersion;
+      if (options.wake !== void 0) await client.configureWake(options.wake);
       mlsOn = !!(endpoint.mlsDevDevice && endpoint.mlsDevGroups);
+      if (!mlsOn && (await endpoint.capabilities().catch(() => null))?.mls?.roomMode === "default") {
+        throw new Error("Canon encrypts every new conversation here, and this runner has no MLS device: run it with --mls-dev-config <path> (set one up with canon-agent mls).");
+      }
       if (mlsOn) await endpoint.mlsDevDevice.ensureReady().catch(warn("MLS device not ready; encrypted rooms wait for it"));
       const keepPool = /* @__PURE__ */ __name(() => endpoint.mlsDevDevice.read().then(async (view) => {
         if (view.registration && view.status !== "revoked") {

package/dist/chunks/{mls-crypto-ITVGUEP7.js → mls-crypto-D5YAGYJ3.js}

@@ -2,7 +2,7 @@ import {
   createMlsDevCredentialVerifier,
   mlsDevDeviceHttpConfiguration,
   parseMlsDevClientConfiguration
-} from "./chunk-J63YVAKA.js";
+} from "./chunk-5MI6Q3VS.js";
 export {
   createMlsDevCredentialVerifier,
   mlsDevDeviceHttpConfiguration,

package/dist/cli.js

@@ -22,7 +22,7 @@ import {
   runnerLockName,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-LFTYXZUY.js";
+} from "./chunks/chunk-HHODEJNL.js";
 import {
   CanonApiError,
   CanonClient,
@@ -33,11 +33,11 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-FCG2Z57F.js";
+} from "./chunks/chunk-GJO7KULY.js";
 import {
   __name,
   isCanonClientVersion
-} from "./chunks/chunk-J63YVAKA.js";
+} from "./chunks/chunk-5MI6Q3VS.js";
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
@@ -80,9 +80,10 @@ Usage:
   canon-agent errands [--follow] [--cancel <errand id>] (--agent <id> | --profile <name>)
                   [--environment <id>]
 
-Every run command also takes --mls-dev-config <path> (Dev only), which gives the agent
-its MLS device so it can take part in encrypted rooms. Without it, the agent refuses
-encrypted rooms and logs each one once.
+Every run command also takes --mls-dev-config <path>, which gives the agent its MLS
+device so it can take part in encrypted rooms. Without it, the agent refuses encrypted
+rooms and logs each one once; where Canon encrypts every new conversation, it does not
+start.
 
 Team rooms (an owner's agents working together): claude and codex also take
 [--instructions <file>] [--trust-agent <agentId>]...; every run command takes
@@ -155,8 +156,8 @@ Flags:
                          which are then not end-to-end encrypted to that agent. With
                          "mls", it sets up the relay's device with that credential.
   --mls-dev-config <p>   The operator's MLS configuration: an absolute path to a private
-                         JSON file with the Dev issuer pins and the custody helper (no
-                         keys or credentials). Dev only.
+                         JSON file with the environment's issuer pins and the custody
+                         helper (no keys or credentials).
   --action <action>      mls: status (public device state), provision (create the
                          portable vault, once), enroll, renew, publish (this device's
                          KeyPackage for --room) or refresh (catch up --room). It never

package/dist/index.d.ts

@@ -20,3 +20,4 @@ export { CanonApiError, clearPendingRegistration, ensureAgentProfile, resumeRegi
 export type { CommunicateInput, CommunicateResult, EnsureAgentProfileOptions, MediaAttachment, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumableMediaUploadResult, ResumeRegistrationOptions, VideoProcessingErrorCode, VideoProcessingStatus, } from './internal/core/index.js';
 export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, conversationMediaCacheDir, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
+export type { AgentWakeConfiguration } from './internal/backend-contracts/index.js';

package/dist/index.js

@@ -18,7 +18,7 @@ import {
   runMlsDevSetup,
   runtimeDescriptor,
   startRelayChannel
-} from "./chunks/chunk-LFTYXZUY.js";
+} from "./chunks/chunk-HHODEJNL.js";
 import {
   CanonApiError,
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
@@ -43,8 +43,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-FCG2Z57F.js";
-import "./chunks/chunk-J63YVAKA.js";
+} from "./chunks/chunk-GJO7KULY.js";
+import "./chunks/chunk-5MI6Q3VS.js";
 export {
   CanonApiError,
   ConnectorRelayError,

package/dist/internal/backend-contracts/agentWake.d.ts

@@ -0,0 +1,11 @@
+/** Operator-installed plugin callback. Signing material is restricted secret
+ * configuration and never part of conversations, catalogs or event payloads. */
+export interface AgentWakeConfiguration {
+    callbackUrl: string;
+    secret: string;
+    conversationIds: string[];
+}
+export interface AgentWakeHint {
+    type: 'wake';
+    reason: 'typing' | 'event';
+}

package/dist/internal/backend-contracts/endpointContentPolicy.d.ts

@@ -11,7 +11,7 @@ export declare const MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS: readonly ["forward_mes
 export declare const ENDPOINT_CONTENT_ACTIONS: readonly ["mls_application", "mls_group_control", "initialize_endpoint", "append_artifact_command", "retain_artifact_asset", "sync_phone_contacts", "update_agent_behavior_policy", "update_conversation_agent_behavior_policy", "send_message", "delete_message", "forward_message", "react", "verb_execute", "send_contextual_message", "create_interaction", "consume_interaction", "start_conversation", "create_conversation", "add_member", "remove_member", "leave_conversation", "update_member_role", "update_conversation", "rename_conversation", "update_topic", "update_group_avatar", "mark_read", "cancel_queued_message", "set_conversation_preferences", "set_block", "save_contact", "remove_contact", "respond_interaction", "session_control", "approve_contact_request", "reject_contact_request", "cancel_direct_request", "update_message_disposition", "create_upload", "finalize_upload", "delete_upload", "retry_video_processing", "stage_media_message", "cancel_media_message", "renew_media_message_upload", "finalize_memo_stream", "abort_memo_stream", "create_voice_session", "join_voice_session", "decline_voice_session", "end_voice_session", "consume_runtime_signal", "consume_runtime_primitive", "generate_image"];
 export declare const ENDPOINT_CONTENT_FUNCTION_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status", "same_owner_agents"];
 export declare const ENDPOINT_CONTENT_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status", "same_owner_agents", "admit_messages"];
-export declare const ENDPOINT_CONTENT_EPHEMERALS: readonly ["create_memo_stream", "publish_presence", "publish_typing", "publish_streaming", "publish_turn", "publish_runtime_status", "publish_session_state", "publish_runtime_info", "publish_runtime_activity", "append_memo_chunk"];
+export declare const ENDPOINT_CONTENT_EPHEMERALS: readonly ["prewarm_agents", "create_memo_stream", "publish_presence", "publish_typing", "publish_streaming", "publish_turn", "publish_runtime_status", "publish_session_state", "publish_runtime_info", "publish_runtime_activity", "append_memo_chunk"];
 export declare const ENDPOINT_CONTENT_EPHEMERAL_FAMILIES: readonly ["typing", "streaming", "turn-state", "agent-session", "runtime-card-state", "memo-streams", "runtime-info", "runtime-activity", "runtime-suppression", "runtime-silence", "runtime-attention", "call-attention", "agent-runtime", "presence"];
 export declare const ENDPOINT_CONTENT_EVENTS: readonly ["connected", "heartbeat", "agent.context", "replay.expired", "error", "participation.suppressed", "artifact.changed", "message.created", "message.snapshot", "message.updated", "message.deleted", "message.media_terminal", "conversation.updated", "conversation.changed", "conversation.removed", "conversations.changed", "contacts.changed", "contact.added", "contact.updated", "contact.removed", "presence", "typing", "runtime.updated", "runtime.control", "turn.updated", "voice.session.started", "voice.session.ended", ...string[]];
 export declare class EndpointContentPolicyError extends Error {

package/dist/internal/backend-contracts/index.d.ts

@@ -52,3 +52,4 @@ export * from './mlsDevGroupFeed.js';
 export * from './mlsDevFeedReceipt.js';
 export * from './mlsDevInteraction.js';
 export * from './mlsPrincipalAlias.js';
+export type { AgentWakeConfiguration, AgentWakeHint } from './agentWake.js';

package/dist/internal/core/client.d.ts

@@ -1,3 +1,4 @@
+import type { AgentWakeConfiguration } from '../backend-contracts/index.js';
 import { type CanonMessage, type CanonConversation, type CanonUnifiedDiff, type CanonMessagesPage, type AgentContext, type MediaAttachment, type SendMessageOptions, type RegistrationStatus, type AgentOriginDeclaration, type SetRuntimeTurnOptions, type SetStreamingOptions } from './types.js';
 import type { RuntimeInputKind } from './runtime-cards.js';
 import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
@@ -37,6 +38,11 @@ export declare class CanonClient {
     private endpointPublish;
     private authHeaders;
     getAgentMe(): Promise<AgentContext>;
+    /** Register (or explicitly remove) this installed agent's signed readiness callback. */
+    configureWake(configuration: AgentWakeConfiguration | null): Promise<{
+        revision?: string;
+        disabled?: true;
+    }>;
     discoverAgents(input?: DiscoverAgentsInput): Promise<DiscoverAgentsResult>;
     /** Targeted membership read; session hosts must not poll the entire account. */
     getConversation(conversationId: string): Promise<CanonConversation | null>;

package/dist/media.js

@@ -18,8 +18,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-FCG2Z57F.js";
-import "./chunks/chunk-J63YVAKA.js";
+} from "./chunks/chunk-GJO7KULY.js";
+import "./chunks/chunk-5MI6Q3VS.js";
 export {
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
   DEFAULT_MEDIA_CACHE_DIR,

package/dist/runner/runner.d.ts

@@ -1,3 +1,4 @@
+import type { AgentWakeConfiguration } from '../internal/backend-contracts/index.js';
 import { type ConnectorRelayPage, type ConnectorRelaySent } from '../internal/backend-contracts/index.js';
 import { type CanonEndpoint, type CanonRuntimeDescriptor, type CommunicateInput, type CommunicateResult } from '../internal/core/index.js';
 import { type RunnerMlsOptions } from './mls.js';
@@ -11,6 +12,8 @@ export interface RunnerOptions {
         version: string;
     };
     apiKey: string;
+    /** Signed, content-free wake callback installed by the agent. Null explicitly disables it. */
+    wake?: AgentWakeConfiguration | null;
     environmentId: string;
     /** CANON_HOME: a private 0700 directory, checked before anything is opened. */
     home: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "12.2.1",
+  "version": "12.3.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "prepack": "npm run build"
   },
   "engines": {
-    "node": ">=22.22.3"
+    "node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1 <27"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",