@canonmsg/agent-sdk 13.0.3 → 13.1.0

package/README.md

@@ -227,6 +227,8 @@ Every room is encrypted, so the runner needs the agent's MLS device, which it ke
 | `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 |
 | `sessionApprovalForDestructive` | off | Encrypted rooms: whether the owner may allow an action the runtime marks destructive for the rest of the session (CLI `--allow-session-for-destructive`) |
+| `wake` | left as registered | The agent's signed wake callback, registered at each start, or `null` to remove it; see [Waking and sleeping](#waking-and-sleeping) |
+| `idleTimeoutMs`, `onIdle` | off | `onIdle(activity)` once the runner has had nothing to do for this long; see [Waking and sleeping](#waking-and-sleeping) |
 
 `baseUrl`, `streamUrl`, `endpoint` and `fetch` are test seams; production never sets them. `codeDriver`'s second argument overrides its capabilities, such as `outboundFiles` and `maxConcurrentTurns` (default 8).
 
@@ -328,6 +330,14 @@ canon-agent errands --profile engineer --cancel <errand id>
 - **Replies.** Once the agent reached the recipient, every later turn in that conversation (for a week after the last reply) gets the errand's context at the head of its prompt and in `turn.input.errands`, so the agent knows why it is there. Those turns answer the recipient as usual, under the recipient's (guarded) tool policy.
 - **Status.** `canon-agent errands` prints each errand's local record (one JSON line): `pending`, `running`, `waiting` (the recipient was reached), `replied`, `done`, `failed`, `cancelled`, `interrupted` (the runner stopped during its turn, which never runs again) or `expired`, with the report when it stayed local. `--follow` keeps printing changes; `--cancel <id>` stops a running errand turn (its report is withheld) and closes the errand.
 
+## Waking and sleeping
+
+An agent need not run all the time. Canon can wake it, and the runner says when it has nothing to do, so its host can stop or suspend it in between ([agent-wake.md](https://github.com/HeyBobChan/canon/blob/main/docs/agent-wake.md)).
+
+- **Wake.** `wake: { callbackUrl, secret, conversationIds }` (CLI `--wake-config <file>`) registers, at each start, a public HTTPS callback for up to 32 rooms. When a person types in one, or a message arrives there, Canon POSTs it a signed [Standard Webhooks](https://www.standardwebhooks.com/) request whose body is only `{"type":"wake","reason":"typing"|"event"}`: no room, sender or content. The host starts or resumes the agent and answers 2xx once it is ready; the agent then reads its input as usual. The secret is `whsec_` and the padded base64 of 32 random bytes (`echo "whsec_$(openssl rand -base64 32)"`). Canon first sends the URL a signed `{"type":"verification","challenge":"…"}`, which must be answered with `{"challenge":"…"}` and wake nothing, and the start fails if it is not. `wake: null` (`--wake-off`) removes the callback; leaving it out leaves it as it is.
+- **Idle.** `runner.activity()` reports what the runner has in hand, as counts: running `turns`, `inputs` waiting for one, `errands` waiting, and `outbound` operations Canon has not answered yet (a reply waiting out an outage counts). It is `idle` when all are 0. With `idleTimeoutMs` (at least 1 s), `onIdle(activity)` is called once the runner has been idle that long, and again only after new activity. The CLI's `--idle-timeout 10m` stops gracefully and exits 0 then.
+- **What a host must add.** Typing reaches the host's callback, not the runner, so a host keeps the agent awake while a person types (Canon sends at most one typing hint per room every 10 s while they do). A wake that arrives just as the runner goes idle can leave its input in the inbox: a host that has received a wake since the runner last reported idle starts it again. Errands written while the agent is stopped run at its next start.
+
 ## Registration
 
 `ensureAgentProfile` registers an agent and keeps its key in `$CANON_HOME/agents.json` (default `~/.canon`), as a profile the CLI can use with `--profile`. It reuses an environment-bound profile, resumes the exact saved approval request, persists credentials before acknowledging delivery, and retries an interrupted acknowledgement on the next call. `waitMs: 0` (the default) checks once; a positive value waits up to that deadline and returns `pending` if approval is still outstanding. See the [complete runnable quickstart](https://canonmail.com/agents/build#run-a-complete-agent).

package/dist/chunks/{chunk-XKUG2BQR.js → chunk-IEKVS7AN.js}

@@ -262,9 +262,9 @@ function stdioRpc(child, handlers, { name, envelope }) {
     }, PIPE_GRACE_MS).unref();
   });
   return {
-    call: /* @__PURE__ */ __name((method, params) => new Promise((resolve3, reject) => {
+    call: /* @__PURE__ */ __name((method, params) => new Promise((resolve4, reject) => {
       next += 1;
-      pending.set(next, { resolve: /* @__PURE__ */ __name((value) => resolve3(isRecord(value) ? value : {}), "resolve"), reject });
+      pending.set(next, { resolve: /* @__PURE__ */ __name((value) => resolve4(isRecord(value) ? value : {}), "resolve"), reject });
       write({ id: next, method, params });
     }), "call"),
     notify: /* @__PURE__ */ __name((method, params) => write({ method, ...params ? { params } : {} }), "notify"),
@@ -341,11 +341,11 @@ async function checkAcp({ command, args = [], cwd, timeoutMs = 3e4 }) {
   const link = stdioRpc(child, { notify: /* @__PURE__ */ __name(() => void 0, "notify"), request: /* @__PURE__ */ __name((method) => refuseMethod(method), "request") }, { name: basename(command), envelope: { jsonrpc: "2.0" } });
   let timer;
   try {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       timer = setTimeout(() => reject(new Error(`${command} did not answer the Agent Client Protocol's initialize within ${timeoutMs / 1e3} s`)), timeoutMs);
       child.once("error", (error) => reject(new Error(`Could not run ${command}: ${error.message}`)));
       child.once("close", () => reject(new Error(`${command} exited before answering the Agent Client Protocol's initialize`)));
