@canonmsg/agent-sdk 12.3.1 → 12.4.1

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,41 +209,45 @@ 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.
+
+On macOS (Apple silicon) and Linux (x64 and arm64, glibc 2.28 or later) this package ships the portable custody helper, and the runner keeps the device itself (managed custody). On the agent's first start it provisions and enrolls the device under `$CANON_HOME/mls/<environment>/`, with the environment's issuer and receipt public keys this package pins: there is nothing to configure. Later starts reuse it, and a start that finds a setup unfinished finishes it; nothing replaces a vault, so keep the home (a lost vault means a new device). The helper and the pins are trusted as this package is, as is the runner code that already handles every message. `canon-agent mls --action setup` does the same without starting a model; in library form, pass `mls: managedMlsDevice({ home, environmentId })` to `createRunner`.
+
+Elsewhere (an Intel Mac or musl; Windows is not supported), or to keep the device in custody of your own, give the runner an operator's MLS configuration with `--mls-dev-config`: a private JSON file with the custody helper, built from `mls/native` in the Canon repository, and the environment's issuer and receipt public keys, never private keys or credentials. 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
-canon-agent mls --action enroll --mls-dev-config /abs/mls-dev.json --profile dev-agent
-canon-agent mls --action publish --room <conversation id> --mls-dev-config /abs/mls-dev.json --profile dev-agent
+canon-agent run --driver claude --profile dev-agent
+canon-agent mls --action status --profile dev-agent
+canon-agent mls --action publish --room <conversation id> --profile dev-agent
 canon-agent run --driver claude --mls-dev-config /abs/mls-dev.json --profile dev-agent
 ```
 
-`canon-agent mls` runs one setup step (`status`, `provision` for portable custody, once, `enroll`, `renew`, `publish` a KeyPackage for a room before someone adds the agent, `refresh` a room) on the same home as `run`, so stop the agent first. It prints public device state and never starts a model. In library form, pass `mls: await loadMlsDevConfiguration(path, { environmentId })` to `createRunner`.
+`canon-agent mls` runs one setup step (`status`, `setup` for whatever is left of provision then enroll, `provision` for portable custody, once, `enroll`, `renew`, `publish` a KeyPackage for a room before someone adds the agent, `refresh` a room) on the same home as `run`, so stop the agent first. Each takes `--mls-dev-config` for an operator's custody. It prints public device state and never starts a model. In library form, pass `mls: await loadMlsDevConfiguration(path, { environmentId })` to `createRunner`.
 
 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.
+Without a device (no helper for the host and no `--mls-dev-config`, or no `mls` for `createRunner`), 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:
 
 ```sh
