@canonmsg/agent-sdk 13.2.1 → 13.3.1

package/dist/chunks/{mls-crypto-ZBEC26B5.js → mls-crypto-AW7TY744.js}

@@ -2,8 +2,8 @@ import {
   createMlsDevCredentialVerifier,
   mlsDevDeviceHttpConfiguration,
   parseMlsDevClientConfiguration
-} from "./chunk-2NVLVPSG.js";
-import "./chunk-VIS5WXNH.js";
+} from "./chunk-NIORQKUI.js";
+import "./chunk-CUPSYLBV.js";
 export {
   createMlsDevCredentialVerifier,
   mlsDevDeviceHttpConfiguration,

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   MLS_SETUP_ACTIONS,
+  RUNNER_CLIENT,
   acpDriver,
   awaitErrand,
   checkAcp,
@@ -25,28 +26,30 @@ import {
   runMlsDevSetup,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-TJBG6NKF.js";
+} from "./chunks/chunk-B6AOBWNZ.js";
 import {
   assertPrivateHome,
   runnerLockName
-} from "./chunks/chunk-POBMFS2K.js";
+} from "./chunks/chunk-BQGXOAIW.js";
 import {
   CanonApiError,
   CanonClient,
   acquireLock,
+  clearPendingRegistration,
+  ensureAgentProfile,
   isProfileLocked,
+  loadPendingRegistrations,
   loadProfiles,
-  readCliPackageVersion,
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-HTLKCUQG.js";
-import "./chunks/chunk-BPSFHEAA.js";
-import "./chunks/chunk-2NVLVPSG.js";
+} from "./chunks/chunk-SS22I6HM.js";
+import "./chunks/chunk-HFT75BNB.js";
+import "./chunks/chunk-NIORQKUI.js";
 import {
-  __name,
-  isCanonClientVersion
-} from "./chunks/chunk-VIS5WXNH.js";
+  AGENT_HOME_ELSEWHERE,
+  __name
+} from "./chunks/chunk-CUPSYLBV.js";
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
@@ -54,8 +57,25 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-var RUNNER_VERSION = readCliPackageVersion(import.meta.url);
-var RUNNER_CLIENT = isCanonClientVersion(RUNNER_VERSION) ? { kind: "runner", version: RUNNER_VERSION } : void 0;
+var OWNER_DECLINED = "OWNER_DECLINED";
+function exitCodeFor(error) {
+  const code = error?.code;
+  return code === AGENT_HOME_ELSEWHERE || code === OWNER_DECLINED ? 0 : 1;
+}
+__name(exitCodeFor, "exitCodeFor");
+function stopThenExit(stop, code, exit = process.exit, boundMs = 15e3) {
+  let done = false;
+  const finish = /* @__PURE__ */ __name(() => {
+    if (!done) {
+      done = true;
+      clearTimeout(bound);
+      exit(code);
+    }
+  }, "finish");
+  const bound = setTimeout(finish, boundMs);
+  void Promise.resolve().then(stop).catch(() => void 0).finally(finish);
+}
+__name(stopThenExit, "stopThenExit");
 function once(handler) {
   let called = false;
   return (...args) => {
@@ -69,6 +89,8 @@ __name(once, "once");
 var HELP = `canon-agent: run a Canon agent on the unified runner
 
 Usage:
+  canon-agent run --driver <driver> --name <name> --owner-phone <+E.164> [--description <text>]
+                  [--environment <id>] ...    (the first run: registers the agent, then runs)
   canon-agent run --driver code --module <path> [--profile <name>] [--environment <id>]
   canon-agent run --driver claude [--cwd <dir>] [--model <id>] [--permission-mode <mode>]
                   [--claude-path <path>] [--profile <name>] [--environment <id>]
@@ -99,6 +121,19 @@ 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.
 
+First run: with --name and --owner-phone, a run whose profile (--profile, default the
+name) has no key asks the owner to approve the agent in Canon, waits up to 30 minutes,
+saves the profile and runs. A run whose saved key Canon refuses asks the owner for a
+new key for the same agent the same way; the agent keeps its conversations, devices and
+connections. The request stays open while nobody answers: run the command again to keep
+waiting. A declined request ends the run.
+
+One home: an agent answers from one place at a time. A run on a new machine, or with an
+empty $CANON_HOME, takes it over at start, and the run it replaced stops and exits 0, so
+a supervisor that restarts only on failure leaves it stopped. That run does not take the
+home back by itself; start it with --take-over to move the agent back there. While the
+agent's owner has Canon's relay on for its MCP connection, no run starts (exit 0).
+
 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,
@@ -191,6 +226,8 @@ Flags:
                          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.
+  --take-over            Move the agent's home back to this machine after a run
+                         elsewhere took it over.
   --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
@@ -221,6 +258,9 @@ Flags:
                          1 unless it was accepted (a note kept, a post sent, an errand's
                          turn ended and any report it sent to --origin accepted).
   --profile <name>       A profile in $CANON_HOME/agents.json (key and endpoints).
+  --name <name>          run: the agent's name, to register it (with --owner-phone).
+  --owner-phone <phone>  run: the owner's phone number in Canon, international format.
+  --description <text>   run: what the agent does, shown to its owner (default: the name).
   --environment <id>     canon-prod-v1 or canon-dev-v1 (default: CANON_ENVIRONMENT_ID).
   --help, -h             Show this help.
   --version, -V          Show the package version.
@@ -310,10 +350,11 @@ async function main() {
   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 registered = await ensureRegistered(values, values.driver);
+  if (registered) values.profile = registered;
   const { environmentId, home, profile, apiKey } = await settings(values);
   const mls = await mlsDevice(values, environmentId, home);
-  const baseUrl = process.env.CANON_BASE_URL || profile?.baseUrl;
-  const streamUrl = process.env.CANON_STREAM_URL || profile?.streamUrl;
+  const { apiBaseUrl: baseUrl, streamUrl } = connectionFor(environmentId, profile);
   let driver;
   if (values.driver === "claude") {
     driver = claudeDriver({
@@ -366,8 +407,8 @@ async function main() {
     ...team,
     ...trustedAgents.length ? { trustedAgents } : {},
     ...values["allow-session-for-destructive"] ? { sessionApprovalForDestructive: true } : {},
-    ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {},
     ...wake !== void 0 ? { wake } : {},
+    ...values["take-over"] ? { takeOver: true } : {},
     // 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.`);
@@ -378,7 +419,7 @@ async function main() {
     }) } : {},
     onFatal: once((error) => {
       console.error(`canon-agent: ${error.message}`);
-      void runner.stop().catch(() => void 0).finally(() => process.exit(1));
+      stopThenExit(() => runner.stop(), exitCodeFor(error));
     })
   });
   stopOnSignals(() => runner.stop());
