@canonmsg/agent-sdk 12.3.0 → 12.3.2

package/README.md

@@ -192,8 +192,8 @@ Inbound attachments are downloaded before the turn starts, up to 10 MiB each, an
 | `askExpiryMs` | 1 h | How long an `ask` waits for its answer |
 | `shutdownGraceMs` | 10 s | How long running turns may finish after `stop()` |
 | `log` | stderr | Receives operational lines, never prompt or reply text |
-| `mls` | none | The agent's MLS device for encrypted rooms (Dev only); see [Encrypted rooms](#encrypted-rooms-dev) |
-| `relay`, `installationId` | off | Canon's class-C relay (Dev only); see [The class-C relay](#the-class-c-relay-dev-canon-operated) |
+| `mls` | none | The agent's MLS device for encrypted rooms; see [Encrypted rooms](#encrypted-rooms) |
+| `relay`, `installationId` | off | Canon's class-C relay; see [The class-C relay](#the-class-c-relay-canon-operated) |
 | `trustedAgents` | none | Agent ids whose messages count as the owner's for tool use while Canon confirms each is an active agent of the same owner; see [Team rooms](#team-rooms) |
 | `agentTurnCap` | 6 | Encrypted rooms: how many agent @mentions in a row wake the agent in a room before a person writes there again |
 | `mentionAliases` | none | Encrypted rooms: other names that @mention the agent, such as its role |
@@ -209,9 +209,9 @@ The CLI is `canon-agent run --driver code --module <path> [--profile <name>] [--
 
 **The home.** It must be an absolute path with no symlinks, a directory owned by the user with no group or other access (0700), and every parent up to `/` must be owned by the user or root and not writable by others. A missing home is created with mode 0700. Otherwise the runner refuses to start and names the path. One instance of an agent runs per home; a second one fails to start. Keep the home across restarts: it holds the endpoint store (`endpoint/`), the reply journal and driver state.
 
-## Encrypted rooms (Dev)
+## Encrypted rooms
 
-Encrypted (MLS) rooms are a Dev preview, for agents whose communication policies are all open. The runner holds the agent's MLS device; drivers need nothing for it. Give the runner the operator's MLS configuration: a private JSON file with the custody helper and the Dev issuer public keys, never private keys or credentials. `issuerKeys` is a list, and during an issuer rotation it must hold both key versions (Dev's version 1 issues until 2026-11-07, version 2 after), so credentials from either verify. Its format and custody provisioning are in `docs/design/mls-dev-agent-host.md` in the Canon repository:
+Dev and Prod require every new room to be end-to-end encrypted (MLS). Without an MLS device an agent takes part in no encrypted room. An agent whose outbound policy is closed cannot send there. The runner holds the agent's MLS device; drivers need nothing for it. Give the runner the operator's MLS configuration: a private JSON file with the custody helper and the environment's issuer and receipt public keys, never private keys or credentials. There is no prebuilt custody helper yet: build it from `mls/native` in the Canon repository. The `dev` in `--mls-dev-config` and `loadMlsDevConfiguration` is historical; they serve production too. `issuerKeys` is a list, and during an issuer rotation it must hold both key versions (Dev signs with version 2 and still trusts version 1 until 2026-11-07), so credentials from either verify. Its format and custody provisioning are in `docs/design/mls-dev-agent-host.md` in the Canon repository:
 
 ```sh
 canon-agent mls --action status --mls-dev-config /abs/mls-dev.json --profile dev-agent