-canon-agent run --driver connector --relay-config /abs/relay.json --mls-dev-config /abs/mls-dev.json
-canon-agent mls --action provision --mls-dev-config /abs/mls-dev.json --relay-config /abs/relay.json
+canon-agent run --driver connector --relay-config /abs/relay.json
+canon-agent mls --action status --relay-config /abs/relay.json
 ```
 
-The relay configuration (a private JSON file) names the agent, where the channel to Canon's Functions listens, and the path of the channel secret. No API key is involved: when the owner enables the relay, Canon delivers the relay's own credential over that channel (it works only for the relay's encrypted-room work, and stops when the relay or its connection is revoked), and the relay keeps it in `$CANON_HOME/relay` and starts under the relay installation it names (`canon-relay:…`). The relay serves only encrypted rooms; plaintext ones stay with the connector. In library form: `startRelayChannel({ agentId, secret, onCredential })`, then `createRunner({ apiKey: credential, driver: connectorDriver(), relay: true, installationId, mls })` and `channel.serve({ runner, inbox: driver.inbox }, grantId)`. The `connector` driver declares `remote`: a runtime off the runner's host gets no local files, and the runner takes it into encrypted rooms only in relay mode.
+The relay configuration (a private JSON file) names the agent, where the channel to Canon's Functions listens, and the path of the channel secret. No API key is involved: when the owner enables the relay, Canon delivers the relay's own credential over that channel (it works only for the relay's encrypted-room work, and stops when the relay or its connection is revoked), and the relay keeps it in `$CANON_HOME/relay` and starts under the relay installation it names (`canon-relay:…`), setting up that installation's device as any runner does (or with `--mls-dev-config`). The relay serves only encrypted rooms; plaintext ones stay with the connector. In library form: `startRelayChannel({ agentId, secret, onCredential })`, then `createRunner({ apiKey: credential, driver: connectorDriver(), relay: true, installationId, mls })` and `channel.serve({ runner, inbox: driver.inbox }, grantId)`. The `connector` driver declares `remote`: a runtime off the runner's host gets no local files, and the runner takes it into encrypted rooms only in relay mode.
 
 ## Team rooms
 

package/dist/chunks/{chunk-SKFI2MJA.js → chunk-6PKXASSK.js}

@@ -8,6 +8,7 @@ import {
   MAX_PUBLIC_RUNTIME_COMMANDS,
   MLS_DEV_CREDENTIAL_MAX_BYTES,
   MLS_DEV_CREDENTIAL_RECONCILIATION_MAX_BYTES,
+  MLS_DEV_DISCLOSED_PROCESSING_FIELDS,
   MLS_DEV_ENROLLMENT_MAX_BYTES,
   MLS_DEV_GROUP_RECEIPT_CLOCK_SKEW,
   MLS_DEV_INTERACTION_LIMITS,
@@ -109,7 +110,7 @@ import {
   readMembershipChangeMetadata,
   resolveAllowedUploadMimeType,
   sanitizeDownloadFileName
-} from "./chunk-5MI6Q3VS.js";
+} from "./chunk-GWQF4WFT.js";
 
 // src/media.ts
 import { createWriteStream as createWriteStream2 } from "node:fs";
@@ -2602,6 +2603,8 @@ async function assertMlsDevPlaintextAllowed(tx, intent2, lane = "operation.reque
   }), "failure");
   const action = intent2.action === "verb_execute" ? intent2.body.verb : intent2.action;
   if (typeof action === "string" && MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS.some((unsupported) => unsupported === action)) throw failure2();
+  const disclosed = lane === "operation.request" && Object.hasOwn(MLS_DEV_DISCLOSED_PROCESSING_FIELDS, intent2.action) ? MLS_DEV_DISCLOSED_PROCESSING_FIELDS[intent2.action] : void 0;
+  if (disclosed && !intent2.envelope && Object.keys(intent2.body).every((field) => disclosed.includes(field))) return;
   const payload = lane === "operation.request" ? { body: { encoding: "json", value: intent2.body }, ...intent2.envelope ? { envelope: intent2.envelope } : {} } : intent2.body;
   let boundary;
   try {
@@ -8080,6 +8083,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"]);
@@ -8794,9 +8806,28 @@ function createEndpoint(options) {
   }
   __name(sendDeferredOpeners, "sendDeferredOpeners");
   const stubReads = /* @__PURE__ */ new Map();
+  const stubNames = /* @__PURE__ */ new Map();
   let liveActionCounter = 0;
   const liveActions = /* @__PURE__ */ new Map();
   const stubKey = /* @__PURE__ */ __name((conversationId, messageId) => `${conversationId}\0${messageId}`, "stubKey");
+  function rememberStubName(conversationId, stub) {
+    const name = typeof stub.senderName === "string" ? stub.senderName.trim() : "";
+    if (typeof stub.senderId !== "string" || !stub.senderId || !name || name === stub.senderId || name.length > 80) return;
+    const key2 = stubKey(conversationId, stub.id);
+    stubNames.delete(key2);
+    stubNames.set(key2, { senderId: stub.senderId, name });
+    if (stubNames.size > 1e3) stubNames.delete(stubNames.keys().next().value);
+  }
+  __name(rememberStubName, "rememberStubName");
+  function withStubNames(conversationId, history) {
+    const messages = history.messages;
+    if (!Array.isArray(messages)) return history;
+    return { ...history, messages: messages.map((message) => {
+      const named = typeof message.id === "string" ? stubNames.get(stubKey(conversationId, message.id)) : void 0;
+      return named && named.senderId === message.senderId ? { ...message, senderName: named.name } : message;
+    }) };
+  }
+  __name(withStubNames, "withStubNames");
   function forgetStubReads(conversationId) {
     for (const key2 of stubReads.keys()) if (key2.startsWith(`${conversationId}\0`)) stubReads.delete(key2);
   }
@@ -8814,6 +8845,7 @@ function createEndpoint(options) {
     } catch {
       return false;
     }
+    for (const stub of stubs) if (typeof stub.id === "string" && due.includes(stub.id)) rememberStubName(conversationId, { ...stub, id: stub.id });
     return store.transaction(async (tx) => {
       let changed = false;
       for (const stub of stubs) {
@@ -8845,8 +8877,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)) {
@@ -8864,7 +8899,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;
@@ -9653,7 +9690,7 @@ function createEndpoint(options) {
             const room = normalized.conversationId, read = /* @__PURE__ */ __name(() => mlsDevGroups.queryTextHistory(room, name, normalized), "read");
             const history = await read();
             const shown = (history.messages ?? []).map((entry) => entry.id).filter((id2) => typeof id2 === "string");
-            return await recoverMlsDevMessageActions(room, shown) ? await read() : history;
+            return withStubNames(room, await recoverMlsDevMessageActions(room, shown) ? await read() : history);
           }
         }
         if (name === "get_runtime_card_state" && await mlsDevInteractionRoom(normalized.conversationId, false)) {
@@ -10082,7 +10119,7 @@ async function acquireAgentEndpoint(input) {
   }
   const requestedMls = input.options.mlsDev;
   const mls = requestedMls ? await (async () => {
-    const crypto2 = await import("./mls-crypto-D5YAGYJ3.js");
+    const crypto2 = await import("./mls-crypto-LGPCXM3K.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;
@@ -14083,6 +14120,7 @@ function getCodexImagePath(attachment) {
 __name(getCodexImagePath, "getCodexImagePath");
 
 export {
+  NodeMlsDevCustodyError,
   createNodeMlsDevCustody,
   createPortableNodeMlsDevCustody,
   resolveCanonRuntimeConnection,

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

@@ -4065,6 +4065,9 @@ __name(normalizePublicRuntimeFacts, "normalizePublicRuntimeFacts");
 
 // ../backend-contracts/src/endpointContentPolicy.ts
 var MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS = ["forward_message"];
+var MLS_DEV_DISCLOSED_PROCESSING_FIELDS = {
+  generate_image: ["conversationId", "requestId", "prompt", "sourceUploadId"]
+};
 var ENDPOINT_CONTENT_ACTIONS = [
   "mls_application",
   "mls_group_control",
@@ -5381,6 +5384,7 @@ export {
   normalizePublicRuntimeDescriptor,
   normalizePublicRuntimeFacts,
   MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS,
+  MLS_DEV_DISCLOSED_PROCESSING_FIELDS,
   endpointOperationRequestRetention,
   endpointContentBoundary,
   canonicalEndpointJson,