@canonmsg/agent-sdk 12.4.1 → 12.5.1

package/README.md

@@ -192,7 +192,7 @@ 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; see [Encrypted rooms](#encrypted-rooms) |
+| `mls` | managed custody, where this package ships a helper for the host | The agent's MLS device for encrypted rooms, or `false` for none; 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 |
@@ -213,7 +213,7 @@ The CLI is `canon-agent run --driver code --module <path> [--profile <name>] [--
 
 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`.
+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. `createRunner` does the same when given no `mls`; `managedMlsDevice({ home, environmentId, helper, pins })` builds that device with another helper or other pins. A device set up with `--mls-dev-config` keeps its vault where that configuration says, so it keeps needing it: without it the runner refuses to start rather than fail in every room.
 
 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:
 
@@ -236,7 +236,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 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.
+Without a device (no helper for the host and no `--mls-dev-config`, or `mls: false` 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 (Canon-operated)
 

package/dist/chunks/{chunk-NXL4C2R6.js → chunk-3KFVBOVI.js}

@@ -30,7 +30,7 @@ import {
   sendMessageWithRetryChunked,
   splitTextByUtf8Bytes,
   verifyCanonRuntimeConnection
-} from "./chunk-6PKXASSK.js";
+} from "./chunk-TFSURFF6.js";
 import {
   CONNECTOR_RELAY_ANSWER_WITHIN_MS,
   CONNECTOR_RELAY_INSTALLATION_PATTERN,
@@ -59,7 +59,7 @@ import {
   parseMlsDevGroupHead,
   parseMlsDevGroupRoster,
   resolveAllowedUploadMimeType
-} from "./chunk-GWQF4WFT.js";
+} from "./chunk-C2WJT3VX.js";
 
 // src/runner/types.ts
 var DriverSessionError = class extends Error {
@@ -913,31 +913,43 @@ function connectorDriver() {
     },
     async claim(inputId, requestId, options = {}) {
       const entry = find(inputId);
-      if (entry.state === "claiming") {
-        if (entry.requestId !== requestId) throw new ConnectorRelayError(409, "CONNECTOR_CLAIM_CONFLICT", "This input belongs to another claim");
-        throw new ConnectorRelayError(503, "CONNECTOR_RELAY_BUSY", "This claim is still being confirmed; try again");
+      if (entry.state === "claiming" && entry.requestId !== requestId) {
+        throw new ConnectorRelayError(409, "CONNECTOR_CLAIM_CONFLICT", "This input belongs to another claim");
       }
-      if (entry.state !== "pending") {
+      if (entry.state !== "pending" && entry.state !== "claiming") {
         if (entry.requestId !== void 0 && entry.requestId !== requestId) {
           throw new ConnectorRelayError(409, "CONNECTOR_CLAIM_CONFLICT", "This input belongs to another claim");
         }
         return { inputId, requestId, runAllowed: false, state: entry.state };
       }
-      entry.state = "claiming";
-      entry.requestId = requestId;
+      if (entry.confirmation) throw new ConnectorRelayError(503, "CONNECTOR_RELAY_BUSY", "This claim is still being confirmed; retry the same request id");
+      if (entry.state === "pending") {
+        entry.state = "claiming";
+        entry.requestId = requestId;
+      }
+      const confirmation = entry.confirm().then(() => "ok", () => {
+        if (entry.state === "claiming") {
+          entry.state = "pending";
+          entry.requestId = void 0;
+        }
+        return "refused";
+      }).finally(() => {
+        entry.confirmation = void 0;
+      });
+      entry.confirmation = confirmation;
       const deadline = options.deadline ?? Date.now() + CONNECTOR_RELAY_ANSWER_WITHIN_MS;
       let timer;
       const late = new Promise((resolve3) => {
         timer = setTimeout(resolve3, Math.max(0, deadline - Date.now()), "late");
       });
-      const confirmed = await Promise.race([entry.confirm().then(() => "ok", () => "refused"), late]).finally(() => clearTimeout(timer));
-      if (entry.state === "claiming" && confirmed === "ok") {
+      const confirmed = await Promise.race([confirmation, late]).finally(() => clearTimeout(timer));
+      const state = entry.state;
+      if (state === "claiming" && confirmed === "ok") {
         entry.state = "claimed";
         return { inputId, requestId, runAllowed: true, state: "claimed", input: entry.input };
       }
-      if (entry.state !== "claiming") throw withdrawn();
-      entry.state = "pending";
-      entry.requestId = void 0;
+      if (state === "claimed") return { inputId, requestId, runAllowed: false, state: "claimed" };
+      if (state === "withdrawn" || state === "answered") throw withdrawn();
       throw new ConnectorRelayError(503, "CONNECTOR_RELAY_BUSY", "Canon could not confirm this claim now; try again");
     },
     reply: /* @__PURE__ */ __name((inputId, requestId, text3) => answer(inputId, requestId, { outcome: "reply", text: text3 }), "reply"),
@@ -952,7 +964,10 @@ function connectorDriver() {
       activity: false,
       tools: false,
       outboundFiles: false,
-      remote: true
+      remote: true,
+      // A turn here is an input waiting for (or with) the assistant, not work on this host: one per room, so a room
+      // whose assistant is away never keeps another room's input from being offered.
+      maxConcurrentTurns: Number.POSITIVE_INFINITY
     },
     inbox,
     runTurn(turn) {
@@ -1503,11 +1518,18 @@ function mlsDevRoomPackageId(identity, room) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
 }
 __name(mlsDevRoomPackageId, "mlsDevRoomPackageId");
+async function assertMlsVaultInHome(endpoint, provisioned) {
+  const { status, binding } = await endpoint.mlsDevDevice.read();
+  if (status === "absent" || status === "revoked" || provisioned({ ...binding, revision: 0 })) return;
+  throw new Error("This agent's MLS device has no vault in this home. A device set up with an operator's configuration keeps needing it: run the agent with that --mls-dev-config <path> again (in createRunner, mls: await loadMlsDevConfiguration(path, { environmentId })). A vault that was lost cannot be recovered.");
+}
+__name(assertMlsVaultInHome, "assertMlsVaultInHome");
 async function runMlsDevSetup(endpoint, action, room, provision, provisioned) {
   const identity = await endpoint.ready();
   const { environmentId } = identity, devices = endpoint.mlsDevDevice;
   if (!isMlsEnvironmentId(environmentId) || !devices || !endpoint.mlsDevKeyPackages || !endpoint.mlsDevGroups) throw new Error("MLS_DEV_SETUP_UNAVAILABLE");
   if ((action === "publish" || action === "refresh") !== !!room) throw new Error("MLS_DEV_SETUP_ARGUMENTS_INVALID");
+  if (provisioned && action !== "status") await assertMlsVaultInHome(endpoint, provisioned);
   const enroll = /* @__PURE__ */ __name(async () => {
     await devices.enroll();
     if ((await devices.read()).status !== "credential_committed") await devices.renew();
@@ -1689,6 +1711,12 @@ import { createHash as createHash6 } from "node:crypto";
 import { chmodSync, copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync as renameSync2 } from "node:fs";
 import { dirname as dirname5, join as join3 } from "node:path";
 var sha256 = /* @__PURE__ */ __name((bytes) => createHash6("sha256").update(bytes).digest("hex"), "sha256");
+function defaultMlsDevice(home, environmentId) {
+  if (!isMlsEnvironmentId(environmentId)) return void 0;
+  const helper = bundledMlsCustodyHelper();
+  return helper ? managedMlsDevice({ home, environmentId, helper }) : void 0;
+}
+__name(defaultMlsDevice, "defaultMlsDevice");
 function managedMlsDevice(options) {
   const { environmentId } = options;
   const helper = options.helper ?? bundledMlsCustodyHelper();
@@ -1849,6 +1877,8 @@ async function startRelayChannel(options) {
         return served.runner.relayRead(request.args.conversationId, { limit: request.args.limit, before: request.args.before, deadline });
       case "send":
         return served.runner.relaySend(request.args.conversationId, request.args.messageId, request.args.text, { deadline });
+      case "start":
+        return served.runner.relayStart(request.args.targetUserId, request.args.messageId, request.args.text, request.args.selection, { deadline });
     }
   }
   __name(dispatch, "dispatch");
@@ -3214,6 +3244,7 @@ __name(runtimeDescriptor, "runtimeDescriptor");
 async function createRunner(options) {
   const { driver, home } = options;
   await assertPrivateHome(home);
+  const mls = options.mls === false ? void 0 : options.mls ?? (options.endpoint ? void 0 : defaultMlsDevice(home, options.environmentId));
   const log = options.log ?? ((line) => console.error(`[canon-runner] ${line}`));
   const warn = /* @__PURE__ */ __name((what) => (error) => log(`${what}: ${error instanceof Error ? error.message : String(error)}`), "warn");
   const abortGraceMs = options.abortGraceMs ?? 1e4;
@@ -3385,6 +3416,7 @@ ${error instanceof Error ? error.message : String(error)}`;
     if (input.mls) target.mls = true;
     target.queue.push(input);
     target.turn?.live.refresh();
+    requeue(target);
     pump();
   }
   __name(offer, "offer");
@@ -3492,7 +3524,7 @@ ${error instanceof Error ? error.message : String(error)}`;
       const inputs = candidate.queue.splice(0, Math.min(MAX_INPUTS_PER_TURN, other < 0 ? MAX_INPUTS_PER_TURN : other));
       const turn = newTurn(inputs, turnId(candidate.id, inputs), candidate.id);
       candidate.turn = turn;
-      (turn.live = livePublisher(candidate, turn, encrypted ? "presence" : "status")).open();
+      (turn.live = driver.capabilities.remote ? SILENT : livePublisher(candidate, turn, encrypted ? "presence" : "status")).open();
       const done = execute(candidate, turn).catch((error) => {
         warn("turn failed")(error);
         return dispose(queued(turn), "release", "turn-failed");
@@ -3522,14 +3554,28 @@ ${error instanceof Error ? error.message : String(error)}`;
     if (turn.inputs[0].mls && !await beforeTurn(current, turn)) return;
     turn.trusted = await confirmTrusted(turn, conversation.memberIds);
     turn.notes = pendingNotes(current.id);
-    turn.contexts = await Promise.all(openErrands(current.id).map(async (record) => ({ record, encryptedOrigin: !!record.origin && await endpoint.getConversationContentMode(record.origin).then((mode) => mode === "mls-dev-text", () => false) })));
-    turn.live.setMode(turn.mls ? "presence" : driver.capabilities.streaming && resolveTurnVerbosity({ conversationType: kind }) === "verbose" ? "full" : "status");
+    turn.contexts = await Promise.all(openErrands(current.id).map(async (record) => ({ record, encryptedOrigin: !!record.origin && await endpoint.getConversationContentMode(record.origin).then((mode2) => mode2 === "mls-dev-text", () => false) })));
+    const mode = turn.mls ? "presence" : driver.capabilities.streaming && resolveTurnVerbosity({ conversationType: kind }) === "verbose" ? "full" : "status";
+    turn.live.setMode(mode);
     const history = driver.capabilities.sessionMemory === "none" ? await recentHistory(current, turn) : [];
     await materialize(current, turn);
     const bound = bindTools(current, turn);
     try {
       let work;
-      for (let live = queued(turn), waited = 0; live.length && !turn.controller.signal.aborted; ) {
+      if (driver.capabilities.remote) {
+        const live = queued(turn);
+        if (live.length && !turn.controller.signal.aborted) {
+          turn.inputs = live;
+          turn.id = turnId(current.id, live);
+          turn.pickUp = () => pickUp(current, turn, mode);
+          try {
+            work = Promise.resolve(driver.runTurn(buildTurn(current.id, turn, kind, history, bound.tools)));
+          } catch (error) {
+            work = Promise.reject(error);
+          }
+          requeue(current);
+        }
+      } else for (let live = queued(turn), waited = 0; live.length && !turn.controller.signal.aborted; ) {
         turn.inputs = live;
         turn.id = turnId(current.id, live);
         let driverTurn = buildTurn(current.id, turn, kind, history, bound.tools);
@@ -3552,15 +3598,17 @@ ${error instanceof Error ? error.message : String(error)}`;
         live = next;
       }
       if (!work) return;
-      turn.submitted = true;
-      progress(turn);
-      if (!turn.mls) void client.markAsRead(current.id).catch(warn("mark read"));
-      for (const { payload } of turn.mls ? [] : turn.inputs) {
-        if (payload.message.metadata?.inboundDisposition === "queued") {
-          void client.updateMessageDisposition(current.id, payload.message.id, "accepted_now").catch(warn("accepted_now"));
-        }
-      }
+      if (!driver.capabilities.remote) started(current, turn);
       const outcome = await outcomeOf(turn, work);
+      if (!turn.submitted) await turn.claiming?.catch(() => void 0);
+      if (!turn.submitted) {
+        turn.pickUp = void 0;
+        if (turn.reason === "requeue") return void current.queue.unshift(...queued(turn));
+        if (turn.reason) return;
+        const claim = await endpoint.startInbound(queued(turn).map((input) => input.handle), () => void 0);
+        if (claim.status !== "submitted") return await dispose(queued(turn), "release", "claim-deferred");
+        started(current, turn);
+      }
       turn.open = false;
       turn.ended.abort();
       bound.release();
@@ -3573,6 +3621,46 @@ ${error instanceof Error ? error.message : String(error)}`;
     }
   }
   __name(execute, "execute");
+  function started(current, turn) {
+    turn.submitted = true;
+    progress(turn);
+    if (!turn.mls) void client.markAsRead(current.id).catch(warn("mark read"));
+    for (const { payload } of turn.mls ? [] : turn.inputs) {
+      if (payload.message.metadata?.inboundDisposition === "queued") {
+        void client.updateMessageDisposition(current.id, payload.message.id, "accepted_now").catch(warn("accepted_now"));
+      }
+    }
+  }
+  __name(started, "started");
+  async function pickUp(current, turn, mode) {
+    const live = queued(turn);
+    if (live.length !== turn.inputs.length) {
+      abort(turn, "requeue");
+      throw turnEnded2();
+    }
+    const claiming = endpoint.startInbound(live.map((input) => input.handle), () => void 0).then((result) => {
+      if (result.status === "submitted") {
+        turn.pickUp = void 0;
+        started(current, turn);
+        if (!turn.controller.signal.aborted) (turn.live = livePublisher(current, turn, mode)).open();
+      }
+      return result;
+    });
+    turn.claiming = claiming;
+    const claim = await claiming;
+    if (claim.status !== "submitted") {
+      if (claim.status !== "deferred") abort(turn, "requeue");
+      throw new Error("The input could not be claimed now");
+    }
+  }
+  __name(pickUp, "pickUp");
+  function requeue(current) {
+    const turn = current.turn, next = current.queue[0];
+    if (!turn?.pickUp || turn.pickingUp || turn.controller.signal.aborted || !next) return;
+    if (!!next.mls !== !!turn.inputs[0].mls || turn.inputs.length >= MAX_INPUTS_PER_TURN) return;
+    abort(turn, "requeue");
+  }
+  __name(requeue, "requeue");
   async function confirmTrusted(turn, memberIds) {
     if (!trustedAgents.size || driver.capabilities.remote || options.relay) return /* @__PURE__ */ new Set();
     const candidates = turn.inputs.map(({ payload }) => payload.message).filter((message2) => message2.senderType === "ai_agent" && message2.senderId !== agentId && trustedAgents.has(message2.senderId) && (turn.mls ? true : message2.metadata?.[ACTED_FOR_OWNER] === true && message2.metadata.turnSemantics === "turn_complete" && message2.forwarded !== true));
@@ -3805,7 +3893,7 @@ ${JSON.stringify(result, null, 2)}`);
     let sending = turn.said.get(messageId);
     if (!sending) {
       turn.said.set(messageId, sending = (async () => {
-        const mls = audience ?? (await currentAudience(roomId)).audience;
+        const mls2 = audience ?? (await currentAudience(roomId)).audience;
         const record = {
           version: 1,
           turnId: messageId,
@@ -3816,7 +3904,7 @@ ${JSON.stringify(result, null, 2)}`);
           text: text3,
           options: { messageId },
           notice: false,
-          mls
+          mls: mls2
         };
         journal.save(record);
         const sent2 = await publish(record);
@@ -4052,21 +4140,21 @@ ${JSON.stringify(result, null, 2)}`);
     return await send(record.conversationId, STOPS_SHORT_NOTICE, notice, retire) === "pending" ? "pending" : "refused";
   }
   __name(publish, "publish");
-  async function send(conversationId, text3, options2, retire, record, mls = record?.mls) {
+  async function send(conversationId, text3, options2, retire, record, mls2 = record?.mls) {
     const sent = await (async () => {
       for (let attempt = 0; ; attempt += 1) {
         const files = record?.attachments?.length ?? 0;
-        const result = await untilHalt((mls ? sendEncryptedItems(mls, record?.items ?? [], retire).then(() => sendEncrypted(mls, options2.messageId, text3, retire)) : files ? sendWithFiles(record, fitGroup(text3, files), options2, retire) : sendMessageWithRetryChunked(client, conversationId, fitGroup(text3, 0), options2, { signal: retire })).then(() => "delivered", (error) => error));
+        const result = await untilHalt((mls2 ? sendEncryptedItems(mls2, record?.items ?? [], retire).then(() => sendEncrypted(mls2, options2.messageId, text3, retire)) : files ? sendWithFiles(record, fitGroup(text3, files), options2, retire) : sendMessageWithRetryChunked(client, conversationId, fitGroup(text3, 0), options2, { signal: retire })).then(() => "delivered", (error) => error));
         if (result === "delivered" || result === "pending") return result;
         if (retire?.aborted || isPendingCanonOperation(result)) return "pending";
-        if (mls ? result.retryable === false : !isRetryableCanonDeliveryError(result)) {
+        if (mls2 ? result.retryable === false : !isRetryableCanonDeliveryError(result)) {
           warn("Canon refused a reply")(result);
           return "refused";
         }
         if (await untilHalt(pause2(Math.min(3e4, 1e3 * 2 ** attempt))) === "pending") return "pending";
       }
     })();
-    if (mls) forgetGuard(mls, options2.messageId, sent);
+    if (mls2) forgetGuard(mls2, options2.messageId, sent);
     return sent;
   }
   __name(send, "send");
@@ -4200,21 +4288,28 @@ ${JSON.stringify(result, null, 2)}`);
   __name(buildTurn, "buildTurn");
   async function confirmPickup(roomId, turn, open4) {
     if (!open4()) throw turnEnded2();
-    const current = await client.getConversation(roomId);
-    if (!open4()) throw turnEnded2();
-    if (!current?.memberIds?.includes(agentId)) {
-      loseMembership(room(roomId));
-      throw new Error("The agent is no longer a member of this conversation");
-    }
-    if (turn.mls && await readAgain(() => reaudience(roomId, turn), Date.now() + CONNECTOR_RELAY_ANSWER_WITHIN_MS) === "changed") {
-      if (!turn.controller.signal.aborted) {
-        void dispose(queued(turn), "settle", "mls-obsolete-audience");
-        abort(turn, "audience");
+    turn.pickingUp = true;
+    try {
+      const current = await client.getConversation(roomId);
+      if (!open4()) throw turnEnded2();
+      if (!current?.memberIds?.includes(agentId)) {
+        loseMembership(room(roomId));
+        throw new Error("The agent is no longer a member of this conversation");
       }
-      throw new Error("Who can read this encrypted conversation changed");
+      if (turn.mls && await readAgain(() => reaudience(roomId, turn), Date.now() + CONNECTOR_RELAY_ANSWER_WITHIN_MS) === "changed") {
+        if (!turn.controller.signal.aborted) {
+          void dispose(queued(turn), "settle", "mls-obsolete-audience");
+          abort(turn, "audience");
+        }
+        throw new Error("Who can read this encrypted conversation changed");
+      }
+      if (!open4()) throw turnEnded2();
+      if (turn.pickUp) await turn.pickUp();
+      progress(turn);
+    } finally {
+      turn.pickingUp = false;
+      requeue(room(roomId));
     }
-    if (!open4()) throw turnEnded2();
-    progress(turn);
   }
   __name(confirmPickup, "confirmPickup");
   function ask(roomId, turn, sender, request) {
@@ -4396,11 +4491,11 @@ ${JSON.stringify(result, null, 2)}`);
           const mode = await endpoint.getConversationContentMode(roomId);
           if (mode !== "plaintext") target.mls = true;
           if (mode !== "plaintext" && (!mlsOn || mode !== "mls-dev-text")) refuse(roomId, mlsOn ? "protocol" : "no-device");
-          const mls = mode === "mls-dev-text" && mlsOn ? (await currentAudience(roomId)).audience : void 0;
+          const mls2 = mode === "mls-dev-text" && mlsOn ? (await currentAudience(roomId)).audience : void 0;
           const legacy = `${id}:restart`;
-          const messageId = mls && !await endpoint.getOperation(encryptedOperation(mls, legacy)) ? keyed().text("restart", roomId, id) : legacy;
-          if (mode !== "plaintext" && !mls) await settle(inputs.map(({ event }) => event.id), "interrupted-by-restart");
-          else if (await send(roomId, RESTART_NOTICE, outputOptions(id, trigger, "restart", false, messageId), void 0, void 0, mls) !== "pending") {
+          const messageId = mls2 && !await endpoint.getOperation(encryptedOperation(mls2, legacy)) ? keyed().text("restart", roomId, id) : legacy;
+          if (mode !== "plaintext" && !mls2) await settle(inputs.map(({ event }) => event.id), "interrupted-by-restart");
+          else if (await send(roomId, RESTART_NOTICE, outputOptions(id, trigger, "restart", false, messageId), void 0, void 0, mls2) !== "pending") {
             await settle(inputs.map(({ event }) => event.id), "interrupted-by-restart");
           }
         }
@@ -4933,7 +5028,7 @@ ${JSON.stringify(result, null, 2)}`);
         // Below Canon's client floor nothing can work, wherever the refusal surfaces: a query, an operation or the stream.
         ...options.onFatal ? { onClientUpdateRequired: /* @__PURE__ */ __name((error) => options.onFatal(error), "onClientUpdateRequired") } : {},
         ...options.installationId ? { installationId: options.installationId } : {},
-        ...options.mls ? { mlsDev: { configuration: options.mls.configuration, custody: options.mls.custody } } : {},
+        ...mls ? { mlsDev: { configuration: mls.configuration, custody: mls.custody } } : {},
         ...options.endpoint ? { endpoint: options.endpoint } : {},
         ...options.fetch ? { fetch: options.fetch } : {}
       });
@@ -4949,14 +5044,17 @@ ${JSON.stringify(result, null, 2)}`);
       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: give it mls (managedMlsDevice, or an operator's configuration: --mls-dev-config <path>).");
+        throw new Error(`Canon encrypts every new conversation here, and this runner has no MLS device${options.mls === void 0 && !options.endpoint ? ` (@canonmsg/agent-sdk ships no custody helper for ${process.platform}-${process.arch})` : ""}: give it an operator's configuration (--mls-dev-config <path>, or mls: await loadMlsDevConfiguration(path, { environmentId })).`);
       }
-      if (mlsOn && options.mls?.provisioned && (await endpoint.mlsDevDevice.read()).status !== "credential_committed") {
-        log("Setting up this agent's MLS device");
-        const device = await runMlsDevSetup(endpoint, "setup", void 0, options.mls.provision, options.mls.provisioned).catch((error) => {
-          throw new Error(`Could not set up this agent's MLS device: ${error instanceof Error ? error.message : String(error)}`);
-        });
-        log(`MLS device ${device.deviceId} is ${device.status}`);
+      if (mlsOn && mls?.provisioned) {
+        await assertMlsVaultInHome(endpoint, mls.provisioned);
+        if ((await endpoint.mlsDevDevice.read()).status !== "credential_committed") {
+          log("Setting up this agent's MLS device");
+          const device = await runMlsDevSetup(endpoint, "setup", void 0, mls.provision, mls.provisioned).catch((error) => {
+            throw new Error(`Could not set up this agent's MLS device: ${error instanceof Error ? error.message : String(error)}`);
+          });
+          log(`MLS device ${device.deviceId} is ${device.status}`);
+        }
       }
       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) => {
@@ -5011,10 +5109,8 @@ ${JSON.stringify(result, null, 2)}`);
       roots = outbound ? (await Promise.all(outbound.roots.map((root) => realpath5(root).catch(() => "")))).filter(Boolean) : [];
       if (driver.capabilities.tools) tools = await startToolServer();
       await recover();
-      if (!options.relay) {
-        const publisher = createRuntimeStatePublisher({ agentId, clientType: CLIENT_TYPES[driver.name], hostMode: true, rtdb: initRTDBAuth(client) });
-        heartbeat = createRuntimeHeartbeat({ publisher, getRuntime: /* @__PURE__ */ __name(() => ({ runtimeDescriptor: descriptor }), "getRuntime"), onError: warn("runtime heartbeat") });
-      }
+      const publisher = createRuntimeStatePublisher({ agentId, clientType: CLIENT_TYPES[driver.name], hostMode: true, rtdb: initRTDBAuth(client) });
+      heartbeat = createRuntimeHeartbeat({ publisher, getRuntime: /* @__PURE__ */ __name(() => ({ runtimeDescriptor: descriptor }), "getRuntime"), onError: warn("runtime heartbeat") });
       inbound = endpoint.acceptInbound({ kind: "message.created", offer, onError: warn("inbox"), ...mlsOn ? { intervalMs: 1e3 } : {} });
       inbound.start();
       let reconnect = false;
@@ -5079,7 +5175,7 @@ ${JSON.stringify(result, null, 2)}`);
         for (const unregister of guards.values()) unregister();
         guards.clear();
         await client?.close();
-        await options.mls?.close?.().catch(warn("MLS custody close"));
+        await mls?.close?.().catch(warn("MLS custody close"));
       })().finally(() => lock?.release());
       return stopping;
     },
@@ -5118,6 +5214,54 @@ ${JSON.stringify(result, null, 2)}`);
       const sent = await within(entry.sent, Math.max(0, deadline - Date.now()));
       if (sent === "refused") throw new ConnectorRelayError(409, "CONNECTOR_RELAY_SEND_REFUSED", "Canon did not accept the message; the conversation's members may have changed");
       return { conversationId, messageId, historyMessageId: id, status: sent === "delivered" ? "sent" : "pending" };
+    },
+    async relayStart(targetUserId, messageId, text3, selection, startOptions = {}) {
+      if (typeof targetUserId !== "string" || !targetUserId || targetUserId.length > 200 || targetUserId.includes("/") || typeof messageId !== "string" || !ENDPOINT_ID_PATTERN.test(messageId) || messageId.length > 120 || typeof text3 !== "string" || !text3.trim() || Buffer.byteLength(text3) > MLS_DEV_TEXT_MAX_BYTES) {
+        throw new ConnectorRelayError(400, "CONNECTOR_RELAY_INVALID", "A start needs a person or agent, a messageId and 1 byte to 32 KiB of text");
+      }
+      if (!options.relay || !client) throw new ConnectorRelayError(403, "CONNECTOR_RELAY_UNAVAILABLE", "This runner is not a relay");
+      if (!mlsOn) throw new ConnectorRelayError(503, "CONNECTOR_RELAY_NO_DEVICE", "The relay has no MLS device");
+      const deadline = startOptions.deadline ?? Date.now() + CONNECTOR_RELAY_ANSWER_WITHIN_MS;
+      const identity = { messageId, historyMessageId: `relay-start-${sha2563(messageId).slice(0, 32)}` };
+      const answer = await within(
+        endpoint.startWithheldOpener({
+          targetUserId,
+          text: text3,
+          messageId: identity.historyMessageId,
+          ...selection ? { selection } : {}
+        }).then((result2) => ({ result: result2 }), (error) => ({ error })),
+        Math.max(0, deadline - Date.now())
+      );
+      if (!answer || "error" in answer && answer.error?.retryable === true) {
+        return { ...identity, status: "starting" };
+      }
+      if ("error" in answer) {
+        const { status, code, message: message2 } = answer.error;
+        if (code === "OPERATION_ID_COLLISION") {
+          throw new ConnectorRelayError(409, "CONNECTOR_RELAY_MESSAGE_CONFLICT", "This messageId already started a conversation with other text or another person");
+        }
+        if ((status === 400 || status === 403 || status === 404 || status === 409) && typeof code === "string") {
+          throw new ConnectorRelayError(status, code, typeof message2 === "string" ? message2 : "Canon refused the start");
+        }
+        throw answer.error;
+      }
+      const result = answer.result;
+      if ("reason" in result) {
+        if (result.reason === "opening-text-required") {
+          throw new ConnectorRelayError(403, "CONNECTOR_RELAY_NOT_ENCRYPTED", "The relay serves only encrypted conversations its agent is in");
+        }
+        return { ...identity, status: result.status, reason: result.reason };
+      }
+      if ("requestId" in result) {
+        return { ...identity, status: result.status, requestId: result.requestId, ...result.conversationId ? { conversationId: result.conversationId } : {} };
+      }
+      return {
+        ...identity,
+        status: "messaged",
+        conversationId: result.conversationId,
+        ...result.created !== void 0 ? { created: result.created } : {},
+        ...result.reused !== void 0 ? { reused: result.reused } : {}
+      };
     }
   };
 }
@@ -5157,6 +5301,7 @@ export {
   runMlsDevSetup,
   MLS_ENVIRONMENT_PINS,
   bundledMlsCustodyHelper,
+  defaultMlsDevice,
   managedMlsDevice,
   startRelayChannel,
   loadRelayConfiguration,

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

@@ -4654,6 +4654,13 @@ function text4(value) {
   return value;
 }
 __name(text4, "text");
+function selection(value) {
+  const args = record3(value, ["mode"], ["conversationId"]);
+  if ((args.mode === "new" || args.mode === "latest_or_new") && args.conversationId === void 0) return { mode: args.mode };
+  if (args.mode === "specific") return { mode: "specific", conversationId: room(args.conversationId) };
+  return invalid11("selection");
+}
+__name(selection, "selection");
 function limit(value) {
   if (value === void 0) return void 0;
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 100) invalid11("limit");
@@ -4703,6 +4710,15 @@ function parseConnectorRelayRequest(value) {
       const args = record3(body.args, ["conversationId", "messageId", "text"]);
       return { ...head, op: "send", args: { conversationId: room(args.conversationId), messageId: id6(args.messageId, "messageId"), text: text4(args.text) } };
     }
+    case "start": {
+      const args = record3(body.args, ["targetUserId", "messageId", "text"], ["selection"]);
+      return { ...head, op: "start", args: {
+        targetUserId: doc(args.targetUserId, "targetUserId"),
+        messageId: id6(args.messageId, "messageId"),
+        text: text4(args.text),
+        ...args.selection === void 0 ? {} : { selection: selection(args.selection) }
+      } };
+    }
     case "credential": {
       const args = record3(body.args, ["installationId", "generation", "credential"]);
       if (!Number.isSafeInteger(args.generation) || args.generation < 1) invalid11("generation");

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

@@ -110,7 +110,7 @@ import {
   readMembershipChangeMetadata,
   resolveAllowedUploadMimeType,
   sanitizeDownloadFileName
-} from "./chunk-GWQF4WFT.js";
+} from "./chunk-C2WJT3VX.js";
 
 // src/media.ts
 import { createWriteStream as createWriteStream2 } from "node:fs";
@@ -5219,7 +5219,7 @@ function createMlsDevDeviceClient(options, context) {
   const store = guardedStore();
   const fence = /* @__PURE__ */ __name(() => store.transaction(async () => {
   }), "fence");
-  async function initialized() {
+  async function initialized(storedPrincipalId) {
     context.assertOpen();
     const { identity, installationGeneration } = await context.ready();
     await fence();
@@ -5230,7 +5230,7 @@ function createMlsDevDeviceClient(options, context) {
     const binding = parseMlsDevDeviceBinding({
       version: 1,
       environmentId: identity.environmentId,
-      principal: { ...principal, id: await context.mlsPrincipalId() },
+      principal: { ...principal, id: storedPrincipalId ?? await context.mlsPrincipalId() },
       installationId: identity.installationId
     });
     const coordinator = /* @__PURE__ */ __name((journal) => createMlsDevDeviceCoordinator({
@@ -5517,6 +5517,14 @@ function createMlsDevDeviceClient(options, context) {
     }
   }
   __name(ensureReady, "ensureReady");
+  async function revoke() {
+    const { coordinator, transport: http } = await initialized();
+    const device = coordinator(store), view3 = await device.read();
+    if (view3.status === "revoked" || !view3.registration) return view3;
+    const receipt = await http.revokeCredential({ version: 1, deviceId: view3.registration.device.deviceId }, context.signal);
+    return device.acceptRevocation(receipt);
+  }
+  __name(revoke, "revoke");
   function run(goal) {
     context.assertOpen();
     const preceding = running;
@@ -5543,12 +5551,26 @@ function createMlsDevDeviceClient(options, context) {
     return promise;
   }
   __name(run, "run");
+  function read(options2) {
+    return context.run(async () => {
+      let storedPrincipalId;
+      if (options2?.localOnly) {
+        await context.ready();
+        const saved = await store.transaction((tx) => tx.get("mls-dev-device/identity"));
+        if (!saved) return void 0;
+        storedPrincipalId = parseMlsDevDeviceBinding(saved.binding).principal.id;
+      }
+      return (await initialized(storedPrincipalId)).coordinator(store).read();
+    });
+  }
+  __name(read, "read");
   return Object.freeze({
-    read: /* @__PURE__ */ __name(() => context.run(async () => (await initialized()).coordinator(store).read()), "read"),
+    read,
     enroll: /* @__PURE__ */ __name(() => run("enroll"), "enroll"),
     renew: /* @__PURE__ */ __name(() => run("renew"), "renew"),
     reconcile: /* @__PURE__ */ __name(() => run("reconcile"), "reconcile"),
-    ensureReady: /* @__PURE__ */ __name(() => run("ready"), "ensureReady")
+    ensureReady: /* @__PURE__ */ __name(() => run("ready"), "ensureReady"),
+    revoke: /* @__PURE__ */ __name(() => context.run(revoke), "revoke")
   });
 }
 __name(createMlsDevDeviceClient, "createMlsDevDeviceClient");
@@ -7242,7 +7264,11 @@ function createMlsDevGroups(options, context, keyPackages, bridge) {
       const group = envelope((await readPreparationSnapshot(tx, scope4(conversationId))).protocolState, init.binding, conversationId);
       const accounts = mlsRoomAccounts(room, init.binding.environmentId);
       const admitted = new Set((group && !group.removed ? group.roster : []).map((entry) => mlsAccountOf(accounts, entry.device.principal)));
-      const waiting = [...Array.isArray(room.memberIds) ? room.memberIds : [], ...typeof room.mlsInviteeId === "string" ? [room.mlsInviteeId] : []].filter((memberId) => typeof memberId === "string" && !admitted.has(memberId));
+      const waiting = [.../* @__PURE__ */ new Set([
+        ...Array.isArray(room.memberIds) ? room.memberIds : [],
+        ...typeof room.mlsInviteeId === "string" ? [room.mlsInviteeId] : [],
+        ...Array.isArray(room.mlsPendingFounderIds) ? room.mlsPendingFounderIds : []
+      ])].filter((memberId) => typeof memberId === "string" && !admitted.has(memberId));
       return Object.freeze({ held: waiting.length > 0, waitingPrincipalIds: Object.freeze(waiting) });
     });
   }
@@ -9514,6 +9540,13 @@ function createEndpoint(options) {
           createdAt: timestamp,
           updatedAt: timestamp
         };
+        if (normalized.action === "start_conversation") {
+          const opener = normalized.body.opener;
+          if (opener?.withheld && typeof opener.messageId === "string") {
+            const pending = await tx.get(`${openerPrefix()}/${encodeURIComponent(opener.messageId)}`);
+            if (pending?.start?.operationId === operationId) created.openerFingerprint = pending.openerFingerprint;
+          }
+        }
         return commitOperationRecord(tx, created);
       }, "commitOperation");
       const operation = sensitive ? await store.transaction(async (tx) => {
@@ -9766,6 +9799,7 @@ function createEndpoint(options) {
     },
     async startWithheldOpener(input) {
       assertOpen();
+      input = copyJson(input);
       await initialization;
       if (typeof input.messageId !== "string" || !input.messageId || typeof input.text !== "string")
         throw new EndpointError("Invalid deferred opening line", { status: 400, code: "INVALID_DEFERRED_OPENER", retryable: false });
@@ -9776,9 +9810,16 @@ function createEndpoint(options) {
         opener: { withheld: true, messageId: input.messageId },
         ...input.selection ? { selection: copyJson(input.selection) } : {}
       };
+      const openerFingerprint = await hash3(canonicalEndpointJson([body, input.text]));
       const recordKey = `${openerPrefix()}/${encodeURIComponent(input.messageId)}`;
       await store.transaction(async (tx) => {
         await assertCurrentInstallation(tx);
+        const operation = await tx.get(key(operationId));
+        if (operation) {
+          if (operation.openerFingerprint !== openerFingerprint)
+            throw new EndpointError("Opening line ID was already used for different content", { status: 409, code: "OPERATION_ID_COLLISION", retryable: false, operationId });
+          return;
+        }
         const existing = await tx.get(recordKey);
         if (existing && (existing.text !== input.text || canonicalEndpointJson(existing.start?.body) !== canonicalEndpointJson(body)))
           throw new EndpointError("Opening line ID was already used for different content", { status: 409, code: "OPERATION_ID_COLLISION", retryable: false, operationId });
@@ -9787,6 +9828,7 @@ function createEndpoint(options) {
           messageId: input.messageId,
           text: input.text,
           requestId: null,
+          openerFingerprint,
           operationId: `send-opener-${digest.slice(0, 48)}`,
           start: { operationId, body }
         });
@@ -10119,7 +10161,7 @@ async function acquireAgentEndpoint(input) {
   }
   const requestedMls = input.options.mlsDev;
   const mls = requestedMls ? await (async () => {
-    const crypto2 = await import("./mls-crypto-LGPCXM3K.js");
+    const crypto2 = await import("./mls-crypto-Y44BOSEM.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;

package/dist/chunks/{mls-crypto-LGPCXM3K.js → mls-crypto-Y44BOSEM.js}

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

package/dist/cli.js

@@ -3,20 +3,19 @@ import {
   MLS_SETUP_ACTIONS,
   assertPrivateHome,
   awaitErrand,
-  bundledMlsCustodyHelper,
   checkCodex,
   claudeDriver,
   codeDriver,
   codexDriver,
   connectorDriver,
   createRunner,
+  defaultMlsDevice,
   errandJournal,
   errandsDirectory,
   loadClaudeQuery,
   loadInstructions,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
-  managedMlsDevice,
   queueErrand,
   readRelayCredential,
   relayRunnerHome,
@@ -24,7 +23,7 @@ import {
   runnerLockName,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-NXL4C2R6.js";
+} from "./chunks/chunk-3KFVBOVI.js";
 import {
   CanonApiError,
   CanonClient,
@@ -35,12 +34,11 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-6PKXASSK.js";
+} from "./chunks/chunk-TFSURFF6.js";
 import {
   __name,
-  isCanonClientVersion,
-  isMlsEnvironmentId
-} from "./chunks/chunk-GWQF4WFT.js";
+  isCanonClientVersion
+} from "./chunks/chunk-C2WJT3VX.js";
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
@@ -464,9 +462,7 @@ async function settings(values, { key = true } = {}) {
 __name(settings, "settings");
 async function mlsDevice(values, environmentId, home) {
   if (values["mls-dev-config"]) return loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
-  if (!isMlsEnvironmentId(environmentId)) return void 0;
-  const helper = bundledMlsCustodyHelper();
-  return helper ? managedMlsDevice({ home, environmentId, helper }) : void 0;
+  return defaultMlsDevice(home, environmentId);
 }
 __name(mlsDevice, "mlsDevice");
 async function mlsSetup(values) {

package/dist/drivers/connector.d.ts

@@ -10,7 +10,7 @@ export interface ConnectorInbox {
     /**
      * The first claim gets `runAllowed` and the turn's input, once Canon confirms the agent may still act on it (its
      * membership and the room's audience, read now, never from a hint); a repeat gets its state, never the input again.
-     * A claim that cannot be confirmed by `deadline` (epoch ms) is refused as busy and the input stays pending.
+     * A claim not confirmed by `deadline` (epoch ms) is busy; retry the same request id to finish that confirmation.
      */
     claim(inputId: string, requestId: string, options?: {
         deadline?: number;
@@ -27,8 +27,9 @@ export interface ConnectorDriver extends RuntimeDriver {
 /**
  * The `connector` driver: the runtime is an assistant its provider runs (ChatGPT, Claude.ai and the like), reached
  * through Canon's remote MCP connector, so a turn waits, as one pending input, for the assistant to claim it and answer
- * through the connector's pickup tools (spec §11.3). It keeps no timer: an assistant that never answers is the runner's
- * no-progress deadline, which a claim restarts. It never calls Canon itself; the relay channel calls its inbox, and the
- * runner confirms each claim with Canon.
+ * through the connector's pickup tools (spec §11.3). Such an assistant acts only when its user prompts it, so an input
+ * waits as long as it takes: the runner submits it, and starts its no-progress deadline, only at the claim. The driver
+ * keeps no timer. It never calls Canon itself; the relay channel calls its inbox, and the runner confirms (and submits)
+ * each claim with Canon.
  */
 export declare function connectorDriver(): ConnectorDriver;

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   runMlsDevSetup,
   runtimeDescriptor,
   startRelayChannel
-} from "./chunks/chunk-NXL4C2R6.js";
+} from "./chunks/chunk-3KFVBOVI.js";
 import {
   CanonApiError,
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
@@ -46,8 +46,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-6PKXASSK.js";
-import "./chunks/chunk-GWQF4WFT.js";
+} from "./chunks/chunk-TFSURFF6.js";
+import "./chunks/chunk-C2WJT3VX.js";
 export {
   CanonApiError,
   ConnectorRelayError,

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

@@ -1,3 +1,4 @@
+import type { DirectConversationSelection } from './communication.js';
 /**
  * The class-C relay (docs/design/agent-runner.md §11): a Canon-operated process that relays a connector agent's
  * encrypted rooms, holding an MLS device for the agent and decrypting and re-encrypting messages for the assistant (which
@@ -108,6 +109,14 @@ export type ConnectorRelayRequest = {
         messageId: string;
         text: string;
     };
+} | {
+    op: 'start';
+    args: {
+        targetUserId: string;
+        messageId: string;
+        text: string;
+        selection?: DirectConversationSelection;
+    };
 } | {
     op: 'credential';
     args: ConnectorRelayCredentialDelivery;
@@ -172,6 +181,31 @@ export interface ConnectorRelaySent {
     historyMessageId: string;
     status: 'sent' | 'pending';
 }
+/**
+ * A start (§11.5): the relay's device founds (or finds) the encrypted room and sends the opening line itself, as any
+ * device does with a withheld opener. `messageId` is the start's identity, as for a send; `historyMessageId` is the
+ * opening line's id in the room. `starting`: the outcome is unresolved, including whether local recording completed;
+ * retry with the same `messageId` until a terminal answer. Canon's answers otherwise: `messaged` (the line is going into `conversationId`),
+ * `requested` or `pending` (it goes once the request is approved), `blocked` or `unavailable`.
+ */
+export type ConnectorRelayStarted = {
+    messageId: string;
+    historyMessageId: string;
+} & ({
+    status: 'messaged';
+    conversationId: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+    conversationId?: string;
+} | {
+    status: 'starting';
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+});
 export declare class ConnectorRelayRequestError extends Error {
     name: string;
 }

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

@@ -97,7 +97,7 @@ export interface EndpointCapabilities {
     actions: string[];
     queries: string[];
     maintenance: boolean;
-    /** Only for a principal eligible for MLS here: how new rooms are born (functions `rollout.ts`, `CANON_MLS_DEV_ROOMS`). */
+    /** Only while MLS is on here, where every valid principal is eligible: how new rooms are born (functions `devActivation.ts`). */
     mls?: {
         eligible: true;
         roomMode: 'default';

package/dist/internal/endpoint/engine.d.ts

@@ -67,6 +67,8 @@ export interface EndpointOperation {
     preparedContent?: PreparedContent;
     /** Authored-input collision check, never recorded for memory-only answers. */
     inputFingerprint?: string;
+    /** Local-only binding of a withheld start's text; retained after the opener is sent or its payload is erased. */
+    openerFingerprint?: string;
     receipt?: EndpointOperationReceipt;
     attempts: number;
     attempted: boolean;
@@ -196,7 +198,9 @@ export interface Endpoint {
         text: string;
         requestId?: string | null;
     }): Promise<void>;
-    /** Persist the opening line before starting a room; recover the start through its durable receipt. */
+    /**
+     * Persist the opening line before starting a room; recover the start through its durable receipt.
+     */
     startWithheldOpener(input: Omit<StartDirectInput, 'opener'> & {
         messageId: string;
         text: string;

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

@@ -17,6 +17,11 @@ export interface MlsDevDeviceClientOptions {
 /** Explicit synthetic Dev operations. No timers, eager enrollment or room authority. */
 export interface MlsDevDeviceClient {
     read(): Promise<MlsDevDeviceView>;
+    /** Read only committed local device state, without discovering or waiting for its remote alias.
+     * Returns undefined when no local device exists. Used to capture the device before logout erases it. */
+    read(options: {
+        localOnly: true;
+    }): Promise<MlsDevDeviceView | undefined>;
     /** Ensure local registration; an existing view is not an online status check. */
     enroll(): Promise<MlsDevDeviceView>;
     renew(): Promise<MlsDevDeviceView>;
@@ -28,6 +33,10 @@ export interface MlsDevDeviceClient {
      * current credential is valid, a failed renewal returns it and is retried
      * after a minute. Never creates an unrequested enrollment. */
     ensureReady(): Promise<MlsDevDeviceView>;
+    /** Retire this registered device at Canon for good (`POST /revoke`): it can no longer authenticate, renew or be offered
+     * to a room, and readiness refuses it. A device Canon never registered has
+     * nothing to revoke; a revoked one is returned as it is. Rooms keep its leaf until Canon can remove devices (step 5c). */
+    revoke(): Promise<MlsDevDeviceView>;
 }
 /** Whether readiness would renew this registered device: it has no credential, or less than half its lifetime remains. */
 export declare function isMlsDevCredentialRenewalDue(view: MlsDevDeviceView, now: number): boolean;

package/dist/media.js

@@ -18,8 +18,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-6PKXASSK.js";
-import "./chunks/chunk-GWQF4WFT.js";
+} from "./chunks/chunk-TFSURFF6.js";
+import "./chunks/chunk-C2WJT3VX.js";
 export {
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
   DEFAULT_MEDIA_CACHE_DIR,

package/dist/runner/mls-managed.d.ts

@@ -1,4 +1,4 @@
-import type { MlsDevDeviceContext, MlsEnvironmentId } from '../internal/backend-contracts/index.js';
+import { type MlsDevDeviceContext, type MlsEnvironmentId } from '../internal/backend-contracts/index.js';
 import type { RunnerMlsOptions } from './mls.js';
 export interface ManagedMlsDeviceOptions {
     /** The runner's home (CANON_HOME, or a relay installation's home). */
@@ -28,4 +28,9 @@ export type ManagedMlsDevice = RunnerMlsOptions & {
     provisioned(context: MlsDevDeviceContext): boolean;
     close(): Promise<void>;
 };
+/**
+ * A runner's device where it is given none (`createRunner` and the CLI alike): managed custody with this package's helper
+ * for the host, or undefined where it ships none or the environment has no MLS.
+ */
+export declare function defaultMlsDevice(home: string, environmentId: string): ManagedMlsDevice | undefined;
 export declare function managedMlsDevice(options: ManagedMlsDeviceOptions): ManagedMlsDevice;

package/dist/runner/mls.d.ts

@@ -84,11 +84,17 @@ export declare function mlsDevRoomPackageId(identity: {
     installationId: string;
     ownershipVersion?: number;
 }, room: string): string;
+/**
+ * Managed custody opens only the vaults it made in its home. A device the engine store holds with no vault there (set up
+ * with an operator's configuration, or its vault lost) is refused once, here, rather than failing in every room.
+ */
+export declare function assertMlsVaultInHome(endpoint: CanonEndpoint, provisioned: (context: MlsDevDeviceContext) => boolean): Promise<void>;
 /**
  * One operator step for the agent's device (`canon-agent mls`), on the same engine store the runner uses. It never
  * starts a model, and prints only public device state: no credentials, proofs, envelopes or history. `setup` does what
  * is left of provision then enroll, so it also finishes a setup that stopped part way; it never replaces a vault, and
- * with `provisioned` (managed custody) it provisions only where this installation has none.
+ * with `provisioned` (managed custody) it provisions only where this installation has none, and refuses a device whose
+ * vault is elsewhere.
  */
 export declare function runMlsDevSetup(endpoint: CanonEndpoint, action: MlsSetupAction, room?: string, provision?: (context: MlsDevDeviceContext) => Promise<void>, provisioned?: (context: MlsDevDeviceContext) => boolean): Promise<{
     conversationId?: string | undefined;

package/dist/runner/relay.d.ts

@@ -1,9 +1,9 @@
 import { type ConnectorRelayCredentialDelivery } from '../internal/backend-contracts/index.js';
 import type { ConnectorInbox } from '../drivers/connector.js';
 import type { Runner } from './runner.js';
-/** What the channel serves: the relay's runner (history and sends) and its connector driver's inbox (pickup). */
+/** What the channel serves: the relay's runner (history, sends and starts) and its connector driver's inbox (pickup). */
 export interface RelayTarget {
-    runner: Pick<Runner, 'relayRead' | 'relaySend'>;
+    runner: Pick<Runner, 'relayRead' | 'relaySend' | 'relayStart'>;
     inbox: ConnectorInbox;
 }
 /** Canon's credential for this relay, as delivered: the connection it serves is the delivering request's. */
@@ -12,7 +12,7 @@ export type RelayCredentialDelivery = ConnectorRelayCredentialDelivery & {
 };
 export interface RelayChannelOptions {
     /** The runner and inbox to serve from the start; `serve` sets or replaces them. Until then only `credential` is answered. */
-    runner?: Pick<Runner, 'relayRead' | 'relaySend'>;
+    runner?: Pick<Runner, 'relayRead' | 'relaySend' | 'relayStart'>;
     inbox?: ConnectorInbox;
     /** The relayed agent: requests naming another agent are refused. */
     agentId: string;

package/dist/runner/runner.d.ts

@@ -1,5 +1,5 @@
 import type { AgentWakeConfiguration } from '../internal/backend-contracts/index.js';
-import { type ConnectorRelayPage, type ConnectorRelaySent } from '../internal/backend-contracts/index.js';
+import { type ConnectorRelayPage, type ConnectorRelaySent, type ConnectorRelayStarted, type DirectConversationSelection } 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';
 import { type RuntimeDriver } from './types.js';
@@ -26,16 +26,18 @@ export interface RunnerOptions {
     baseUrl?: string;
     streamUrl?: string;
     /**
-     * The agent's MLS device (Dev only, spec §6): issuer pins and custody, from `loadMlsDevConfiguration`. With it the
-     * runner takes part in encrypted rooms; without it each encrypted room is refused, once, in the log. An injected
-     * `endpoint` that already has an MLS device counts as configured. `close` runs last on shutdown.
+     * The agent's MLS device (spec §6): issuer pins and custody, from `loadMlsDevConfiguration` or `managedMlsDevice`. Left
+     * out, it is managed custody in `home` where this package ships a custody helper for the host, as the CLI's; `false` is
+     * none. With a device the runner takes part in encrypted rooms; without one each encrypted room is refused, once, in the
+     * log. An injected `endpoint` brings its own device, if any. `close` runs last on shutdown.
      */
-    mls?: RunnerMlsOptions;
+    mls?: RunnerMlsOptions | false;
     /**
      * Relay mode, the class-C relay (spec §11.4): only encrypted rooms are served, which is what lets a `remote` driver
      * (the connector) into them. Plaintext input is cancelled with no turn (the connector's own installation serves it),
-     * control hints are read only for encrypted rooms, no runtime descriptor is published, and `relayRead` and `relaySend`
-     * serve the relay channel. It needs the agent's MLS device.
+     * control hints are read only for encrypted rooms, and `relayRead` and `relaySend` serve the relay channel. It publishes
+     * the runtime descriptor and heartbeat, so the apps show a relayed turn working and offer Stop. It needs the agent's MLS
+     * device.
      */
     relay?: boolean;
     /** The engine's installation: the relay's reserved one, from its configuration. A store opened under another refuses to start. */
@@ -95,6 +97,15 @@ export interface Runner {
     relaySend(conversationId: string, messageId: string, text: string, options?: {
         deadline?: number;
     }): Promise<ConnectorRelaySent>;
+    /**
+     * Relay mode (§11.5): a conversation started with a person or agent, its opening line withheld from Canon and kept
+     * here first; this device founds (or finds) the encrypted room and sends the line. The same `messageId` is the same
+     * start. It answers by `deadline`: `starting` means unresolved, even if recording has not finished; retry the same
+     * identity until another answer arrives. Only a persisted start resumes automatically after a restart.
+     */
+    relayStart(targetUserId: string, messageId: string, text: string, selection?: DirectConversationSelection, options?: {
+        deadline?: number;
+    }): Promise<ConnectorRelayStarted>;
 }
 /** RUN-27: generated once from the driver's declarations; no static capability table. */
 export declare function runtimeDescriptor(driver: RuntimeDriver): CanonRuntimeDescriptor;

package/dist/runner/types.d.ts

@@ -36,8 +36,9 @@ export interface DriverTurn {
     tools: TurnTools;
     /**
      * For a `remote` runtime, before its input first leaves this host (the connector's claim): the runner reads the
-     * agent's membership, and an encrypted room's audience, from Canon now and counts the pickup as progress (RUN-12).
-     * It rejects, and ends the turn, when the agent may no longer act on this input; a transient failure only rejects.
+     * agent's membership, and an encrypted room's audience, from Canon now, submits the input on the first confirmed
+     * pickup (until then it is only offered, with no deadline) and counts each pickup as progress (RUN-12). It rejects,
+     * and ends the turn, when the agent may no longer act on this input; a transient failure only rejects.
      */
     confirmPickup(): Promise<void>;
 }
@@ -65,7 +66,9 @@ export interface DriverCapabilities {
     /**
      * The runtime runs off the runner's host (the class-C connector, spec §11.3): it gets no local files (inbound
      * attachments are named in the prompt, never materialized), and since its plaintext leaves this host, the runner
-     * takes it into encrypted rooms only in relay mode, whose installation discloses that.
+     * takes it into encrypted rooms only in relay mode, whose installation discloses that. Its input is offered first and
+     * submitted only when the runtime picks it up (`confirmPickup`); newer messages in the room join an input not yet
+     * picked up.
      */
     remote?: boolean;
     /** Across rooms; runner default 8. */

package/package.json

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