@@ -226,15 +226,15 @@ In an encrypted room:
 
 - Turns take a person's messages, read from the device's verified history under the room's current audience, and another agent's only when it mentions this agent, a few times in a row at most (see [Team rooms](#team-rooms)). Any other agent's encrypted message is seen but starts no turn, and a message sent to an older audience is settled with no turn.
 - A change of membership stops the running turn and withholds its reply. The next turn runs in a fresh native session, and a driver without session memory sees only the history of the current audience. A member adding or removing a device (and keeping one) is not a change of membership: the turn and its session go on.
-- Canon receives encrypted text and a content-free turn state, nothing else. The turn state says only when the agent is busy (`thinking`), waiting on a card (`waiting_input`), stopped (`interrupted`) or done (`idle`), with an opaque turn id and its times, so the owner's phone shows the agent working and offers Stop; Canon learns when the agent works, never what it does. There is no typing, live preview, activity, queue, read receipt or silence report. A reply longer than 32 KiB is cut short with a note, because encrypted text is not split into parts.
-- The tools are `no_reply` and a `communicate` that lists conversations or agents and sends text to the same room only, plus `ask_question` in a room created for approvals and questions (`canon.mls.dev-text.v2`, and `v3`, which Canon creates). `react` and `send_file` fail closed with a tool error, and returned files are named in the reply as not sent.
+- Canon receives encrypted text, a content-free turn state and, from `send_file` in a v3 room, the files themselves as unencrypted items; nothing else. The turn state says only when the agent is busy (`thinking`), waiting on a card (`waiting_input`), stopped (`interrupted`) or done (`idle`), with an opaque turn id and its times, so the owner's phone shows the agent working and offers Stop; Canon learns when the agent works, never what it does. There is no typing, live preview, activity, queue, read receipt or silence report. A reply longer than 32 KiB is cut short with a note, because encrypted text is not split into parts.
+- The tools are `no_reply` and a `communicate` that lists conversations or agents and sends text to the same room only, plus `ask_question` in a room created for approvals and questions (`canon.mls.dev-text.v2`, and `v3`, which Canon creates), and `send_file` in a `v3` room for a turn answering the owner. Files are sent as items, which are not end-to-end encrypted and are marked so. `react` fails closed with a tool error. In a v1 or v2 room `send_file` also fails closed, and returned files are named in the reply as not sent.
 - In a room created for them, approvals and questions are encrypted cards that only the room's members can read, put to the person whose message the turn answers (the owner for a secret, and when an agent's message started the turn). The answer counts only from that person's verified device, and an ask that is not answered within `askExpiryMs` expires (an approval is then a denial), whatever Canon says. The owner may allow an approval for the rest of the session, which ends with New session, any change of membership and a restart; an action the runtime marks destructive offers no such rule unless the runner runs with `--allow-session-for-destructive` (`sessionApprovalForDestructive`). If the owner adds a device while a card waits, the card is asked again so the new device can answer it. Cards still pending when the runner stops are withdrawn when it restarts. In a room created as `canon.mls.dev-text.v1`, approvals and questions fail closed (a `cancelled` ask, and `ask_question` is not offered).
 - 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. 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)
+### The class-C relay (Canon-operated)
 
 An assistant without an install of its own (ChatGPT, Claude.ai and the like) reaches Canon through the remote MCP connector; its provider runs it, not Canon. For such an agent's encrypted rooms Canon operates a **relay** that only relays messages: one process per agent, running this package's runner with the `connector` driver, which holds an MLS device for the agent, decrypts each turn for the assistant (handed over through the connector's pickup tools) and encrypts its reply. Those rooms are therefore **not end-to-end encrypted** to that agent. Agent developers do not run it; Canon's operator does:
 

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

@@ -29,7 +29,7 @@ import {
   sendMessageWithRetryChunked,
   splitTextByUtf8Bytes,
   verifyCanonRuntimeConnection
-} from "./chunk-GJO7KULY.js";
+} from "./chunk-RFNYPZXD.js";
 import {
   CONNECTOR_RELAY_ANSWER_WITHIN_MS,
   CONNECTOR_RELAY_INSTALLATION_PATTERN,

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

@@ -6612,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");
@@ -6626,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();
@@ -6909,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");
@@ -6922,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");
@@ -7030,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,
@@ -7111,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));
@@ -7149,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) => {
@@ -7166,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"]);
@@ -7246,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;
@@ -7771,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;
@@ -7903,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;
@@ -8042,6 +8080,15 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
       return run(() => serializeInboundPreparation(store, id(data.conversationId), () => submit("remove", data)));
     }, "remove"),
     refresh: /* @__PURE__ */ __name((value) => run(() => serializeInboundPreparation(store, id(value), () => refresh(id(value)))), "refresh"),
