@canonmsg/agent-sdk 12.2.2 → 12.3.1

package/README.md

@@ -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-LFTYXZUY.js → chunk-HI2SVCUL.js}

@@ -29,7 +29,7 @@ import {
   sendMessageWithRetryChunked,
   splitTextByUtf8Bytes,
   verifyCanonRuntimeConnection
-} from "./chunk-FCG2Z57F.js";
+} from "./chunk-SKFI2MJA.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/{chunk-FCG2Z57F.js → chunk-SKFI2MJA.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")));
         }
@@ -6609,6 +6612,7 @@ var view2 = /* @__PURE__ */ __name((value) => Object.freeze({
   roster: value.roster,
   pendingOperationId: value.pending?.operationId ?? null
 }), "view");
+var CATCH_UP_MAX_AGE_MS = 6e4;
 function createMlsDevGroups(options, context, keyPackages, bridge) {
   const principal = parseMlsDevEnrollmentPrincipal(options.principal);
   const prepareProtected = options.prepareProtectedGroup ?? fail6("MLS_DEV_GROUP_UNAVAILABLE");
@@ -6623,6 +6627,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
   }), "transaction") };
   const fence = /* @__PURE__ */ __name(() => store.transaction(async () => {
   }), "fence");
+  const caughtUpAt = /* @__PURE__ */ new Map();
   async function initialized() {
     const ready = await context.ready();
     await fence();
@@ -6906,7 +6911,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         if (!current.envelope?.head || current.envelope.removed || !same6(current.envelope.head, wire.expectedHead) || current.envelope.groupId !== wire.groupId) fail6("MLS_DEV_GROUP_HEAD_CHANGED", true);
         if (await tx.get(appMessageKey(cid, wire.messageId)) !== void 0 && await tx.get(appMessageKey(cid, wire.messageId)) !== receipt.operationId) fail6("MLS_DEV_APPLICATION_ID_CONFLICT");
         const existingMessage = await tx.get(mlsDevTextMessageKey(cid, wire.messageId));
-        if (existingMessage?.feedOrdinal !== null && existingMessage?.feedOrdinal !== void 0) fail6("MLS_DEV_APPLICATION_ID_CONFLICT");
+        if (existingMessage?.feedOrdinal !== null && existingMessage?.feedOrdinal !== void 0 && (existingMessage.feedOrdinal !== entry.ordinal || sender.deviceId !== current.device.registration.device.deviceId)) fail6("MLS_DEV_APPLICATION_ID_CONFLICT");
         if (!current.envelope.roster.some((member) => same6(member.device, sender) && member.admissionId === wire.preconditions.admissionId)) fail6("MLS_DEV_GROUP_MEMBER_REQUIRED");
         ownIntent = sender.deviceId === current.device.registration.device.deviceId ? await tx.get(appIntentKey(receipt.operationId)) : void 0;
         if (ownIntent && (!same6(ownIntent.envelope, wire) || ownIntent.envelopeHash !== receipt.envelopeHash)) fail6("MLS_DEV_APPLICATION_ID_CONFLICT");
@@ -6919,7 +6924,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         let message, integrity, wrappedState = group.wrappedState;
         if (ownIntent) {
           const local = await store.transaction((tx) => tx.get(mlsDevTextMessageKey(cid, wire.messageId))) ?? fail6();
-          message = local.message.kind === "text" ? parseMlsDevTextPayload(local.message) : parseMlsDevApplicationPayload(local.message);
+          message = local.deleted ? local.message : local.message.kind === "text" ? parseMlsDevTextPayload(local.message) : parseMlsDevApplicationPayload(local.message);
         } else {
           const prepared = await native(init, current, state, cid, group.groupId, { op: "process_application", entry });
           if (prepared.payload.kind !== "text" && prepared.payload.kind !== "item" && prepared.payload.kind !== "interaction" && prepared.payload.kind !== "invalid" || prepared.payload.messageId !== wire.messageId || prepared.payload.operationId !== receipt.operationId || prepared.payload.senderDeviceId !== sender2.deviceId || prepared.payload.feedOrdinal !== entry.ordinal) fail6("MLS_DEV_GROUP_BINDING_MISMATCH");
@@ -7027,7 +7032,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         let operation;
         if (prepared.own) {
           const own = await tx.get(`operation/${receipt.operationId}`) ?? fail6();
-          operation = await bridge.settle(tx, own, {
+          if (own.status !== "succeeded") operation = await bridge.settle(tx, own, {
             protocol: CANON_ENDPOINT_PROTOCOL,
             operationId: own.operationId,
             installationId: own.installationId,
@@ -7108,6 +7113,17 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
   }
   __name(reduceInteraction, "reduceInteraction");
   async function refreshFeed(cid, init) {
+    const applied = { entries: false };
+    try {
+      const view3 = await catchUpFeed(cid, init, applied);
+      caughtUpAt.set(cid, context.clock());
+      return view3;
+    } finally {
+      if (applied.entries) bridge.historyChanged?.(cid);
+    }
+  }
+  __name(refreshFeed, "refreshFeed");
+  async function catchUpFeed(cid, init, applied) {
     if (!bridge.queryFeed) fail6("MLS_DEV_GROUP_UNAVAILABLE");
     for (let page = 0; page < 8; page++) {
       const captured = await store.transaction(async (tx) => capture(tx, await readPreparationSnapshot(tx, scope4(cid)), init, cid));
@@ -7146,6 +7162,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         if (entry.kind === "control") {
           if (!await applyAccepted(init, entry.accepted, void 0, entry)) fail6("MLS_DEV_GROUP_FEED_GAP", true);
         } else await applyApplication(init, entry);
+        applied.entries = true;
       }
       if (!response.hasMore) {
         await store.transaction(async (tx) => {
@@ -7163,7 +7180,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
     }
     return fail6("MLS_DEV_GROUP_CATCHUP_REQUIRED", true);
   }
-  __name(refreshFeed, "refreshFeed");
+  __name(catchUpFeed, "catchUpFeed");
   const canonItemReference = /* @__PURE__ */ __name((item, conversationId, environmentId) => isCanonUploadUrl(item.url, { environmentId, conversationId, uploadId: item.uploadId }) && (item.thumbnailUrl === void 0 || isCanonUploadUrl(item.thumbnailUrl, { environmentId, conversationId, uploadId: item.uploadId, poster: true })), "canonItemReference");
   function itemInput(attachment, caption) {
     const data = record5(attachment, ["kind", "url", "mimeType", "sizeBytes", "uploadId"], ["fileName", "width", "height", "durationMs", "thumbnailUrl", "processingStatus"]);
@@ -7243,7 +7260,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
     __name(existing, "existing");
     const previous = await store.transaction(existing);
     if (previous) return previous;
-    await refresh(cid);
+    if (!await caughtUp(cid)) await refresh(cid);
     await assertNotHeld(cid);
     const messageId = input.messageId ?? id(context.ids());
     let captured, replyTo;
@@ -7768,6 +7785,28 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
     }
   }
   __name(refresh, "refresh");
+  function textReady(conversationId) {
+    return store.transaction(async (tx) => {
+      const ready = await tx.get(`mls-dev-group/feed-ready/${encodeURIComponent(conversationId)}`);
+      return !!ready?.admitted && !ready.terminal && ready.ordinal === await tx.get(feedKey(conversationId)) && await tx.get(recoveryFailureKey(conversationId)) === void 0;
+    });
+  }
+  __name(textReady, "textReady");
+  async function caughtUp(conversationId) {
+    return !!bridge.streamLive?.() && context.clock() - (caughtUpAt.get(conversationId) ?? -Infinity) < CATCH_UP_MAX_AGE_MS && await textReady(conversationId);
+  }
+  __name(caughtUp, "caughtUp");
+  async function settleOwnApplication(tx, operation, accepted, receipt) {
+    if (operation.status === "succeeded" && same6(operation.receipt?.result, receipt.result)) return {};
+    if (operation.status === "succeeded" || operation.status === "rejected") return void 0;
+    const local = await tx.get(mlsDevTextMessageKey(accepted.conversationId, accepted.messageId));
+    if (local?.message.kind !== "text" && local?.message.kind !== "item") return void 0;
+    const intent2 = await tx.get(appIntentKey(operation.operationId));
+    if (accepted.messageId !== operation.messageId || local.message.operationId !== operation.operationId || intent2?.envelopeHash !== accepted.envelopeHash || intent2.envelope.groupId !== accepted.groupId) fail6("MLS_DEV_GROUP_BINDING_MISMATCH");
+    await putMlsDevTextMessage(tx, { ...local, status: "sent", createdAtMs: accepted.acceptedAtMs, feedOrdinal: accepted.feedOrdinal });
+    return { operation: await bridge.settle(tx, operation, receipt, true) };
+  }
+  __name(settleOwnApplication, "settleOwnApplication");
   async function existingOperation(tx, operationId, authored) {
     const intent2 = await tx.get(`mls-dev-group/intent/${operationId}`), operation = await tx.get(`operation/${operationId}`);
     if (!intent2 && !operation) return void 0;
@@ -7900,10 +7939,12 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
     const verified = await store.transaction(async (tx) => {
       const local = await tx.get(mlsDevTextMessageKey(conversationId, messageId));
       if (!local || local.feedOrdinal === null || local.message.kind !== "text" && local.message.kind !== "item" || local.deleted) return void 0;
+      const stored = await tx.get(feedEntryKey(conversationId, local.feedOrdinal));
+      if (stored === void 0) return void 0;
       const text = local.message.kind === "item" ? parseMlsDevItemPayload(local.message) : parseMlsDevTextPayload(local.message);
       const protocol2 = await tx.get(mlsDevTextProtocolKey(conversationId));
       if (!isMlsDevTextProtocol(protocol2)) fail6("MLS_DEV_VERIFIED_MESSAGE_MISMATCH");
-      const entry = parseMlsDevGroupFeedEntry(await tx.get(feedEntryKey(conversationId, local.feedOrdinal)));
+      const entry = parseMlsDevGroupFeedEntry(stored);
       if (entry.kind !== "application") fail6("MLS_DEV_VERIFIED_MESSAGE_MISMATCH");
       const { envelope: wire2, receipt: receipt2 } = entry;
       const sender2 = parseMlsDevCredentialToken(wire2.senderCredential).unsigned.claims.device;
@@ -8102,9 +8143,12 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
       const input = textInput(value), selectedId = id(operationId), selectedGuard = guardId === void 0 ? void 0 : id(guardId);
       return run(() => serializeInboundPreparation(store, input.conversationId, () => sendText(input, selectedId, selectedGuard)));
     },
+    /** A room this device holds caught up is read as it holds it: what fetches the room's new entries says so
+     * (bridge.historyChanged). Otherwise a read fetches the feed first, which the polling fallback and the connected
+     * stream's minute-long safety poll rely on. */
     queryTextHistory(conversationId, name, parameters) {
       return run(() => serializeInboundPreparation(store, id(conversationId), async () => {
-        await refresh(conversationId);
+        if (!await caughtUp(conversationId)) await refresh(conversationId);
         const init = await initialized();
         await primeIdentities(conversationId, init);
         return store.transaction(async (tx) => {
@@ -8128,12 +8172,7 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         });
       }));
     },
-    async isTextReady(conversationId) {
-      return store.transaction(async (tx) => {
-        const ready = await tx.get(`mls-dev-group/feed-ready/${encodeURIComponent(conversationId)}`);
-        return !!ready?.admitted && !ready.terminal && ready.ordinal === await tx.get(feedKey(conversationId)) && await tx.get(recoveryFailureKey(conversationId)) === void 0;
-      });
-    },
+    isTextReady: textReady,
     async readAcceptedReceipt(operation) {
       if (!["mls_group_control", "mls_application"].includes(operation.action)) return void 0;
       return store.transaction(async (tx) => {
@@ -8149,13 +8188,18 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
         const cid = operation.conversationId;
         const accepted2 = operation.action === "mls_application" ? parseMlsDevApplicationReceipt(receipt.result) : parseMlsDevGroupAcceptedControl(receipt.result);
         if (accepted2.operationId !== operation.operationId || ("control" in accepted2 ? accepted2.control.conversationId : accepted2.conversationId) !== cid) fail6("MLS_DEV_GROUP_BINDING_MISMATCH");
-        await store.transaction(async (tx) => {
+        const own = await store.transaction(async (tx) => {
           const current = await tx.get(`operation/${operation.operationId}`) ?? fail6();
           if (receipt.installationId !== current.installationId || receipt.action !== current.action) fail6("MLS_DEV_GROUP_BINDING_MISMATCH");
           const previous = await tx.get(acceptedReceiptKey(operation.operationId));
           if (previous && !same6(previous, receipt)) fail6("MLS_DEV_GROUP_BINDING_MISMATCH");
           if (!previous) await tx.put(acceptedReceiptKey(operation.operationId), receipt);
+          return "control" in accepted2 ? void 0 : settleOwnApplication(tx, current, accepted2, receipt);
         });
+        if (own) {
+          if (own.operation) await bridge.afterReceipt(own.operation);
+          return true;
+        }
         await run(() => serializeInboundPreparation(store, cid, async () => {
           try {
             await refresh(cid);
@@ -8382,7 +8426,10 @@ function createEndpoint(options) {
       clearTimeout(admissionTimers.get(conversationId));
       admissionTimers.delete(conversationId);
       scheduleAdmission(conversationId, 0);
-    }, "controlSettled")
+    }, "controlSettled"),
+    // Whatever fetched them (a hint, the reconnect sweep, a send, recovery), the room's local reads show them now.
+    historyChanged: /* @__PURE__ */ __name((conversationId) => queryObserver.invalidate((query, parameters) => parameters.conversationId === conversationId && ["list_messages", "get_messages", "get_runtime_card_state"].includes(query)), "historyChanged"),
+    streamLive: /* @__PURE__ */ __name(() => events.isConnected(), "streamLive")
   }) : void 0;
   async function inMlsEnvironment() {
     return isMlsEnvironmentId((await initialization).environmentId);
@@ -8834,7 +8881,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 +9095,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 +10082,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 +10376,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/{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-HI2SVCUL.js";
 import {
   CanonApiError,
   CanonClient,
@@ -33,11 +33,11 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-FCG2Z57F.js";
+} from "./chunks/chunk-SKFI2MJA.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-HI2SVCUL.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-SKFI2MJA.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/internal/endpoint/mls-dev-groups.d.ts

@@ -149,6 +149,10 @@ export interface MlsDevGroupBridge {
     /** A control of this device's settled, accepted or lost to another device's: what waited on it can go on now. A hint
      * announcing the room's change may have come while it was pending, and none may follow (D2 holds the room's sends). */
     controlSettled?(conversationId: string): void;
+    /** A fetch applied entries of the room's feed: its encrypted history, read locally, has changed. */
+    historyChanged?(conversationId: string): void;
+    /** This device's event stream is connected, so each room's hints announce what Canon accepts into its feed. */
+    streamLive?(): boolean;
     /** Reads and applies the room's conversation snapshot from Canon, for openings of members admitted since. */
     readRoom?(conversationId: string): Promise<unknown>;
 }
@@ -161,13 +165,16 @@ export declare function createMlsDevGroups(options: MlsDevDeviceClientOptions, c
      * encrypted room (mls-payload-v3.md §4). Items and cards are not forwarded yet. */
     forwardText(value: unknown, operationId: string, guardId?: string): Promise<EndpointOperation>;
     sendText(value: unknown, operationId: string, guardId?: string): Promise<EndpointOperation>;
+    /** A room this device holds caught up is read as it holds it: what fetches the room's new entries says so
+     * (bridge.historyChanged). Otherwise a read fetches the feed first, which the polling fallback and the connected
+     * stream's minute-long safety poll rely on. */
     queryTextHistory(conversationId: string, name: string, parameters: Record<string, unknown>): Promise<{
         messages: Record<string, unknown>[];
         nextBefore?: string | null;
         missingMessageIds?: string[];
     }>;
     syncText(conversationId: string, options?: EndpointSyncOptions): Promise<EndpointSyncPage>;
-    isTextReady(conversationId: string): Promise<boolean>;
+    isTextReady: (conversationId: string) => Promise<boolean>;
     readAcceptedReceipt(operation: EndpointOperation): Promise<EndpointOperationReceipt | undefined>;
     settleReceipt(operation: EndpointOperation, receipt: EndpointOperationReceipt): Promise<boolean>;
 };

package/dist/internal/endpoint/mls-dev-text.d.ts

@@ -29,8 +29,8 @@ export declare const mlsDevTextDeletedKey: (conversationId: string, messageId: s
 export declare const mlsDevTextReactionsKey: (conversationId: string, messageId: string) => string;
 /**
  * Its sender deleted a message for everyone. The decrypted text is erased now, and the tombstone keeps it erased if the
- * feed brings the message again, on catch-up or replay. An own send whose echo is not applied yet keeps its text until
- * the echo applies (the echo is checked against it); the history already shows it deleted. Cards are not deleted this
+ * feed brings the message again, on catch-up or replay. An own send Canon has not accepted yet keeps its text until its
+ * receipt or echo settles it; the history already shows it deleted. Cards are not deleted this
  * way: Canon refuses to delete an encrypted card, which is withdrawn instead. Returns whether anything changed.
  */
 export declare function deleteMlsDevTextMessage(tx: EndpointStoreTransaction, conversationId: string, messageId: string): Promise<boolean>;

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-SKFI2MJA.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.2",
+  "version": "12.3.1",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",