-      initialize(link, command).then(({ capabilities, info }) => resolve3({
+      initialize(link, command).then(({ capabilities, info }) => resolve4({
         name: text(info.title) || text(info.name) || basename(command),
         version: text(info.version),
         sessionMemory: restoreMethod(capabilities) ? "native" : "none"
@@ -401,8 +401,8 @@ function acpDriver(options) {
       if (guest && options.guestMode === void 0 && !options.unguardedGuests) return { reply: OWNER_ONLY };
       const child = startAgent(command, args, cwd);
       let exit = /* @__PURE__ */ __name(() => void 0, "exit");
-      const exited = new Promise((resolve3) => {
-        exit = resolve3;
+      const exited = new Promise((resolve4) => {
+        exit = resolve4;
       });
       let killing;
       let stopping = false;
@@ -413,7 +413,7 @@ function acpDriver(options) {
       }, "close"), exited };
       running.set(turn.session, entry);
       const server = `${CANON}_${randomBytes(4).toString("hex")}`;
-      return new Promise((resolve3, reject) => {
+      return new Promise((resolve4, reject) => {
         const messages = [];
         const calls = /* @__PURE__ */ new Map();
         let sessionId = "";
@@ -439,7 +439,7 @@ function acpDriver(options) {
           finish();
           if (turn.signal.aborted) reject(turn.signal.reason);
           else if (outcome instanceof Error) reject(outcome);
-          else resolve3(outcome);
+          else resolve4(outcome);
         }, "settle");
         const stopGuest = /* @__PURE__ */ __name((what) => {
           link.notify("session/cancel", { sessionId });
@@ -532,10 +532,10 @@ ${text(item.newText)}`);
         child.once("exit", () => {
           if (stopping || guest || turn.signal.aborted) {
             signalAgent(child, "SIGTERM");
-            ended = new Promise((resolve4) => {
+            ended = new Promise((resolve5) => {
               setTimeout(() => {
                 signalAgent(child, "SIGKILL");
-                resolve4();
+                resolve5();
               }, KILL_AFTER_MS);
             });
           }
@@ -789,8 +789,8 @@ function claudeDriver(options) {
       const resume = turn.state.get(SESSION2);
       const native = query({ prompt: turn.prompt, options: queryOptions(turn, resume) });
       let exit = /* @__PURE__ */ __name(() => void 0, "exit");
-      const entry = { close: /* @__PURE__ */ __name(() => native.close(), "close"), exited: new Promise((resolve3) => {
-        exit = resolve3;
+      const entry = { close: /* @__PURE__ */ __name(() => native.close(), "close"), exited: new Promise((resolve4) => {
+        exit = resolve4;
       }) };
       running.set(turn.session, entry);
       let closing;
@@ -803,7 +803,7 @@ function claudeDriver(options) {
       }, "interrupt");
       turn.signal.addEventListener("abort", interrupt, { once: true });
       const reader = liveReader(turn);
-      return new Promise((resolve3, reject) => void (async () => {
+      return new Promise((resolve4, reject) => void (async () => {
         let session = resume;
         let started = false;
         let finished = false;
@@ -820,7 +820,7 @@ function claudeDriver(options) {
             closeLater();
             if (message2.subtype === "success" && !message2.is_error) {
               const reply = message2.result.trim() ? message2.result : reader.text();
-              resolve3({ reply: reply.trim() ? reply : null });
+              resolve4({ reply: reply.trim() ? reply : null });
             } else {
               const detail = message2.subtype === "success" ? message2.result : message2.errors.join("; ");
               reject(failed(new Error(`Claude Code ended the turn with ${message2.subtype}${detail ? `: ${oneLine2(detail, 300)}` : ""}`)));
@@ -1112,14 +1112,14 @@ function codexDriver(options) {
       const cli = installedCli(codexPath);
       const child = spawn3(cli.file, [...cli.args, "app-server", "--listen", "stdio://"], { cwd, env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
       let exit = /* @__PURE__ */ __name(() => void 0, "exit");
-      const exited = new Promise((resolve3) => {
-        exit = resolve3;
+      const exited = new Promise((resolve4) => {
+        exit = resolve4;
       });
       const entry = { close: /* @__PURE__ */ __name(() => {
         stopCli(child);
       }, "close"), exited };
       running.set(turn.session, entry);
-      return new Promise((resolve3, reject) => {
+      return new Promise((resolve4, reject) => {
         const messages = /* @__PURE__ */ new Map();
         const items = /* @__PURE__ */ new Map();
         const completed = /* @__PURE__ */ new Map();
@@ -1145,7 +1145,7 @@ function codexDriver(options) {
           finish();
           if (turn.signal.aborted) reject(turn.signal.reason);
           else if (outcome instanceof Error) reject(outcome);
-          else resolve3(outcome);
+          else resolve4(outcome);
         }, "settle");
         const conclude = /* @__PURE__ */ __name(() => {
           const ended = completed.get(nativeTurn);
@@ -1343,8 +1343,8 @@ function connectorDriver() {
       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 late = new Promise((resolve4) => {
+        timer = setTimeout(resolve4, Math.max(0, deadline - Date.now()), "late");
       });
       const confirmed = await Promise.race([confirmation, late]).finally(() => clearTimeout(timer));
       const state = entry.state;
@@ -1383,7 +1383,7 @@ function connectorDriver() {
       ])).digest("hex").slice(0, 40)}`;
       const input = fitInput(inputId, turn);
       if (!input) return Promise.reject(new Error(TOO_LARGE));
-      return new Promise((resolve3, reject) => {
+      return new Promise((resolve4, reject) => {
         const entry = {
           ref: { inputId, conversationId: turn.input.conversationId, messageId: messages.at(-1).id, createdAt: messages.at(-1).createdAt },
           session: turn.session,
@@ -1393,9 +1393,9 @@ function connectorDriver() {
           finish: /* @__PURE__ */ __name((result) => {
             turn.signal.removeEventListener("abort", onAbort);
             if (result instanceof Error) reject(result);
-            else if (result.outcome === "reply") resolve3({ reply: result.text });
+            else if (result.outcome === "reply") resolve4({ reply: result.text });
             else if (result.outcome === "failed") reject(new Error(FAILED));
-            else resolve3({ reply: null });
+            else resolve4({ reply: null });
           }, "finish")
         };
         const onAbort = /* @__PURE__ */ __name(() => withdraw(entry, turn.signal.reason), "onAbort");
@@ -1531,7 +1531,7 @@ var answered = /* @__PURE__ */ __name((kind, record) => record.status !== "sendi
 async function awaitErrand(directory, command, ms) {
   const journal = errandJournal(directory);
   let record;
-  for (const deadline = Date.now() + ms; Date.now() < deadline; await new Promise((resolve3) => setTimeout(resolve3, 200))) {
+  for (const deadline = Date.now() + ms; Date.now() < deadline; await new Promise((resolve4) => setTimeout(resolve4, 200))) {
     record = journal.get(command.id);
     if (record && answered(command.kind, record)) break;
   }
@@ -2161,9 +2161,9 @@ function managedMlsDevice(options) {
   }
   __name(device, "device");
   const custody2 = {
-    prepareProtected: /* @__PURE__ */ __name((context, ...rest) => device(context, false).then((open4) => open4.prepareProtected(context, ...rest)), "prepareProtected"),
-    prepareProtectedKeyPackage: /* @__PURE__ */ __name((context, ...rest) => device(context, false).then((open4) => open4.prepareProtectedKeyPackage(context, ...rest)), "prepareProtectedKeyPackage"),
-    prepareProtectedGroup: /* @__PURE__ */ __name((identity, ...rest) => device(identity, false).then((open4) => open4.prepareProtectedGroup(identity, ...rest)), "prepareProtectedGroup")
+    prepareProtected: /* @__PURE__ */ __name((context, ...rest) => device(context, false).then((open5) => open5.prepareProtected(context, ...rest)), "prepareProtected"),
+    prepareProtectedKeyPackage: /* @__PURE__ */ __name((context, ...rest) => device(context, false).then((open5) => open5.prepareProtectedKeyPackage(context, ...rest)), "prepareProtectedKeyPackage"),
+    prepareProtectedGroup: /* @__PURE__ */ __name((identity, ...rest) => device(identity, false).then((open5) => open5.prepareProtectedGroup(identity, ...rest)), "prepareProtectedGroup")
   };
   return {
     configuration,
@@ -2181,7 +2181,7 @@ function managedMlsDevice(options) {
       return false;
     },
     async close() {
-      await Promise.allSettled([...devices.values()].map((open4) => open4.then((custody3) => custody3.close())));
+      await Promise.allSettled([...devices.values()].map((open5) => open5.then((custody3) => custody3.close())));
     }
   };
 }
@@ -2685,15 +2685,15 @@ import { createHash as createHash7 } from "node:crypto";
 import { readdirSync as readdirSync3, readFileSync as readFileSync5, rmSync } from "node:fs";
 import { join as join6 } from "node:path";
 var sha2562 = /* @__PURE__ */ __name((value) => createHash7("sha256").update(value).digest("hex"), "sha256");
-var pause = /* @__PURE__ */ __name((ms) => new Promise((resolve3) => {
-  setTimeout(resolve3, ms).unref?.();
+var pause = /* @__PURE__ */ __name((ms) => new Promise((resolve4) => {
+  setTimeout(resolve4, ms).unref?.();
 }), "pause");
-var pauseUnless = /* @__PURE__ */ __name((ms, signal) => new Promise((resolve3) => {
-  if (signal.aborted) return resolve3();
+var pauseUnless = /* @__PURE__ */ __name((ms, signal) => new Promise((resolve4) => {
+  if (signal.aborted) return resolve4();
   const done = /* @__PURE__ */ __name(() => {
     clearTimeout(timer);
     signal.removeEventListener("abort", done);
-    resolve3();
+    resolve4();
   }, "done");
   const timer = setTimeout(done, ms);
   timer.unref?.();
@@ -2986,14 +2986,14 @@ function createMlsAsks(options, approvalScope2) {
         }
       }
       if (signal.aborted) throw ended();
-      await new Promise((resolve3) => {
+      await new Promise((resolve4) => {
         const timer = setTimeout(done, Math.max(0, Math.min(pollMs, expiresAtMs - Date.now())));
         timer.unref?.();
         function done() {
           clearTimeout(timer);
           signal.removeEventListener("abort", done);
           card.wake = () => void 0;
-          resolve3();
+          resolve4();
         }
         __name(done, "done");
         card.wake = done;
@@ -3004,12 +3004,12 @@ function createMlsAsks(options, approvalScope2) {
   __name(wait, "wait");
   function bounded(card, work) {
     const { expiresAtMs, signal } = card.input;
-    return new Promise((resolve3, reject) => {
-      const stop = /* @__PURE__ */ __name(() => resolve3(void 0), "stop");
+    return new Promise((resolve4, reject) => {
+      const stop = /* @__PURE__ */ __name(() => resolve4(void 0), "stop");
       const timer = setTimeout(stop, Math.max(0, expiresAtMs - Date.now()));
       timer.unref?.();
       signal.addEventListener("abort", stop, { once: true });
-      work.then(resolve3, reject).finally(() => {
+      work.then(resolve4, reject).finally(() => {
         clearTimeout(timer);
         signal.removeEventListener("abort", stop);
       });
@@ -3058,11 +3058,11 @@ function createMlsAsks(options, approvalScope2) {
           throw error;
         });
       })();
-      return new Promise((resolve3, reject) => {
+      return new Promise((resolve4, reject) => {
         const stop = /* @__PURE__ */ __name(() => reject(turnEnded()), "stop");
         if (signal.aborted) stop();
         else signal.addEventListener("abort", stop, { once: true });
-        work.then(resolve3, reject).finally(() => signal.removeEventListener("abort", stop));
+        work.then(resolve4, reject).finally(() => signal.removeEventListener("abort", stop));
       });
     },
     wake,
@@ -3158,9 +3158,9 @@ async function startToolServer() {
       if (!response.headersSent) response.writeHead(500).end();
     });
   });
-  await new Promise((resolve3, reject) => {
+  await new Promise((resolve4, reject) => {
     http.once("error", reject);
-    http.listen(0, "127.0.0.1", resolve3);
+    http.listen(0, "127.0.0.1", resolve4);
   });
   const { port } = http.address();
   return {
@@ -3171,10 +3171,10 @@ async function startToolServer() {
         turns.delete(token);
       }, "release") };
     },
-    close: /* @__PURE__ */ __name(() => new Promise((resolve3) => {
+    close: /* @__PURE__ */ __name(() => new Promise((resolve4) => {
       turns.clear();
       http.closeAllConnections();
-      http.close(() => resolve3());
+      http.close(() => resolve4());
     }), "close")
   };
 }
@@ -3183,6 +3183,9 @@ __name(startToolServer, "startToolServer");
 // src/runner/runner.ts
 var STOPS = ["stop", "drop", "new_session", "membership", "audience"];
 var MAX_INPUTS_PER_TURN = 20;
+var OUTBOUND_UNANSWERED = ["queued", "sending", "deferred", "pending"];
+var INBOUND_UNSETTLED = ["observed", "deferred", "offered"];
+var ACTIVITY_COUNT_LIMIT = 1e3;
 var CLAIM_RETRY_MS = 250;
 var CLAIM_PATIENCE_MS = 2e4;
 var HISTORY_WINDOW = 20;
@@ -3248,14 +3251,14 @@ var toolText = /* @__PURE__ */ __name((text3, isError = false) => ({ content: [{
 var turnEnded2 = /* @__PURE__ */ __name(() => new DOMException("This turn has ended", "AbortError"), "turnEnded");
 function within(promise, ms) {
   let timer;
-  const expiry = new Promise((resolve3) => {
-    timer = setTimeout(resolve3, ms, void 0);
+  const expiry = new Promise((resolve4) => {
+    timer = setTimeout(resolve4, ms, void 0);
   });
   return Promise.race([promise, expiry]).finally(() => clearTimeout(timer));
 }
 __name(within, "within");
-var pause2 = /* @__PURE__ */ __name((ms) => new Promise((resolve3) => {
-  setTimeout(resolve3, ms).unref?.();
+var pause2 = /* @__PURE__ */ __name((ms) => new Promise((resolve4) => {
+  setTimeout(resolve4, ms).unref?.();
 }), "pause");
 function agentRun(turns) {
   const history = turns.map(({ senderId, senderType }) => senderType === "ai_agent" ? { senderId, senderType, metadata: { turnSemantics: "turn_complete" } } : { senderId, senderType: "human" });
@@ -3432,6 +3435,11 @@ async function createRunner(options) {
   const maxTurns = driver.capabilities.maxConcurrentTurns ?? 8;
   const agentTurnCap = options.agentTurnCap ?? 6;
   if (!Number.isSafeInteger(agentTurnCap) || agentTurnCap < 0 || agentTurnCap > 1e3) throw new Error("agentTurnCap must be a whole number from 0 to 1000");
+  const { idleTimeoutMs, onIdle } = options;
+  if (idleTimeoutMs === void 0 !== (onIdle === void 0)) throw new Error("idleTimeoutMs and onIdle go together");
+  if (idleTimeoutMs !== void 0 && (!Number.isSafeInteger(idleTimeoutMs) || idleTimeoutMs < 1e3)) {
+    throw new Error("idleTimeoutMs must be a whole number of milliseconds, at least 1000");
+  }
   const names = /* @__PURE__ */ __name((list, what) => {
     if (list !== void 0 && (!Array.isArray(list) || list.some((name) => typeof name !== "string" || !name.trim() || name.length > 200))) {
       throw new Error(`${what} must be a list of non-empty names`);
@@ -3484,13 +3492,90 @@ async function createRunner(options) {
   const halt = new AbortController();
   const untilHalt = /* @__PURE__ */ __name((work) => {
     let stop = /* @__PURE__ */ __name(() => void 0, "stop");
-    const halted = new Promise((resolve3) => {
-      stop = /* @__PURE__ */ __name(() => resolve3("pending"), "stop");
+    const halted = new Promise((resolve4) => {
+      stop = /* @__PURE__ */ __name(() => resolve4("pending"), "stop");
       if (halt.signal.aborted) stop();
       else halt.signal.addEventListener("abort", stop, { once: true });
     });
     return Promise.race([work, halted]).finally(() => halt.signal.removeEventListener("abort", stop));
   }, "untilHalt");
+  let lastActiveAt = Date.now();
+  let idleCalled = false;
+  let offering = 0;
+  let calls = 0;
+  const touch = /* @__PURE__ */ __name(() => {
+    lastActiveAt = Date.now();
+    idleCalled = false;
+  }, "touch");
+  async function activeCall(work) {
+    calls += 1;
+    touch();
+    try {
+      return await work();
+    } finally {
+      calls -= 1;
+      touch();
+    }
+  }
+  __name(activeCall, "activeCall");
+  function ownActivity() {
+    let turns = running.size;
+    let queued2 = offering;
+    for (const current of rooms.values()) {
+      queued2 += current.queue.length;
+      if (current.recovering) turns += 1;
+      if (current.resetting) turns += 1;
+    }
+    let errandsWaiting = 0;
+    for (const record of errandsById.values()) if (record.status === "pending") errandsWaiting += 1;
+    return { turns, queued: queued2, errands: errandsWaiting, sending: posting.size + calls };
+  }
+  __name(ownActivity, "ownActivity");
+  async function activity() {
+    if (stopping) throw new Error("The runner is stopping");
+    if (!inbound) throw new Error("Start the runner first");
+    const [operations, records] = await Promise.all([
+      endpoint.listOperations({ statuses: [...OUTBOUND_UNANSWERED], limit: ACTIVITY_COUNT_LIMIT }),
+      endpoint.listInbound({ states: [...INBOUND_UNSETTLED], limit: ACTIVITY_COUNT_LIMIT })
+    ]);
+    const own = ownActivity();
+    const unsettled = records.filter(({ event, deleted, externalClaim }) => event.kind === "message.created" && !deleted && !externalClaim).length;
+    const inputs = Math.max(own.queued, unsettled);
+    const outbound = own.sending + operations.length;
+    const idle = own.turns === 0 && inputs === 0 && own.errands === 0 && outbound === 0;
+    if (!idle) touch();
+    return { idle, lastActiveAt, turns: own.turns, inputs, errands: own.errands, outbound };
+  }
+  __name(activity, "activity");
+  function watchIdle() {
+    if (idleTimeoutMs === void 0) return;
+    let checking = false;
+    const check = /* @__PURE__ */ __name(async () => {
+      if (checking || stopping || idleCalled) return;
+      const own = ownActivity();
+      if (own.turns || own.queued || own.errands || own.sending) return touch();
+      checking = true;
+      try {
+        const now = await activity();
+        if (now.idle && !stopping && !idleCalled && Date.now() - lastActiveAt >= idleTimeoutMs) {
+          idleCalled = true;
+          try {
+            onIdle(now);
+          } catch (error) {
+            warn("onIdle")(error);
+          }
+        }
+      } catch (error) {
+        if (!stopping) warn("idle check")(error);
+      } finally {
+        checking = false;
+      }
+    }, "check");
+    const timer = setInterval(() => void check(), Math.min(3e4, Math.max(1e3, Math.floor(idleTimeoutMs / 4))));
+    timer.unref?.();
+    detach.push(() => clearInterval(timer));
+  }
+  __name(watchIdle, "watchIdle");
   const room = /* @__PURE__ */ __name((id) => {
     let found = rooms.get(id);
     if (!found) rooms.set(id, found = { id, queue: [], errands: [], controls: Promise.resolve(), lane: Promise.resolve() });
@@ -3569,9 +3654,21 @@ ${error instanceof Error ? error.message : String(error)}`;
   }
   __name(progress, "progress");
   async function offer(event) {
+    offering += 1;
+    touch();
+    try {
+      await take(event);
+    } finally {
+      offering -= 1;
+      touch();
+    }
+  }
+  __name(offer, "offer");
+  async function take(event) {
     const handle = await endpoint.acquireInbound(event.id);
     if (!handle) return;
     const roomId = event.data.conversationId ?? "";
+    const clears = rooms.get(roomId)?.clears;
     const input = await admitInput(event, handle).catch(async (error) => {
       deferredNote(roomId)(error);
       await handle.release("not-admitted-yet");
@@ -3580,11 +3677,12 @@ ${error instanceof Error ? error.message : String(error)}`;
     if (!input) return;
     if (stopping) return void await handle.release("runner-stopping");
     const target = room(input.payload.conversationId);
+    if (target.clears !== clears) return void await dispose([input], "cancel", "stop-and-clear");
     target.queue.push(input);
     requeue(target);
     pump();
   }
-  __name(offer, "offer");
+  __name(take, "take");
   async function admitInput(event, handle) {
     const payload = event.data;
     const { conversationId } = payload;
@@ -3735,11 +3833,13 @@ ${decision.reasonCode}`;
         turn.live.end("ended");
         if (candidate.turn === turn) candidate.turn = void 0;
         running.delete(done);
+        touch();
         rooms.delete(candidate.id);
         rooms.set(candidate.id, candidate);
         pump();
       });
       running.add(done);
+      touch();
     }
     while (localErrands.length && !stopping && running.size < maxTurns) startErrand(void 0, localErrands.shift());
   }
@@ -4170,9 +4270,9 @@ ${JSON.stringify(result, null, 2)}`);
   async function outcomeOf(turn, work) {
     const signal = turn.controller.signal;
     const settled = work.then((result) => ({ result }), (error) => ({ error }));
-    const aborted = new Promise((resolve3) => {
-      if (signal.aborted) resolve3(void 0);
-      else signal.addEventListener("abort", () => resolve3(void 0), { once: true });
+    const aborted = new Promise((resolve4) => {
+      if (signal.aborted) resolve4(void 0);
+      else signal.addEventListener("abort", () => resolve4(void 0), { once: true });
     });
     const first = await Promise.race([settled, aborted]);
     if (first && !signal.aborted) return first;
@@ -4414,8 +4514,8 @@ ${JSON.stringify(result, null, 2)}`);
       ...turn.facts ? { roomFacts: turn.facts } : {}
     });
     const line = /* @__PURE__ */ __name((message2, mark = "") => promptLine(message2, message2.senderId === agentId ? "You" : message2.senderName ?? message2.senderId, turn.media.get(message2.id), mark), "line");
-    const open4 = /* @__PURE__ */ __name(() => turn.open && !turn.controller.signal.aborted, "open");
-    const live = /* @__PURE__ */ __name(() => open4() && !turn.silenced, "live");
+    const open5 = /* @__PURE__ */ __name(() => turn.open && !turn.controller.signal.aborted, "open");
+    const live = /* @__PURE__ */ __name(() => open5() && !turn.silenced, "live");
     return {
       session: turn.session,
       // §12.6: an errand turn's prompt is its errand; the owner's message is only its input's record.
@@ -4437,18 +4537,18 @@ ${JSON.stringify(result, null, 2)}`);
         if (live()) progress(turn);
       }, "onActivity"),
       ask: /* @__PURE__ */ __name((request) => live() ? ask(roomId, turn, input.sender, request) : Promise.reject(turnEnded2()), "ask"),
-      state: driverState(turn.session, open4),
+      state: driverState(turn.session, open5),
       tools: tools2,
-      confirmPickup: /* @__PURE__ */ __name(() => confirmPickup(roomId, turn, open4), "confirmPickup")
+      confirmPickup: /* @__PURE__ */ __name(() => confirmPickup(roomId, turn, open5), "confirmPickup")
     };
   }
   __name(buildTurn, "buildTurn");
-  async function confirmPickup(roomId, turn, open4) {
-    if (!open4()) throw turnEnded2();
+  async function confirmPickup(roomId, turn, open5) {
+    if (!open5()) throw turnEnded2();
     turn.pickingUp = true;
     try {
       const current = await client.getConversation(roomId);
-      if (!open4()) throw turnEnded2();
+      if (!open5()) throw turnEnded2();
       if (!current?.memberIds?.includes(agentId)) {
         loseMembership(room(roomId));
         throw new Error("The agent is no longer a member of this conversation");
@@ -4460,7 +4560,7 @@ ${JSON.stringify(result, null, 2)}`);
         }
         throw new Error("Who can read this encrypted conversation changed");
       }
-      if (!open4()) throw turnEnded2();
+      if (!open5()) throw turnEnded2();
       if (turn.pickUp) await turn.pickUp();
       progress(turn);
     } finally {
@@ -4552,9 +4652,13 @@ ${JSON.stringify(result, null, 2)}`);
   async function control(current) {
     const consumed = await client.consumeRuntimeSignal(current.id);
     if (consumed.status !== "signal") return;
+    touch();
     const signal = consumed.signal;
     const turn = current.turn;
-    if (signal === "stop_and_drop" || signal === "new_session") void dispose(current.queue.splice(0), "cancel", "stop-and-clear");
+    if (signal === "stop_and_drop" || signal === "new_session") {
+      current.clears = (current.clears ?? 0) + 1;
+      void dispose(current.queue.splice(0), "cancel", "stop-and-clear");
+    }
     if (turn) {
       void dispose(turn.inputs, "cancel", "stopped-before-submit");
       abort(turn, signal === "interrupt" ? "stop" : signal === "stop_and_drop" ? "drop" : "new_session");
@@ -4568,6 +4672,7 @@ ${JSON.stringify(result, null, 2)}`);
       const reset = Promise.all([...sessions].map((session) => resetSession(session).catch(warn("session reset")))).then(() => void 0);
       await (current.resetting = reset.finally(() => {
         current.resetting = void 0;
+        touch();
         pump();
       }));
     }
@@ -4611,6 +4716,7 @@ ${JSON.stringify(result, null, 2)}`);
       })().catch(warn("restart recovery"));
       target.recovering = work.finally(() => {
         target.recovering = void 0;
+        touch();
         pump();
       });
     }
@@ -4738,7 +4844,11 @@ ${JSON.stringify(result, null, 2)}`);
       if (sent !== "pending") finishErrandOutput(record, sent);
     }, warn(`errand ${id}`));
     posting.add(delivery);
-    void delivery.finally(() => posting.delete(delivery));
+    touch();
+    void delivery.finally(() => {
+      posting.delete(delivery);
+      touch();
+    });
     return true;
   }
   __name(takeErrand, "takeErrand");
@@ -4784,6 +4894,7 @@ ${JSON.stringify(result, null, 2)}`);
   __name(saveErrand, "saveErrand");
   function enqueueErrand(record) {
     (record.origin ? room(record.origin).errands : localErrands).push(record);
+    touch();
     pump();
   }
   __name(enqueueErrand, "enqueueErrand");
@@ -4821,10 +4932,10 @@ ${JSON.stringify(result, null, 2)}`);
   }
   __name(contextPrompt, "contextPrompt");
   function openErrands(roomId) {
-    const open4 = [...errandsById.values()].filter((record) => record.conversationId === roomId && openErrand(record));
-    const stale = open4.filter((record) => Date.now() - Date.parse(record.repliedAt ?? record.reachedAt ?? record.updatedAt) > ERRAND_OPEN_MS);
+    const open5 = [...errandsById.values()].filter((record) => record.conversationId === roomId && openErrand(record));
+    const stale = open5.filter((record) => Date.now() - Date.parse(record.repliedAt ?? record.reachedAt ?? record.updatedAt) > ERRAND_OPEN_MS);
     for (const record of stale) saveErrand({ ...record, status: "expired", reason: "no reply within a week" });
-    return open4.filter((record) => !stale.includes(record));
+    return open5.filter((record) => !stale.includes(record));
   }
   __name(openErrands, "openErrands");
   function replied(turn) {
@@ -4859,6 +4970,7 @@ ${JSON.stringify(result, null, 2)}`);
       if (holder.turn === turn) holder.turn = void 0;
       errandTurns.delete(record.id);
       running.delete(done);
+      touch();
       if (origin) {
         rooms.delete(origin.id);
         rooms.set(origin.id, origin);
@@ -4866,6 +4978,7 @@ ${JSON.stringify(result, null, 2)}`);
       pump();
     });
     running.add(done);
+    touch();
   }
   __name(startErrand, "startErrand");
   async function executeErrand(current, turn, record) {
@@ -5247,7 +5360,10 @@ ${JSON.stringify(result, null, 2)}`);
         }
         warn("recovery")(error);
       }, "onError") }));
+      touch();
+      watchIdle();
     },
+    activity,
     stop() {
       stopping ??= (async () => {
         for (const off of detach.splice(0).reverse()) off();
@@ -5275,13 +5391,14 @@ ${JSON.stringify(result, null, 2)}`);
     },
     async communicate(input) {
       if (!client) throw new Error("Start the runner before sending");
-      return client.communicate(parseCommunicateToolInput(input));
+      return activeCall(() => client.communicate(parseCommunicateToolInput(input)));
     },
     async relayRead(conversationId, page = {}) {
+      touch();
       const limit = page.limit ?? 20;
       if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new ConnectorRelayError(400, "CONNECTOR_RELAY_INVALID", "limit must be 1 to 100");
       const deadline = page.deadline ?? Date.now() + CONNECTOR_RELAY_ANSWER_WITHIN_MS;
-      return beforeDeadline((async () => {
+      return beforeDeadline(activeCall(async () => {
         const { ownerId } = await relayRoom(conversationId);
         const result = await readAgain(() => endpoint.query("list_messages", { conversationId, limit, ...page.before ? { before: page.before } : {} }), deadline);
         const accepted = result.messages.filter((message2) => !message2.deleted && typeof message2.text === "string" && message2.status === "sent" && Number.isSafeInteger(message2.mlsFeedOrdinal) && message2.mlsFeedOrdinal > 0);
@@ -5293,9 +5410,10 @@ ${JSON.stringify(result, null, 2)}`);
           nextBefore = String(accepted.at(-1).mlsFeedOrdinal);
         }
         return { messages, nextBefore };
-      })(), deadline);
+      }), deadline);
     },
     async relaySend(conversationId, messageId, text3, options2 = {}) {
+      touch();
       if (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 send needs a messageId and 1 byte to 32 KiB of text");
       }
@@ -5303,13 +5421,14 @@ ${JSON.stringify(result, null, 2)}`);
       const id = `relay-send-${sha2563(JSON.stringify([conversationId, messageId])).slice(0, 32)}`;
       let entry = relaySends.get(id);
       if (!entry) relaySends.set(id, entry = prepareRelaySend(conversationId, id, text3, deadline));
-      const prepared = await beforeDeadline(entry.ready, deadline);
+      const prepared = await beforeDeadline(activeCall(() => entry.ready), deadline);
       if (prepared.text !== text3) throw new ConnectorRelayError(409, "CONNECTOR_RELAY_MESSAGE_CONFLICT", "This messageId was already sent with other text");
-      const sent = await within(entry.sent, Math.max(0, deadline - Date.now()));
+      const sent = await within(activeCall(() => 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 = {}) {
+      touch();
       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");
       }
@@ -5318,12 +5437,12 @@ ${JSON.stringify(result, null, 2)}`);
       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({
+        activeCall(() => endpoint.startWithheldOpener({
           targetUserId,
           text: text3,
           messageId: identity.historyMessageId,
           ...selection ? { selection } : {}
-        }).then((result2) => ({ result: result2 }), (error) => ({ error })),
+        })).then((result2) => ({ result: result2 }), (error) => ({ error })),
         Math.max(0, deadline - Date.now())
       );
       if (!answer || "error" in answer && answer.error?.retryable === true) {
@@ -5373,6 +5492,81 @@ function relayMessage(message2, ownerId) {
 }
 __name(relayMessage, "relayMessage");
 
+// src/runner/wake.ts
+import { constants as constants5 } from "node:fs";
+import { open as open4, realpath as realpath5 } from "node:fs/promises";
+import { isAbsolute as isAbsolute4, resolve as resolve3 } from "node:path";
+var MAX_WAKE_CONFIGURATION_BYTES = 16 * 1024;
+var MAX_WAKE_ROOMS = 32;
+var ROOM_ID = /^[A-Za-z0-9_-]{1,200}$/;
+function isWakeSecret(value) {
+  if (typeof value !== "string" || !/^whsec_[A-Za-z0-9+/]+={0,2}$/.test(value)) return false;
+  const key = Buffer.from(value.slice(6), "base64");
+  return key.length >= 32 && key.length <= 64 && key.toString("base64") === value.slice(6);
+}
+__name(isWakeSecret, "isWakeSecret");
+function parseWakeConfiguration(value) {
+  const invalid2 = /* @__PURE__ */ __name((what) => {
+    throw new Error(`Invalid wake configuration: ${what}`);
+  }, "invalid");
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid2("expected a JSON object");
+  const v = value;
+  const keys = ["version", "callbackUrl", "secret", "conversationIds"];
+  if (Object.keys(v).sort().join() !== [...keys].sort().join()) invalid2(`expected ${keys.join(", ")}`);
+  if (v.version !== 1) invalid2("version");
+  let url;
+  try {
+    url = typeof v.callbackUrl === "string" && v.callbackUrl.length <= 2048 ? new URL(v.callbackUrl) : void 0;
+  } catch {
+  }
+  if (!url || url.protocol !== "https:" || url.username || url.password || url.hash) invalid2("callbackUrl: a public https URL, with no credentials or fragment");
+  if (!isWakeSecret(v.secret)) invalid2("secret: whsec_ and the padded base64 of 32 to 64 random bytes");
+  const rooms = v.conversationIds;
+  if (!Array.isArray(rooms) || rooms.length < 1 || rooms.length > MAX_WAKE_ROOMS || rooms.some((id) => typeof id !== "string" || !ROOM_ID.test(id))) {
+    invalid2(`conversationIds: 1 to ${MAX_WAKE_ROOMS} conversation ids`);
+  }
+  return { callbackUrl: url.toString(), secret: v.secret, conversationIds: [...new Set(rooms)].sort() };
+}
+__name(parseWakeConfiguration, "parseWakeConfiguration");
+async function loadWakeConfiguration(path) {
+  const fail2 = /* @__PURE__ */ __name(() => {
+    throw new Error(`The wake configuration must be a private file (0600, owned by this user, not a link): ${path}`);
+  }, "fail");
+  if (typeof path !== "string" || !isAbsolute4(path) || path.includes("\0") || resolve3(path) !== path || await realpath5(path).catch(() => "") !== path) fail2();
+  const windows = process.platform === "win32";
+  if (windows) assertPrivateWindowsFile(path);
+  const file = await open4(path, constants5.O_RDONLY | (constants5.O_NOFOLLOW ?? 0) | (constants5.O_NONBLOCK ?? 0)).catch(() => fail2());
+  let text3;
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size < 1 || info.size > MAX_WAKE_CONFIGURATION_BYTES) fail2();
+    if (!windows && (info.uid !== process.getuid?.() || (info.mode & 63) !== 0)) fail2();
+    const bytes = await readBoundedRegularFileHandle(file, MAX_WAKE_CONFIGURATION_BYTES).catch(() => fail2());
+    try {
+      text3 = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      return fail2();
+    }
+  } finally {
+    await file.close();
+  }
+  let value;
+  try {
+    value = JSON.parse(text3);
+  } catch {
+    throw new Error("Invalid wake configuration: not JSON");
+  }
+  return parseWakeConfiguration(value);
+}
+__name(loadWakeConfiguration, "loadWakeConfiguration");
+function parseIdleTimeout(value) {
+  const match = /^(\d{1,7})([smh]?)$/.exec(value.trim());
+  const ms = match ? Number(match[1]) * { "": 1e3, s: 1e3, m: 6e4, h: 36e5 }[match[2]] : NaN;
+  if (!Number.isSafeInteger(ms) || ms < 1e3) throw new Error("--idle-timeout takes a duration of at least 1 second: 90, 90s, 10m or 1h.");
+  return ms;
+}
+__name(parseIdleTimeout, "parseIdleTimeout");
+
 export {
   DriverSessionError,
   ConnectorRelayError,
@@ -5404,5 +5598,8 @@ export {
   writeRelayCredential,
   relayRunnerHome,
   runtimeDescriptor,
-  createRunner
+  createRunner,
+  parseWakeConfiguration,
+  loadWakeConfiguration,
+  parseIdleTimeout
 };

package/dist/cli.js

@@ -17,13 +17,15 @@ import {
   loadInstructions,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  loadWakeConfiguration,
+  parseIdleTimeout,
   queueErrand,
   readRelayCredential,
   relayRunnerHome,
   runMlsDevSetup,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-XKUG2BQR.js";
+} from "./chunks/chunk-IEKVS7AN.js";
 import {
   assertPrivateHome,
   runnerLockName
@@ -56,10 +58,10 @@ var RUNNER_VERSION = readCliPackageVersion(import.meta.url);
 var RUNNER_CLIENT = isCanonClientVersion(RUNNER_VERSION) ? { kind: "runner", version: RUNNER_VERSION } : void 0;
 function once(handler) {
   let called = false;
-  return (error) => {
+  return (...args) => {
     if (!called) {
       called = true;
-      handler(error);
+      handler(...args);
     }
   };
 }
@@ -97,6 +99,14 @@ command also takes --mls-dev-config <path>, an operator's own custody instead. W
 of these, the agent refuses every room, and where Canon encrypts every new conversation
 it does not start.
 
+Waking and sleeping: code, claude, codex and acp also take [--wake-config <path> |
+--wake-off] [--idle-timeout <duration>]. With --wake-config the agent registers, at
+each start, a public HTTPS callback for up to 32 rooms; Canon POSTs it a signed,
+content-free hint when a person types or a message arrives there, so the host can
+start (or resume) the agent. With --idle-timeout the agent stops and exits 0 once it
+has had nothing to do for that long: no turn, no input, no errand, nothing Canon has
+yet to accept. Nothing is lost while it is stopped; it answers once it starts again.
+
 Team rooms (an owner's agents working together): claude, codex and acp also take
 [--instructions <file>] [--trust-agent <agentId>]...; every run command takes
 [--agent-turn-cap <n>] [--mention-alias <name>]....
@@ -174,6 +184,17 @@ Flags:
                          $CANON_HOME/relay. The relay serves only encrypted rooms,
                          which are then not end-to-end encrypted to that agent. It sets
                          up the relay's device with that credential.
+  --wake-config <path>   Register the agent's wake callback at start: a private JSON file
+                         (0600, owned by you, not a link) {"version": 1, "callbackUrl":
+                         "https://...", "secret": "whsec_<base64 of 32 random bytes>",
+                         "conversationIds": [up to 32 room ids]}. Canon checks the URL
+                         with a signed challenge first; the agent does not start if
+                         that fails. Without the flag a registration is left as it is.
+  --wake-off             Remove the agent's wake callback at start.
+  --idle-timeout <d>     Stop and exit 0 after this long with nothing to do: whole
+                         seconds, or 90s, 10m, 1h. Typing in a room does not reach the
+                         agent: a host that also receives typing hints decides itself
+                         whether to keep the agent awake for them.
   --mls-dev-config <p>   An operator's own MLS configuration, instead of the device the
                          runner keeps itself: an absolute path to a private JSON file
                          with the environment's issuer pins and the custody helper (no
@@ -263,6 +284,16 @@ async function main() {
   if (values["guest-mode"] !== void 0 && values["unguarded-guests"]) throw new UsageError("--guest-mode and --unguarded-guests are alternatives.");
   const team = teamOptions(values);
   if (values.driver === "connector" && values["allow-session-for-destructive"]) throw new UsageError("--allow-session-for-destructive goes with a driver that asks.");
+  if (values.driver === "connector" && (values["wake-config"] !== void 0 || values["wake-off"] || values["idle-timeout"] !== void 0)) {
+    throw new UsageError("--wake-config, --wake-off and --idle-timeout go with an agent's own key, not --driver connector.");
+  }
+  if (values["wake-config"] !== void 0 && values["wake-off"]) throw new UsageError("--wake-config and --wake-off are alternatives.");
+  let idleTimeoutMs;
+  try {
+    idleTimeoutMs = values["idle-timeout"] !== void 0 ? parseIdleTimeout(values["idle-timeout"]) : void 0;
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
   if (values.driver === "connector") return runRelay(values, team);
   const permissionMode = values["permission-mode"];
   if (permissionMode !== void 0 && !PERMISSION_MODES.includes(permissionMode)) {
@@ -278,6 +309,7 @@ async function main() {
   const trustedAgents = values["trust-agent"] ?? [];
   if (trustedAgents.some((id) => !/^[\w.:-]{1,200}$/.test(id))) throw new UsageError("--trust-agent takes an agent id.");
   const instructions = values.instructions !== void 0 ? await loadInstructions(resolve(values.instructions)) : void 0;
+  const wake = values["wake-off"] ? null : values["wake-config"] !== void 0 ? await loadWakeConfiguration(resolve(values["wake-config"])) : void 0;
   const { environmentId, home, profile, apiKey } = await settings(values);
   const mls = await mlsDevice(values, environmentId, home);
   const baseUrl = process.env.CANON_BASE_URL || profile?.baseUrl;
@@ -335,6 +367,15 @@ async function main() {
     ...trustedAgents.length ? { trustedAgents } : {},
     ...values["allow-session-for-destructive"] ? { sessionApprovalForDestructive: true } : {},
     ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {},
+    ...wake !== void 0 ? { wake } : {},
+    // Idle: a clean stop and exit 0, so a supervisor that restarts only on failure leaves the agent stopped until it is woken.
+    ...idleTimeoutMs !== void 0 ? { idleTimeoutMs, onIdle: once(() => {
+      console.error(`canon-agent: nothing to do for ${values["idle-timeout"]}; stopping.`);
+      runner.stop().then(() => process.exit(0), (error) => {
+        console.error(`canon-agent: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+      });
+    }) } : {},
     onFatal: once((error) => {
       console.error(`canon-agent: ${error.message}`);
       void runner.stop().catch(() => void 0).finally(() => process.exit(1));
@@ -347,7 +388,7 @@ async function main() {
     await runner.stop().catch(() => void 0);
     throw error;
   }
-  console.error(`canon-agent: running the ${values.driver} driver in ${environmentId}. Ctrl-C stops it.`);
+  console.error(`canon-agent: running the ${values.driver} driver in ${environmentId}. Ctrl-C stops it${idleTimeoutMs !== void 0 ? `, and it stops itself after ${values["idle-timeout"]} with nothing to do` : ""}.`);
 }
 __name(main, "main");
 async function runRelay(values, team) {
@@ -478,7 +519,10 @@ function parse() {
       why: { type: "string" },
       origin: { type: "string" },
       follow: { type: "boolean" },
-      cancel: { type: "string" }
+      cancel: { type: "string" },
+      "wake-config": { type: "string" },
+      "wake-off": { type: "boolean" },
+      "idle-timeout": { type: "string" }
     }
   });
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createRunner, runtimeDescriptor } from './runner/runner.js';
-export type { Runner, RunnerOptions } from './runner/runner.js';
+export type { Runner, RunnerActivity, RunnerOptions } from './runner/runner.js';
+export { loadWakeConfiguration, parseWakeConfiguration } from './runner/wake.js';
 export { ConnectorRelayError, DriverSessionError } from './runner/types.js';
 export { loadMlsDevConfiguration, MLS_SETUP_ACTIONS, mlsDevRoomPackageId, runMlsDevSetup } from './runner/mls.js';
 export type { MlsSetupAction, RunnerMlsOptions } from './runner/mls.js';

package/dist/index.js

@@ -18,13 +18,15 @@ import {
   loadClaudeQuery,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  loadWakeConfiguration,
   managedMlsDevice,
   mlsDevRoomPackageId,
+  parseWakeConfiguration,
   queueErrand,
   runMlsDevSetup,
   runtimeDescriptor,
   startRelayChannel
-} from "./chunks/chunk-XKUG2BQR.js";
+} from "./chunks/chunk-IEKVS7AN.js";
 import "./chunks/chunk-DTAWEQCM.js";
 import {
   CanonApiError,
@@ -88,11 +90,13 @@ export {
   loadClaudeQuery,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  loadWakeConfiguration,
   managedMlsDevice,
   materializeAttachment,
   materializeMessageMedia,
   materializeReplyContextMedia,
   mlsDevRoomPackageId,
+  parseWakeConfiguration,
   queueErrand,
   resolveAttachmentMimeType,
   resumeRegistration,

package/dist/internal/endpoint/transient-publisher.d.ts

@@ -1,8 +1,9 @@
 import type { Endpoint } from './engine.js';
 /** Transient writes are coalesced here; they never enter the durable outbox. */
 export declare function createEndpointTransientPublisher(endpoint: Pick<Endpoint, 'publish'>, clock?: () => number): {
-    pulseTyping(conversationId: string): void;
-    stopTyping: (conversationId: string) => void;
+    /** A keystroke in the composer wakes the room's agents: once per burst of typing (a 3 s pause ends one), and every 10 s
+     * of it. The hint carries no content; typing itself never leaves the device. */
+    prewarmAgents(conversationId: string): void;
     setPresence(state: "online" | "offline" | "hidden"): void;
     close(): void;
 };

package/dist/runner/runner.d.ts

@@ -68,9 +68,35 @@ export interface RunnerOptions {
     sessionApprovalForDestructive?: boolean;
     /** How long running turns may finish on shutdown before they are aborted (default 10 s). */
     shutdownGraceMs?: number;
+    /**
+     * Idle (agent-wake.md): `onIdle` is called once the runner has been idle (`activity().idle`) for this long, in ms, and
+     * again only after new activity and another idle period. The runner does nothing else about it: the host decides, as the
+     * CLI's --idle-timeout stops and exits, or a hosting platform suspends the agent's machine until Canon's wake callback.
+     */
+    idleTimeoutMs?: number;
+    /** Idle: called with the activity that showed it; it never names a room, message or content. */
+    onIdle?(activity: RunnerActivity): void;
     /** Never receives prompt or reply text. */
     log?: (line: string) => void;
 }
+/**
+ * What the runner has in hand, for a host that stops or suspends an idle agent (agent-wake.md). Counts only. Idle is all
+ * of them 0: once stopped or suspended, the agent loses nothing (input waits in Canon and in its inbox) but answers only
+ * when Canon's wake callback, or its host, starts it again.
+ */
+export interface RunnerActivity {
+    idle: boolean;
+    /** When the runner last had something to do (epoch ms), or when it started. */
+    lastActiveAt: number;
+    /** Turns running or starting, errand turns, restart recovery and New session resets included. */
+    turns: number;
+    /** Input waiting for a turn: in the inbox, being admitted, or queued behind a running turn (whose own input is in `turns`). */
+    inputs: number;
+    /** Errands waiting for their turn. */
+    errands: number;
+    /** In-flight proactive/relay calls plus operations Canon has not answered, including replies, cards and group changes. */
+    outbound: number;
+}
 export interface Runner {
     /** Connects and starts taking input; resolves once listening is set up. */
     start(): Promise<void>;
@@ -78,6 +104,8 @@ export interface Runner {
     stop(): Promise<void>;
     /** A proactive send outside any turn (cron): the `communicate` tool's handler, under the runner's identity. */
     communicate(input: CommunicateInput): Promise<CommunicateResult>;
+    /** What the runner has in hand now, for a host's idle policy (agent-wake.md). Only between start and stop. */
+    activity(): Promise<RunnerActivity>;
     /**
      * Relay mode (§11.6): an encrypted room's history as this device verified it and Canon accepted it, newest first, cut
      * to the channel's response budget. `deadline` (epoch ms, default the channel's answer budget) bounds the read.

package/dist/runner/wake.d.ts

@@ -0,0 +1,16 @@
+import type { AgentWakeConfiguration } from '../internal/backend-contracts/index.js';
+/**
+ * A wake callback's signing secret: `whsec_` and the standard base64 (padded) of 32 to 64 random bytes. Canon takes at
+ * least 32 for a wake callback, and a receiver such as Agent Platform's `/wake/:bindingId` at most 64, padded.
+ */
+export declare function isWakeSecret(value: unknown): value is string;
+/** The same checks Canon makes before it sends the callback its verification challenge; Canon checks again. */
+export declare function parseWakeConfiguration(value: unknown): AgentWakeConfiguration;
+/**
+ * `--wake-config <path>` (agent-wake.md): the agent's signed wake callback. A private JSON file (0600, owned by this user,
+ * one name, no links; on Windows only this user, SYSTEM and Administrators may reach it and its folder), since it holds
+ * the callback's signing secret: `{ "version": 1, "callbackUrl", "secret", "conversationIds" }`. Its text is never logged.
+ */
+export declare function loadWakeConfiguration(path: string): Promise<AgentWakeConfiguration>;
+/** `--idle-timeout`: whole seconds, or a number with `s`, `m` or `h`; at least one second. Returns milliseconds. */
+export declare function parseIdleTimeout(value: string): number;

package/package.json

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