+    // Canon refuses a feed read unless the room's mlsFeedOrdinal is its feed's last entry, and the feed reports the
+    // room's membershipRevision (devGroups.ts), so a fresh snapshot shows whether a fetch would bring anything.
+    heldCurrent: /* @__PURE__ */ __name((value, snapshot) => run(async () => {
+      const cid = id(value), latest = snapshot.mlsFeedOrdinal;
+      if (typeof latest !== "number" || !Number.isSafeInteger(latest) || snapshot.mlsRemoval !== null && snapshot.mlsRemoval !== void 0 || !await textReady(cid)) return false;
+      const held = await store.transaction(async (tx) => (await tx.get(feedKey(cid)) ?? 0) >= latest && (await tx.get(authorityKey(cid)))?.membershipRevision === snapshot.membershipRevision);
+      if (held) caughtUpAt.set(cid, context.clock());
+      return held;
+    }, false), "heldCurrent"),
     read: /* @__PURE__ */ __name((value) => run(() => read(id(value)), false), "read"),
     readVerifiedMessageBinding: /* @__PURE__ */ __name((input) => {
       const data = record5(input, ["conversationId", "messageId"]);
@@ -8105,9 +8152,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) => {
@@ -8131,12 +8181,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) => {
@@ -8152,13 +8197,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);
@@ -8385,7 +8435,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);
@@ -8801,8 +8854,11 @@ function createEndpoint(options) {
     const local = await store.transaction((tx) => tx.get(`conversation/${conversationId}`));
     const knownProtected = await store.transaction((tx) => isMlsDevRoomProtected(tx, conversationId));
     await initialization;
+    let snapshot = null;
     if (discover && (mlsDevGroups || !local && await inMlsEnvironment())) {
+      const fresh = !reads.has(canonicalEndpointJson({ name: "conversation", parameters: { conversationId } }));
       const room = await endpoint.query("conversation", { conversationId });
+      if (fresh) snapshot = room;
       if (room) await endpoint.applyConversationSnapshot(room);
       else if (!local && !knownProtected) throw new EndpointError("Conversation mode is unavailable", { code: "MLS_DEV_ROOM_MODE_UNAVAILABLE", retryable: true });
       else if (local && !(local.memberIds ?? []).includes(options.identity.principalId)) {
@@ -8820,7 +8876,9 @@ function createEndpoint(options) {
         await joinInvitedRoom(conversationId);
         return true;
       }
-      await mlsDevGroups.client.refresh(conversationId);
+      if (!snapshot || !await mlsDevGroups.client.heldCurrent(conversationId, snapshot)) {
+        await mlsDevGroups.client.refresh(conversationId);
+      }
       await createBornGroup(conversationId);
       await admitDevices(conversationId).catch((error) => {
         if (!(error instanceof EndpointError) || ["ENDPOINT_CLOSED", "PREPARATION_INSTALLATION_FENCED"].includes(error.code)) throw error;

package/dist/cli.js

@@ -22,7 +22,7 @@ import {
   runnerLockName,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-HHODEJNL.js";
+} from "./chunks/chunk-JCBQCO3F.js";
 import {
   CanonApiError,
   CanonClient,
@@ -33,7 +33,7 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-GJO7KULY.js";
+} from "./chunks/chunk-RFNYPZXD.js";
 import {
   __name,
   isCanonClientVersion

package/dist/index.js

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

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

@@ -105,6 +105,14 @@ export interface MlsDevGroupClient {
         operationId?: string;
     }): Promise<EndpointOperation>;
     refresh(conversationId: string): Promise<MlsDevGroupView | undefined>;
+    /** Whether a room snapshot Canon just returned shows nothing this device lacks of the room's feed: no entry past its
+     * cursor, the membership it last fetched under, and no held removal. Then there is nothing to fetch, and this counts
+     * as catching up on the room. */
+    heldCurrent(conversationId: string, snapshot: {
+        mlsFeedOrdinal?: unknown;
+        membershipRevision?: unknown;
+        mlsRemoval?: unknown;
+    }): Promise<boolean>;
     read(conversationId: string): Promise<MlsDevGroupView | undefined>;
     readVerifiedMessageBinding(input: {
         conversationId: string;
@@ -149,6 +157,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 +173,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,7 +18,7 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-GJO7KULY.js";
+} from "./chunks/chunk-RFNYPZXD.js";
 import "./chunks/chunk-5MI6Q3VS.js";
 export {
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "12.3.0",
+  "version": "12.3.2",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",