@@ -394,8 +435,7 @@ __name(main, "main");
 async function runRelay(values, team) {
   const { environmentId, home, profile } = await settings(values, { key: false });
   const relay = await loadRelayConfiguration(values["relay-config"], { environmentId });
-  const baseUrl = process.env.CANON_BASE_URL || profile?.baseUrl;
-  const streamUrl = process.env.CANON_STREAM_URL || profile?.streamUrl;
+  const { apiBaseUrl: baseUrl, streamUrl } = connectionFor(environmentId, profile);
   let current;
   let latest;
   let switching = Promise.resolve();
@@ -446,10 +486,12 @@ async function runRelay(values, team) {
       relay: true,
       installationId: stored2.installationId,
       ...team,
-      ...RUNNER_CLIENT ? { client: RUNNER_CLIENT } : {},
       onFatal: once((error) => {
         console.error(`canon-agent: ${error.message}`);
-        void Promise.resolve().then(() => channel.close()).then(() => runner.stop()).catch(() => void 0).finally(() => process.exit(1));
+        stopThenExit(async () => {
+          await channel.close();
+          await runner.stop();
+        }, 1);
       })
     });
     try {
@@ -522,11 +564,85 @@ function parse() {
       cancel: { type: "string" },
       "wake-config": { type: "string" },
       "wake-off": { type: "boolean" },
-      "idle-timeout": { type: "string" }
+      "idle-timeout": { type: "string" },
+      "take-over": { type: "boolean" },
+      name: { type: "string" },
+      "owner-phone": { type: "string" },
+      description: { type: "string" }
     }
   });
 }
 __name(parse, "parse");
