@canonmsg/agent-sdk 13.0.3 → 13.2.0

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-6FD6KFQN.js";
 import {
   assertPrivateHome,
   runnerLockName
@@ -38,7 +40,7 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-ZPBOGOAD.js";
+} from "./chunks/chunk-5YKGDUJX.js";
 import "./chunks/chunk-YJUPKU47.js";
 import "./chunks/chunk-YHDDOADK.js";
 import {
@@ -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-6FD6KFQN.js";
 import "./chunks/chunk-DTAWEQCM.js";
 import {
   CanonApiError,
@@ -50,7 +52,7 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-ZPBOGOAD.js";
+} from "./chunks/chunk-5YKGDUJX.js";
 import "./chunks/chunk-YJUPKU47.js";
 import "./chunks/chunk-YHDDOADK.js";
 import "./chunks/chunk-5WPAB5MB.js";
@@ -88,11 +90,13 @@ export {
   loadClaudeQuery,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  loadWakeConfiguration,
   managedMlsDevice,
   materializeAttachment,
   materializeMessageMedia,
   materializeReplyContextMedia,
   mlsDevRoomPackageId,
+  parseWakeConfiguration,
   queueErrand,
   resolveAttachmentMimeType,
   resumeRegistration,

package/dist/internal/core/client.d.ts

@@ -1,11 +1,6 @@
 import type { AgentWakeConfiguration } from '../backend-contracts/index.js';
-import { type CanonMessage, type CanonConversation, type CanonUnifiedDiff, type CanonMessagesPage, type AgentContext, type MediaAttachment, type SendMessageOptions, type RegistrationStatus, type AgentOriginDeclaration, type SetRuntimeTurnOptions, type SetStreamingOptions } from './types.js';
-import type { RuntimeInputKind } from './runtime-cards.js';
-import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
-import type { RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1 } from './runtime-cards.js';
-import type { InboundDisposition } from './turn-protocol.js';
+import { type CanonMessage, type CanonConversation, type CanonMessagesPage, type AgentContext, type MediaAttachment, type SendMessageOptions, type RegistrationStatus, type AgentOriginDeclaration, type SetRuntimeTurnOptions } from './types.js';
 import { type CanonVerbWireRequest, type CanonVerbWireResponse, type CommunicateInput, type CommunicateResult, type DiscoverAgentsInput, type DiscoverAgentsResult } from '../backend-contracts/index.js';
-import { type EndpointOperation } from '../endpoint/index.js';
 import { type CanonClientEndpointOptions, type CanonEndpoint } from './endpoint-client.js';
 export interface ResumableMediaUploadResult {
     uploadId: string;
@@ -53,28 +48,6 @@ export declare class CanonClient {
     }): Promise<{
         messageId: string;
     }>;
-    /** Inspect a trusted reply's durable delivery without rebuilding its body. */
-    getMessageOperation(conversationId: string, messageId: string, delivery?: {
-        operationId?: string;
-    }): Promise<EndpointOperation | undefined>;
-    /** Core's chunker records all ordered message intents before publishing any part. */
-    prepareMessageGroup(conversationId: string, messageId: string, parts: Array<{
-        text: string;
-        options: SendMessageOptions;
-    }>, delivery?: {
-        operationId?: string;
-        signal?: AbortSignal;
-        replacesOperationId?: string;
-    }): Promise<{
-        id: string;
-        sendPart(index: number, options?: {
-            signal?: AbortSignal;
-            timeoutMs?: number;
-        }): Promise<{
-            messageId: string;
-        }>;
-    }>;
-    cancelMessageGroup(id: string): Promise<void>;
     /**
      * Execute a canonical verb over the wire contract (canon.verb-wire.v1).
      * Bindings build the request with projectVerbIntentToWire; the endpoint
@@ -99,13 +72,10 @@ export declare class CanonClient {
     private startWithheld;
     blockUser(userId: string): Promise<void>;
     deleteMessage(conversationId: string, messageId: string): Promise<void>;
-    updateMessageDisposition(conversationId: string, messageId: string, inboundDisposition: InboundDisposition): Promise<void>;
     markAsRead(conversationId: string): Promise<void>;
     react(conversationId: string, messageId: string, emoji: string): Promise<void>;
-    setStreaming(options: SetStreamingOptions): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;
     setRuntimeTurn(options: SetRuntimeTurnOptions): Promise<void>;
-    setTyping(conversationId: string, typing: boolean, status?: 'thinking' | 'typing'): Promise<void>;
     peekRuntimeSignal(conversationId: string): Promise<Record<string, unknown>>;
     /** Acknowledge exactly the signal observed before the native handler ran. */
     acknowledgeRuntimeSignal(conversationId: string, signalId: string): Promise<Record<string, unknown>>;
@@ -124,190 +94,6 @@ export declare class CanonClient {
         mode: 'clear';
     }): Promise<void>;
     patchRuntimeStreaming(conversationId: string, patch: Record<string, unknown>): Promise<void>;
-    createRuntimeInputRequest(options: {
-        conversationId: string;
-        inputId: string;
-        kind: RuntimeInputKind;
-        expiresAt: number;
-        title?: string;
-        prompt?: string;
-        choices?: RuntimeInputChoice[];
-        questions?: RuntimeInputQuestion[];
-        secretName?: string;
-        native?: RuntimeInputNativeMetadata;
-        sensitive?: boolean;
-        responseUserId?: string;
-        turnId?: string;
-    }): Promise<{
-        success: true;
-        inputId: string;
-        expiresAt: number;
-        messageId?: string;
-    }>;
-    consumeRuntimeInputResponse(options: {
-        conversationId: string;
-        inputId: string;
-        cancel?: boolean;
-    }): Promise<{
-        status: 'pending';
-        inputId: string;
-        expiresAt?: number;
-    } | {
-        status: 'submitted';
-        inputId: string;
-        kind: RuntimeInputKind;
-        value: string;
-        answers?: RuntimeInputAnswers;
-    } | {
-        status: 'cancelled';
-        inputId: string;
-        kind: RuntimeInputKind;
-    } | {
-        status: 'timeout';
-        inputId: string;
-        kind: RuntimeInputKind;
-    }>;
-    createRuntimeApprovalRequest(options: {
-        conversationId: string;
-        approvalId?: string;
-        toolName: string;
-        toolSummary: string;
-        expiresAt: number;
-        responseUserId?: string;
-        riskLevel?: 'normal' | 'destructive';
-        risk?: ApprovalRisk;
-        category?: ApprovalRequestCategory;
-        runtimeId?: string;
-        turnId?: string;
-        native?: ApprovalNativeRequestMetadata;
-        details?: ApprovalRequestDetail[];
-        /** File-change preview rendered inline on the approval card. Truncate via truncateUnifiedDiff before sending. */
-        diff?: CanonUnifiedDiff;
-        allowSessionRule?: boolean;
-    }): Promise<{
-        success: true;
-        approvalId: string;
-        expiresAt: number;
-        messageId?: string;
-        responseUserId: string;
-        allowSessionRule: boolean;
-    }>;
-    consumeRuntimeApprovalResponse(options: {
-        conversationId: string;
-        approvalId: string;
-        cancel?: boolean;
-    }): Promise<{
-        status: 'pending';
-        approvalId: string;
-        expiresAt?: number;
-    } | {
-        status: 'allow';
-        approvalId: string;
-        sessionRule?: SessionRule;
-        respondedBy?: string;
-    } | {
-        status: 'deny';
-        approvalId: string;
-        sessionRule?: SessionRule;
-        respondedBy?: string;
-    } | {
-        status: 'timeout';
-        approvalId: string;
-    }>;
-    createRuntimeCardRequest(options: {
-        conversationId: string;
-        card: RuntimeCardV1;
-        cardId?: string;
-        expiresAt?: number;
-        responseUserId?: string;
-        runtimeId?: string;
-        turnId?: string;
-        native?: RuntimeCardNativeMetadata;
-    }): Promise<{
-        success: true;
-        cardId: string;
-        messageId: string;
-        /** True when the card has actions and a response is pending; false for display cards. */
-        interactive: boolean;
-        /** Effective human responder selected by Canon. */
-        responseUserId?: string;
-        /** Present only for interactive cards. */
-        expiresAt?: number;
-    }>;
-    consumeRuntimeCardResponse(options: {
-        conversationId: string;
-        cardId: string;
-        cancel?: boolean;
-    }): Promise<{
-        status: 'pending';
-        cardId: string;
-        expiresAt?: number;
-    } | {
-        status: 'submitted';
-        cardId: string;
-        actionId?: string;
-        values?: Record<string, unknown>;
-        respondedBy?: string;
-    } | {
-        status: 'cancelled';
-        cardId: string;
-        respondedBy?: string;
-    } | {
-        status: 'timeout';
-        cardId: string;
-    }>;
-    /**
-     * Create a server-owned plan-approval interaction.
-     *
-     * Seeds the pending node + attention + runtime-card state and authors the
-     * `plan_approval` card message, mirroring the other `createRuntime*Request`
-     * spine methods. Hosts resolve it through `consumeRuntimePlanResponse()` so
-     * the canonical pending state, rather than a timeline receipt, is authoritative.
-     */
-    createRuntimePlanRequest(options: {
-        conversationId: string;
-        planId?: string;
-        title?: string;
-        summary?: string;
-        body?: string;
-        allowedPrompts?: ReadonlyArray<{
-            tool: string;
-            prompt: string;
-        }>;
-        responseUserId?: string;
-        turnId?: string;
-        expiresAt?: number;
-    }): Promise<{
-        success: true;
-        planId: string;
-        expiresAt: number;
-        messageId?: string;
-        interactive: boolean;
-    }>;
-    consumeRuntimePlanResponse(options: {
-        conversationId: string;
-        planId: string;
-        cancel?: boolean;
-    }): Promise<{
-        status: 'pending';
-        planId: string;
-        expiresAt?: number;
-    } | {
-        status: 'approve' | 'revise' | 'reject';
-        planId: string;
-        feedback?: string;
-        grantedPrompts?: Array<{
-            tool: string;
-            prompt: string;
-        }>;
-        receiptId?: string;
-    } | {
-        status: 'cancelled';
-        planId: string;
-    } | {
-        status: 'timeout';
-        planId: string;
-    }>;
     updateRuntimeStatus(options: {
         runtime: string;
         hostMode?: boolean;

package/dist/internal/core/index.d.ts

@@ -57,4 +57,3 @@ export { CANON_VERB_NAMES, CANON_VERB_NAMESPACE, CANON_VERBS_SCHEMA_ID, CANON_VE
 export { DEFAULT_DISCOVER_AGENTS_LIMIT, MAX_DISCOVER_AGENTS_LIMIT, MAX_DISCOVER_AGENTS_QUERY_LENGTH, type CanonAgentDirectoryEntry, type DiscoverAgentsInput, type DiscoverAgentsResult, } from '../backend-contracts/index.js';
 export { parseDirectConversationSelection, readCommunicationRule, type CommunicateInput, type CommunicateResult, type CommunicationRule, type DirectConversationSelection, type StartDirectInput, type StartDirectResult, } from '../backend-contracts/index.js';
 export { canonMediaDownloadUrl, sanitizeDownloadFileName, buildMediaContentDisposition, getStoredFileExtension } from '../backend-contracts/index.js';
-export * from './completed-output-journal.js';

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

@@ -0,0 +1,45 @@
+import { type EndpointStore, type EndpointStoreTransaction } from './store.js';
+/**
+ * A runtime's finished output, recorded before it is published: a turn's answer, or text a host sends with no turn. A
+ * host that dies between the answer and Canon's acceptance publishes exactly that output on restart and never runs the
+ * turn again. One record holds the answer, the inputs it answers and the audience it may reach, in the engine's own
+ * store, so recording it and settling its inputs once it is durable are each one transaction with the inbox.
+ */
+export interface EndpointCompletion<T = unknown> {
+    version: 1;
+    id: string;
+    conversationId: string;
+    /** The inbox inputs it answers. They settle with it (`finishCompletion`); an uncertain input that no completion names is an orphan. */
+    inputIds: string[];
+    /** The audience its publication may reach (an encrypted room's group head, roster and admissions), or null. */
+    fence: unknown;
+    /** What the runtime answered, as its host records it. */
+    output: T;
+    createdAt: string;
+}
+/** Completions in the engine's store. Every write checks the current installation, as content writes do. */
+export declare function createCompletions(input: {
+    store: EndpointStore;
+    ready(): Promise<unknown>;
+    assertOpen(): void;
+    assertCurrent(tx: EndpointStoreTransaction): Promise<void>;
+    /** Settles one inbox input inside the caller's transaction, as `setInboundState` does. */
+    settleInbound(tx: EndpointStoreTransaction, id: string, reason: string): Promise<void>;
+}): {
+    save(record: EndpointCompletion): Promise<void>;
+    get<T>(id: string): Promise<EndpointCompletion<T> | undefined>;
+    /** Oldest first. */
+    list<T>(): Promise<Array<EndpointCompletion<T>>>;
+    /** One record for another, in one step: a Stop's cut keeps only what was already queued. */
+    replace(previousId: string, next: EndpointCompletion): Promise<void>;
+    /**
+     * The output is durable or withdrawn: its record goes, and in the same step `settle`'s inputs settle. An input already
+     * settled, or no longer in the inbox, is left as it is.
+     */
+    finish(id: string, settle?: {
+        inputIds: readonly string[];
+        reason: string;
+    }): Promise<void>;
+    /** The input ids every completion names, read inside the caller's transaction. */
+    answered(tx: EndpointStoreTransaction): Promise<Set<string>>;
+};

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

@@ -10,6 +10,7 @@ import { type EndpointRecoveryMigration, type EndpointMigrationReceipt } from '.
 import { type EndpointBackgroundMediaAdapter, type EndpointMediaBytes, type EndpointMediaPipeline } from './media.js';
 import { type EndpointOrdering } from './queue.js';
 import { type EndpointInboundHandoff, type EndpointInboundStartResult } from './handoff.js';
+import { type EndpointCompletion } from './completions.js';
 import { type ExternalInboundClaim } from './external-inbound.js';
 import type { EndpointExternalInboundClaimResult, EndpointExternalInboundOutcome } from '../backend-contracts/index.js';
 import { type MlsDevGroupClient } from './mls-dev-groups.js';
@@ -246,11 +247,25 @@ export interface Endpoint {
     }): Promise<boolean>;
     acceptInbound(options: EndpointInboundConsumerOptions): EndpointInboundConsumer;
     setInboundState(id: string, state: EndpointInboundState, reason?: string): Promise<void>;
+    /** `unanswered`: only inputs no completion names (`completions.ts`), read in the same transaction. */
     listInbound(options?: {
         states?: EndpointInboundState[];
         after?: string;
         limit?: number;
+        unanswered?: boolean;
     }): Promise<EndpointInboundRecord[]>;
+    /** A runtime's finished output, recorded before it is published (`completions.ts`). The same record again is a no-op. */
+    saveCompletion(record: EndpointCompletion): Promise<void>;
+    getCompletion<T = unknown>(id: string): Promise<EndpointCompletion<T> | undefined>;
+    /** Every recorded completion, oldest first. */
+    listCompletions<T = unknown>(): Promise<Array<EndpointCompletion<T>>>;
+    /** One completion for another, in one transaction. */
+    replaceCompletion(previousId: string, next: EndpointCompletion): Promise<void>;
+    /** The output is durable or withdrawn: the completion goes, and `settle`'s inputs settle, in one transaction. */
+    finishCompletion(id: string, settle?: {
+        inputIds: readonly string[];
+        reason: string;
+    }): Promise<void>;
     discardPending(): Promise<void>;
     logout(): Promise<void>;
     close(): Promise<void>;

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

@@ -1,4 +1,5 @@
 export * from './engine.js';
+export type { EndpointCompletion } from './completions.js';
 export * from './store.js';
 export * from './transport.js';
 export * from './observe-query.js';

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/media.js

@@ -18,7 +18,7 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-ZPBOGOAD.js";
+} from "./chunks/chunk-5YKGDUJX.js";
 import "./chunks/chunk-YJUPKU47.js";
 import "./chunks/chunk-YHDDOADK.js";
 import "./chunks/chunk-5WPAB5MB.js";

package/dist/runner/errands.d.ts

@@ -95,8 +95,8 @@ export declare function awaitErrand(directory: string, command: Pick<ErrandComma
     accepted: boolean;
 }>;
 export interface ErrandHandler {
-    /** The command was taken already (its record or its journaled output exists): its file is only removed. */
-    taken(id: string): boolean;
+    /** The command was taken already (its record or its saved output exists): its file is only removed. */
+    taken(id: string): boolean | Promise<boolean>;
     /**
      * The command, or why its file is refused. True once its effect (or refusal) is journaled, so the file may go; false
      * leaves it for the next scan. A throw is logged once per command and reason, and also leaves it.

package/dist/runner/runner.d.ts

@@ -68,16 +68,49 @@ 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>;
     /** Stops intake, releases unsubmitted input, lets running turns finish within the shutdown grace. */
     stop(): Promise<void>;
-    /** A proactive send outside any turn (cron): the `communicate` tool's handler, under the runner's identity. */
+    /**
+     * A proactive send outside any turn (cron), under the runner's identity, with the `communicate` tool's input. Text to a
+     * conversation is encrypted for the members it has now, journaled first and sent once, even across a restart; a new
+     * conversation is founded encrypted by this device. `messageId` makes a retry the same message or start. Other actions
+     * go to Canon as they are.
+     */
     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.2.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",