+var REGISTRATION_WAIT_MS = 30 * 6e4;
+var REGISTRATION_CLIENT_TYPES = { claude: "claude-code", codex: "codex" };
+async function ensureRegistered(values, driver) {
+  const name = values.name?.trim(), ownerPhone = values["owner-phone"]?.trim();
+  if (!name && !ownerPhone && values.description === void 0) return void 0;
+  if (!name || !ownerPhone) throw new UsageError("--name and --owner-phone go together (and --description with them).");
+  if (process.env.CANON_API_KEY) throw new UsageError("--name and --owner-phone keep the agent's key in a profile: unset CANON_API_KEY.");
+  const environmentId = values.environment || process.env.CANON_ENVIRONMENT_ID;
+  if (!environmentId) throw new Error("CANON_ENVIRONMENT_ID (or --environment) is required.");
+  const home = resolve(process.env.CANON_HOME || join(homedir(), ".canon"));
+  await assertPrivateHome(home);
+  const profile = values.profile || name;
+  const saved = loadProfiles(home)[profile];
+  if (saved && saved.environmentId !== environmentId) throw new Error(`Profile "${profile}" belongs to ${saved.environmentId}, not ${environmentId}.`);
+  const connection = connectionFor(environmentId, saved);
+  const agentName = saved?.agentName ?? name;
+  const register = /* @__PURE__ */ __name(async (reconnect) => {
+    const pending = loadPendingRegistrations()[profile];
+    const ask = reconnect || pending?.requestedAgentId ? `a new key for ${agentName}` : agentName;
+    const waiting = /* @__PURE__ */ __name(() => console.error(`canon-agent: ask the owner of ${ownerPhone} to approve ${ask} in Canon. Waiting up to 30 minutes; the request stays open until they answer, and running this command again keeps waiting.`), "waiting");
+    if (pending && !pending.credentialAgentId) waiting();
+    const asked = reconnect || !!pending || !saved;
+    const progress = await ensureAgentProfile({
+      profile,
+      reconnect,
+      waitMs: REGISTRATION_WAIT_MS,
+      onSubmitted: waiting,
+      connection,
+      input: {
+        name,
+        description: values.description?.trim() || name,
+        ownerPhone,
+        clientType: REGISTRATION_CLIENT_TYPES[driver] ?? "generic",
+        developerInfo: `canon-agent run --driver ${driver}`
+      }
+    });
+    switch (progress.status) {
+      case "approved":
+        if (asked) console.error(`canon-agent: ${progress.agentName} is approved; its key is saved in profile "${profile}".`);
+        return progress.apiKey;
+      case "pending":
+        throw new Error(`Nobody has answered the request for ${ask} yet. It stays open: run this command again to keep waiting.`);
+      case "rejected":
+        clearPendingRegistration(profile);
+        throw Object.assign(new Error(`The owner declined ${ask}. Nothing was saved; run this command again to ask again.`), { code: OWNER_DECLINED });
+      case "credential-expired":
+        clearPendingRegistration(profile);
+        throw new Error(`The owner approved ${ask}, but its key was not collected within 48 hours and Canon removed it. Run this command again to ask again.`);
+      case "credential-delivered":
+        clearPendingRegistration(profile);
+        throw new Error(`The key for ${ask} was already collected elsewhere, so this run cannot have it. Run this command again to ask again.`);
+    }
+  }, "register");
+  const apiKey = await register(false);
+  try {
+    await new CanonClient(apiKey, resolveCanonRuntimeConnection(connection).apiBaseUrl).getAgentMe();
+    return profile;
+  } catch (error) {
+    if (!(error instanceof CanonApiError) || error.status !== 401) throw error;
+  }
+  console.error(`canon-agent: Canon no longer accepts ${agentName}'s saved key.`);
+  await register(true);
+  return profile;
+}
+__name(ensureRegistered, "ensureRegistered");
+function connectionFor(environmentId, profile) {
+  const apiBaseUrl = process.env.CANON_BASE_URL || profile?.baseUrl, streamUrl = process.env.CANON_STREAM_URL || profile?.streamUrl;
+  return { environmentId, ...apiBaseUrl ? { apiBaseUrl } : {}, ...streamUrl ? { streamUrl } : {} };
+}
+__name(connectionFor, "connectionFor");
 async function settings(values, { key = true } = {}) {
   const environmentId = values.environment || process.env.CANON_ENVIRONMENT_ID;
   if (!environmentId) throw new Error("CANON_ENVIRONMENT_ID (or --environment) is required.");
@@ -564,11 +680,7 @@ async function mlsSetup(values) {
   let client;
   let lock;
   try {
-    const connection = resolveCanonRuntimeConnection({
-      environmentId,
-      apiBaseUrl: process.env.CANON_BASE_URL || profile?.baseUrl,
-      streamUrl: process.env.CANON_STREAM_URL || profile?.streamUrl
-    });
+    const connection = resolveCanonRuntimeConnection(connectionFor(environmentId, profile));
     await verifyCanonRuntimeConnection(connection);
     client = new CanonClient(apiKey, connection.apiBaseUrl, {
       environmentId,
@@ -660,5 +772,10 @@ __name(stopOnSignals, "stopOnSignals");
 runCli(import.meta.url, main, (error) => {
   console.error(`canon-agent: ${error instanceof Error ? error.message : String(error)}`);
   if (error instanceof UsageError) console.error(HELP.split("\n\nFlags:")[0]);
-  process.exit(1);
+  process.exit(error instanceof UsageError ? 1 : exitCodeFor(error));
 }, { name: "canon-agent", help: HELP });
+export {
+  ensureRegistered,
+  exitCodeFor,
+  stopThenExit
+};

package/dist/index.js

@@ -26,8 +26,8 @@ import {
   runMlsDevSetup,
   runtimeDescriptor,
   startRelayChannel
-} from "./chunks/chunk-TJBG6NKF.js";
-import "./chunks/chunk-POBMFS2K.js";
+} from "./chunks/chunk-B6AOBWNZ.js";
+import "./chunks/chunk-BQGXOAIW.js";
 import {
   CanonApiError,
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
@@ -52,10 +52,10 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-HTLKCUQG.js";
-import "./chunks/chunk-BPSFHEAA.js";
-import "./chunks/chunk-2NVLVPSG.js";
-import "./chunks/chunk-VIS5WXNH.js";
+} from "./chunks/chunk-SS22I6HM.js";
+import "./chunks/chunk-HFT75BNB.js";
+import "./chunks/chunk-NIORQKUI.js";
+import "./chunks/chunk-CUPSYLBV.js";
 export {
   CanonApiError,
   ConnectorRelayError,

package/dist/internal/agent-tools/communication-tool.d.ts

@@ -0,0 +1,80 @@
+import { type CanonClient, type CommunicateInput } from '../core/index.js';
+export interface VerbToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface VerbToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare const CANON_COMMUNICATE_TOOL_NAME = "communicate";
+export declare const CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS = 10;
+/**
+ * What each action takes: the fields it needs, then those it may have. The legacy aliases (start_direct,
+ * create_group, manage_group_members) take their action's fields; the parser still accepts them, and no schema offers them.
+ */
+declare const ACTION_FIELDS: {
+    readonly list_conversations: {
+        readonly required: readonly [];
+        readonly optional: readonly ["limit"];
+    };
+    readonly discover_agents: {
+        readonly required: readonly [];
+        readonly optional: readonly ["query", "limit", "cursor"];
+    };
+    readonly message_existing: {
+        readonly required: readonly ["conversationId", "text"];
+        readonly optional: readonly ["messageId"];
+    };
+    readonly start_conversation: {
+        readonly required: readonly ["principalId", "text"];
+        readonly optional: readonly ["selection", "messageId"];
+    };
+    readonly create_conversation: {
+        readonly required: readonly ["memberIds"];
+        readonly optional: readonly ["name"];
+    };
+    readonly manage_participants: {
+        readonly required: readonly ["conversationId", "userId", "operation"];
+        readonly optional: readonly [];
+    };
+    readonly leave_conversation: {
+        readonly required: readonly ["conversationId"];
+        readonly optional: readonly [];
+    };
+    readonly forward_message: {
+        readonly required: readonly ["sourceConversationId", "targetConversationId", "messageId"];
+        readonly optional: readonly ["text"];
+    };
+    readonly share_contact: {
+        readonly required: readonly ["conversationId", "contactUserId"];
+        readonly optional: readonly ["text", "messageId"];
+    };
+};
+export type CanonCommunicateAction = keyof typeof ACTION_FIELDS;
+/** The actions a binding offers, each with the fields it shows for it (an action's required fields always). */
+export type CommunicateShape = Readonly<Partial<Record<CanonCommunicateAction, readonly string[]>>>;
+/** Every action with every field: the complete communication surface. */
+export declare const CANON_COMMUNICATE_SHAPE: CommunicateShape;
+/**
+ * One flat object schema for `communicate`: `action` names the action, and every other field is optional and says which
+ * actions take it. Claude reads a tool's schema as one object, so a top-level `oneOf` showed it only its first
+ * alternative (the driver trial on Dev, 2026-11-09); the parser checks each combination instead.
+ */
+export declare function communicateInputSchema(shape: CommunicateShape, textMaxLength?: number | null): Record<string, unknown>;
+/**
+ * The complete model-facing communication surface. It is exported separately
+ * from the in-conversation verb list so each runtime can opt into it.
+ */
+export declare function canonCommunicateToolDefinition(name?: string): VerbToolDefinition;
+/**
+ * Runtime validation for bindings that dispatch directly. The schema is flat, so this is where a combination is checked:
+ * an action the binding does not offer, a field the action needs, or one it does not take, is refused by name.
+ */
+export declare function parseCommunicateToolInput(value: unknown, shape?: CommunicateShape): CommunicateInput;
+export declare function executeCanonCommunicateTool(client: CanonClient, args: unknown, shape?: CommunicateShape): Promise<VerbToolResult>;
+export {};

package/dist/internal/agent-tools/index.d.ts

@@ -0,0 +1 @@
+export { CANON_COMMUNICATE_DISCOVERY_MAX_RESULTS, CANON_COMMUNICATE_SHAPE, CANON_COMMUNICATE_TOOL_NAME, canonCommunicateToolDefinition, communicateInputSchema, executeCanonCommunicateTool, parseCommunicateToolInput, type CanonCommunicateAction, type CommunicateShape, type VerbToolDefinition, type VerbToolResult, } from './communication-tool.js';

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

@@ -118,3 +118,28 @@ export declare const ENDPOINT_ID_PATTERN: RegExp;
 export declare const ENDPOINT_ACTION_PATTERN: RegExp;
 export declare function isEndpointOperationRequest(value: unknown): value is EndpointOperationRequest;
 export declare function isEndpointOperationReceipt(value: unknown): value is EndpointOperationReceipt;
+/**
+ * An agent answers from one home at a time: Canon's relay for its MCP connection while the owner has the relay on,
+ * otherwise its runner, the installation that started most recently (`initialize_endpoint` moves it there). Everything
+ * the other home sends is refused with `AGENT_HOME_ELSEWHERE`, so no message gets two answers. It is read from the
+ * agent's own document alone (`users/{agentId}`), so every hot path can check it without another read.
+ *
+ * `since` (ms, Canon's clock): this home answers for work from here, for its work floor and in the refusal's text. Nothing
+ * Canon accepted before it is that home's work, since the home before may have answered it. For the relay, its approval.
+ * For a runner, the later of `installedAt` and the relay's turn-off, after which the runner it replaced is the home again
+ * by itself. Despite its name, `installedAt` holds where its installation answers for work from (its baseline's cutover):
+ * a first installation's approval, a later one's take-over. Older markers hold a first installation's first start, and
+ * are read as they are.
+ */
+export declare const AGENT_HOME_ELSEWHERE = "AGENT_HOME_ELSEWHERE";
+export type AgentHome = {
+    kind: 'connector';
+    since?: number;
+} | {
+    kind: 'runner';
+    installationId?: string;
+    since?: number;
+};
+export declare function readAgentHome(agentConfig: unknown): AgentHome;
+/** The one refusal both homes give the other: what is true now, and what the owner or operator can do. */
+export declare function agentHomeElsewhereMessage(agentName: string | undefined, home: AgentHome): string;

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

@@ -1,5 +1,9 @@
 export declare const MLS_DEV_KEY_PACKAGES_MAX_BYTES = 32768;
 export declare const MLS_DEV_KEY_PACKAGE_TLS_MAX_BYTES = 16384;
+/** How long a claim holds its recipient's slot before another member's device may take it over (mls-rooms-by-default.md
+ * §2.4). On Dev from 2026-10-20 to 11-08, 113 Adds were accepted a median 2.4 s after their claim, 99% within 9.4 s, and
+ * the slowest in 61.5 s: two minutes is about twice the slowest, and a dead claimant holds a device off no longer. */
+export declare const MLS_DEV_KEY_PACKAGE_CLAIM_LEASE_MS: number;
 export interface MlsDevKeyPackagePublishRequest {
     readonly version: 1;
     readonly requestId: string;

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

@@ -8,10 +8,6 @@ export interface ResumableMediaUploadResult {
     status?: 'processing' | 'ready' | 'failed';
     attachment: MediaAttachment;
 }
-/**
- * Agent-facing ergonomics over the shared endpoint engine. Authentication and
- * operator registration remain outside the conversation protocol.
- */
 export declare class CanonClient {
     private baseUrl;
     private apiKey;

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

@@ -30,6 +30,14 @@ export interface CanonClientEndpointOptions {
     mediaDirectory?: string;
     /** Operator inspection/import does not automatically publish queued operations. */
     autoDrain?: boolean;
+    /**
+     * This client is the agent's runner, and its installation is the agent's home: a new installation takes the home at
+     * start; one that lost it to another refuses to start (`AGENT_HOME_ELSEWHERE`) unless `takeOver` moves it back, so two
+     * supervised machines never take it from each other in turn. Other clients (a script, a CLI step) never move the home.
+     */
+    claimHome?: boolean;
+    /** With `claimHome`: move the home back to this installation after another one took it. */
+    takeOver?: boolean;
     /** Replicated cloud hosts supply operator-owned durable byte storage. */
     mediaBytes?: EndpointMediaBytes<string>;
     /** Test seam for the client's out-of-protocol HTTP (identity, profile); production leaves it unset. */

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

@@ -55,5 +55,5 @@ export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, run
 export type { CliMetadata, RunCliMetadataOptions, } from './cli-metadata.js';
 export { CANON_VERB_NAMES, CANON_VERB_NAMESPACE, CANON_VERBS_SCHEMA_ID, CANON_VERBS_SCHEMA_VERSION, CANON_VERB_WIRE_SCHEMA_ID, CANON_VERB_WIRE_SCHEMA_VERSION, CANON_CARD_SCHEMA_ID, VERB_LIMITS, VERB_RATE_LIMITS, VERB_WIRE_ENVELOPE_FIELDS, canonVerbToolName, findVerbByteLimitViolations, findVerbWireEnvelopeViolations, getVerbResultSchema, mergeVerbWireToIntent, normalizeVerbNativeMetadata, projectVerbIntentToWire, type CanonVerbName, type CanonVerbWireEnvelope, type CanonVerbWireRequest, type CanonVerbWireResponse, type CanonVerbJsonSchema, type SendToInput, type SendToResult, type VerbMessageOptions, type VerbNativeMetadata, type VerbWireAccepted, type VerbWireBody, } from '../backend-contracts/index.js';
 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 { MLS_DEV_TEXT_MAX_BYTES, 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';

package/dist/internal/core/registration-profile.d.ts

@@ -3,7 +3,10 @@ export interface EnsureAgentProfileOptions extends Omit<ResumeRegistrationOption
     /** The local profile store owns its stable localRegistrationId. */
     input: Omit<ResumeRegistrationOptions['input'], 'localRegistrationId'>;
     profile: string;
-    /** Explicitly request a new registration even if a usable local credential exists. */
+    /**
+     * Ask the owner for a new key for this profile's agent (its saved agent ID, or `input.requestedAgentId`), even if a
+     * usable local credential exists. Approval only replaces the key: the agent keeps its rooms, devices and connections.
+     */
     reconnect?: boolean;
 }
 /** Reuse an environment-bound local profile, or resume its owner-approved registration. */

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

@@ -1,4 +1,4 @@
-import type { AgentOrigin, AgentOriginDeclaration, ArtifactContext } from '../backend-contracts/index.js';
+import type { AgentHome, AgentOrigin, AgentOriginDeclaration, ArtifactContext } from '../backend-contracts/index.js';
 import type { CanonControlValue, CanonRuntimeStreamingMode, CanonRuntimeDetailTier, CanonRuntimeVisibility, CanonRuntimeCommandDescriptor } from '../backend-contracts/index.js';
 export type { AgentOrigin, AgentOriginDeclaration, CanonControlValue, CanonRuntimeStreamingMode, CanonRuntimeDetailTier, CanonRuntimeVisibility, CanonRuntimeActionAvailability, CanonRuntimeActionPlacement, CanonRuntimeActionCategory, CanonRuntimePrimitiveId, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionDescriptor, CanonRuntimeCommandDescriptor, } from '../backend-contracts/index.js';
 import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
@@ -479,6 +479,8 @@ export interface AgentContext {
     ownershipVersion: number;
     /** Server-created new-principal marker; initialization still binds the installation atomically. */
     endpointBootstrapEligible?: boolean;
+    /** Where the agent answers from: Canon's relay, or the runner installation that started last (absent from older Canon). */
+    home?: AgentHome;
     canonContactId?: string;
     displayName?: string;
     avatarUrl?: string | null;

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

@@ -72,6 +72,11 @@ export interface EndpointOperation {
     /** Local-only binding of a withheld start's text; retained after the opener is sent or its payload is erased. */
     openerFingerprint?: string;
     receipt?: EndpointOperationReceipt;
+    /** A refused encrypted send this device encrypted again: the operation that replaced it, which retries and waits
+     * follow (mls-dev-groups.ts, resendText). */
+    resentAs?: string;
+    /** Local successor made after Canon refused an encrypted send, with readers and sender admission rechecked. */
+    automaticResend?: boolean;
     attempts: number;
     attempted: boolean;
     nextAttemptAt?: number;
@@ -148,10 +153,15 @@ export interface Endpoint {
     submit(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<EndpointOperation>;
     execute<T = unknown>(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<EndpointOperationReceipt<T>>;
     executeResult<T = unknown>(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<T>;
-    /** reconcileOnly reads the server receipt; it never dispatches an operation. */
+    /** reconcileOnly reads and records the server receipt; it never dispatches or encrypts again. An operation encrypted
+     * again (`resentAs`) answers with the one that replaced it. An ordinary retry of a send Canon refused one change behind
+     * encrypts it again, by the rule its first refusal had, when a reconcile only recorded the refusal. */
     retry<T = unknown>(operationId: string, options?: {
         reconcileOnly?: boolean;
     }): Promise<EndpointOperationReceipt<T>>;
+    /** A person's Retry of an encrypted message Canon refused: encrypts it again, from this device's copy, for its room as
+     * it is now, under a new operation that replaces the refused one. Returns the operation to retry. */
+    resend(operationId: string): Promise<EndpointOperation>;
     drain(options?: {
         limit?: number;
     }): Promise<void>;
@@ -192,8 +202,9 @@ export interface Endpoint {
     cancelMessageGroup(id: string): Promise<void>;
     /** Runtime-specific publication policy; closures are never serialized.
      * Return false to defer, or throw a nonretryable EndpointError to retire an
-     * unsent operation. An attempted operation still needs its server receipt. */
-    registerDeliveryGuard(id: string, allow: () => Promise<boolean>): () => void;
+     * unsent operation. An attempted operation still needs its server receipt.
+     * Automatic resends retain the policy; only an audience-specific check may use the revalidated resend context. */
+    registerDeliveryGuard(id: string, allow: EndpointDeliveryGuard): () => void;
     /** Keep a start's opening line that Canon did not store, and send it once the room and the request allow (§2a.13). */
     deferOpener(input: {
         conversationId: string;
@@ -216,6 +227,21 @@ export interface Endpoint {
     /** Immutable operator-reviewed or server-proven cutover for new rooms/admissions. */
     configureRecoveryBaseline(config: EndpointRecoveryBaseline): Promise<void>;
     getRecoveryBaseline(): Promise<EndpointRecoveryBaseline | undefined>;
+    /**
+     * Work here starts at `cutoverAt` (Canon's clock), where this installation's turn as its agent's home began: a
+     * take-over, or Canon's relay turned off. Every input Canon accepted before it is history, never work, whether it is
+     * already in the inbox or still to come off a room's feed, since the home before may have answered it. Only an input a
+     * journaled output answers keeps it. The floor only ever moves later.
+     */
+    startWorkAt(cutoverAt: string): Promise<void>;
+    /**
+     * A runner moving its agent's home here, under a new `initialize_endpoint` operation each time, starts work from
+     * Canon's answer (`startWorkAt`). Only this call sends it. One that fails, or that a process left unanswered when it
+     * died, is never sent again (the latter is settled when the store next opens, before anything drains), so no later
+     * start makes a take-over without its operator. If Canon took the home all the same, the next start reads that from the
+     * agent's home and starts work from there.
+     */
+    takeOverHome(): Promise<void>;
     refreshRecovery(): Promise<void>;
     planRecoveryMigration(baseline: EndpointRecoveryBaseline, conversationIds?: string[]): Promise<EndpointRecoveryMigration>;
     importRecoveryMigration(manifest: EndpointRecoveryMigration, reviewedSha256: string): Promise<EndpointMigrationReceipt>;
@@ -266,5 +292,8 @@ export interface Endpoint {
     logout(): Promise<void>;
     close(): Promise<void>;
 }
+export type EndpointDeliveryGuard = (context: {
+    automaticResend: boolean;
+}) => Promise<boolean>;
 export declare function mergeConversationSnapshot<T extends EndpointConversation>(current: T | undefined, incoming: T): T;
 export declare function createEndpoint(options: EndpointOptions): Endpoint;

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

@@ -1,4 +1,4 @@
-import type { Endpoint } from './engine.js';
+import type { Endpoint, EndpointDeliveryGuard } from './engine.js';
 import { type EndpointStore } from './store.js';
 export interface EndpointMediaDescriptor {
     mimeType: string;
@@ -64,7 +64,7 @@ export interface EndpointMediaProgress {
 export interface EndpointMediaSendOptions {
     signal?: AbortSignal;
     onProgress?: (progress: EndpointMediaProgress) => void;
-    beforePublish?: () => Promise<boolean>;
+    beforePublish?: EndpointDeliveryGuard;
 }
 export interface EndpointMediaInput<Source> {
     conversationId: string;

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

@@ -48,6 +48,8 @@ export interface MlsDevAdmissionHold {
     readonly waitingPrincipalIds: readonly string[];
     /** This device joined after the room's first message, so its history starts later (mls-rooms-by-default.md §2.7). */
     readonly missedEarlier?: true;
+    /** The room's group exists and this device is not in it: only a device already there can add it (§2.4). */
+    readonly outside?: true;
 }
 export interface MlsDevCurrentAudience {
     readonly version: 1;
@@ -166,6 +168,8 @@ export interface MlsDevGroupBridge {
     /** Reads and applies the room's conversation snapshot from Canon, for openings of members admitted since. */
     readRoom?(conversationId: string): Promise<unknown>;
 }
+/** How many times a refused send is encrypted again by itself before it shows as not sent. */
+export declare const MLS_DEV_RESEND_MAX = 3;
 /** Internal attachment: the engine supplies its existing queue, receipt reducer,
  * event/recovery intake, store and lifetime. Native work never runs inside tx. */
 export declare function createMlsDevGroups(options: MlsDevDeviceClientOptions, context: MlsDevDeviceClientContext, keyPackages: MlsDevKeyPackageClient | undefined, bridge: MlsDevGroupBridge): {
@@ -175,6 +179,8 @@ export declare function createMlsDevGroups(options: MlsDevDeviceClientOptions, c
      * encrypted room (mls-payload-v3.md §4). Items and cards are not forwarded yet. */
     forwardText(value: unknown, operationId: string, guardId?: string): Promise<EndpointOperation>;
     sendText(value: unknown, operationId: string, guardId?: string): Promise<EndpointOperation>;
+    /** A person's Retry of a text or item Canon refused: encrypted again for the room as it is now (`resendText`). */
+    resendText(operation: EndpointOperation): Promise<EndpointOperation | undefined>;
     /** `sendText` for a person's composer: in a held room the text is kept, not refused (undefined), until `sendHeldTexts`. */
     holdText(value: unknown, operationId: string): Promise<EndpointOperation | undefined>;
     sendHeldTexts(conversationId: string): Promise<{
@@ -196,6 +202,8 @@ export declare function createMlsDevGroups(options: MlsDevDeviceClientOptions, c
     syncText(conversationId: string, options?: EndpointSyncOptions): Promise<EndpointSyncPage>;
     isTextReady: (conversationId: string) => Promise<boolean>;
     readAcceptedReceipt(operation: EndpointOperation): Promise<EndpointOperationReceipt | undefined>;
-    settleReceipt(operation: EndpointOperation, receipt: EndpointOperationReceipt): Promise<boolean>;
+    settleReceipt(operation: EndpointOperation, receipt: EndpointOperationReceipt, options?: {
+        reconcileOnly?: boolean;
+    }): Promise<boolean>;
 };
 export {};