@canonmsg/agent-sdk 12.3.1 → 12.4.1

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

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

package/dist/cli.js

@@ -3,6 +3,7 @@ import {
   MLS_SETUP_ACTIONS,
   assertPrivateHome,
   awaitErrand,
+  bundledMlsCustodyHelper,
   checkCodex,
   claudeDriver,
   codeDriver,
@@ -15,6 +16,7 @@ import {
   loadInstructions,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  managedMlsDevice,
   queueErrand,
   readRelayCredential,
   relayRunnerHome,
@@ -22,7 +24,7 @@ import {
   runnerLockName,
   startRelayChannel,
   writeRelayCredential
-} from "./chunks/chunk-HI2SVCUL.js";
+} from "./chunks/chunk-NXL4C2R6.js";
 import {
   CanonApiError,
   CanonClient,
@@ -33,11 +35,12 @@ import {
   resolveCanonRuntimeConnection,
   runCli,
   verifyCanonRuntimeConnection
-} from "./chunks/chunk-SKFI2MJA.js";
+} from "./chunks/chunk-6PKXASSK.js";
 import {
   __name,
-  isCanonClientVersion
-} from "./chunks/chunk-5MI6Q3VS.js";
+  isCanonClientVersion,
+  isMlsEnvironmentId
+} from "./chunks/chunk-GWQF4WFT.js";
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
@@ -66,9 +69,9 @@ Usage:
   canon-agent run --driver codex [--cwd <dir>] [--model <id>] [--sandbox <mode>]
                   [--approval-policy <policy>] [--codex-path <path>] [--profile <name>]
                   [--environment <id>]
-  canon-agent run --driver connector --relay-config <path> --mls-dev-config <path>
+  canon-agent run --driver connector --relay-config <path> [--mls-dev-config <path>]
                   [--profile <name>] [--environment <id>]
-  canon-agent mls --action <action> --mls-dev-config <path> [--room <id>]
+  canon-agent mls --action <action> [--mls-dev-config <path>] [--room <id>]
                   [--relay-config <path>] [--profile <name>] [--environment <id>]
   canon-agent tell --room <id> --text <text> (--agent <id> | --profile <name>)
                   [--environment <id>] [--wait]
@@ -80,10 +83,12 @@ Usage:
   canon-agent errands [--follow] [--cancel <errand id>] (--agent <id> | --profile <name>)
                   [--environment <id>]
 
-Every run command also takes --mls-dev-config <path>, which gives the agent its MLS
-device so it can take part in encrypted rooms. Without it, the agent refuses encrypted
-rooms and logs each one once; where Canon encrypts every new conversation, it does not
-start.
+Encrypted rooms need the agent's MLS device. On macOS (Apple silicon) and Linux
+(x64, arm64) the runner keeps it in $CANON_HOME with the custody helper this package
+ships, and sets it up on the agent's first start: nothing to configure. Every run
+command also takes --mls-dev-config <path>, an operator's own custody instead. With
+neither, the agent refuses encrypted rooms, and where Canon encrypts every new
+conversation it does not start.
 
 Team rooms (an owner's agents working together): claude and codex also take
 [--instructions <file>] [--trust-agent <agentId>]...; every run command takes
@@ -146,20 +151,22 @@ Flags:
                          marks destructive (Claude Code's default-to-no prompts,
                          Codex's risky commands and deletions) for the rest of the
                          session. Off by default: each such action asks.
-  --relay-config <path>  connector (Dev only): run as Canon's class-C relay for one agent
+  --relay-config <path>  connector: run as Canon's class-C relay for one agent
                          connected through Canon's MCP connector. A private JSON file
                          naming the agent, where the channel to Canon's Functions
                          listens, and the path of the channel secret. Canon delivers
                          the relay's own credential over that channel when the owner
                          enables the relay (no API key is used); it is kept in
                          $CANON_HOME/relay. The relay serves only encrypted rooms,
-                         which are then not end-to-end encrypted to that agent. With
-                         "mls", it sets up the relay's device with that credential.
-  --mls-dev-config <p>   The operator's MLS configuration: an absolute path to a private
-                         JSON file with the environment's issuer pins and the custody
-                         helper (no keys or credentials).
-  --action <action>      mls: status (public device state), provision (create the
-                         portable vault, once), enroll, renew, publish (this device's
+                         which are then not end-to-end encrypted to that agent. It sets
+                         up the relay's device with that credential.
+  --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
+                         keys or credentials).
+  --action <action>      mls: status (public device state), setup (whatever is left of
+                         provision then enroll), provision (create the portable vault,
+                         once), enroll, renew, publish (this device's
                          KeyPackage for --room) or refresh (catch up --room). It never
                          starts a model, and uses the same home as "run": stop the
                          agent first.
@@ -232,7 +239,6 @@ async function main() {
   }
   if (values.driver === "code" && !values.module) throw new UsageError("--driver code needs --module <path>.");
   if (values.driver === "connector" !== !!values["relay-config"]) throw new UsageError("--relay-config goes with --driver connector, which needs it.");
-  if (values.driver === "connector" && !values["mls-dev-config"]) throw new UsageError("--driver connector needs --mls-dev-config <path>: the relay holds the agent's MLS device.");
   if (!["claude", "codex"].includes(values.driver) && (values.instructions !== void 0 || values["trust-agent"]?.length)) {
     throw new UsageError("--instructions and --trust-agent go with --driver claude or codex.");
   }
@@ -254,7 +260,7 @@ 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 { environmentId, home, profile, apiKey } = await settings(values);
-  const mls = values["mls-dev-config"] ? await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId }) : void 0;
+  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;
   let driver;
@@ -352,7 +358,8 @@ async function runRelay(values, team) {
     channel.serve(void 0);
     await current?.stop();
     current = void 0;
-    const mls = await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
+    const mls = await mlsDevice(values, environmentId, relayRunnerHome(home, stored2.installationId));
+    if (!mls) throw new Error(`this host has no MLS custody helper (${process.platform}-${process.arch}): give the relay --mls-dev-config <path>`);
     const driver = connectorDriver();
     const runner = await createRunner({
       apiKey: stored2.credential,
@@ -455,11 +462,17 @@ async function settings(values, { key = true } = {}) {
   return { environmentId, home, profile, apiKey: process.env.CANON_API_KEY || profile?.apiKey || "" };
 }
 __name(settings, "settings");
+async function mlsDevice(values, environmentId, home) {
+  if (values["mls-dev-config"]) return loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
+  if (!isMlsEnvironmentId(environmentId)) return void 0;
+  const helper = bundledMlsCustodyHelper();
+  return helper ? managedMlsDevice({ home, environmentId, helper }) : void 0;
+}
+__name(mlsDevice, "mlsDevice");
 async function mlsSetup(values) {
   const action = values.action;
   if (!action || !MLS_SETUP_ACTIONS.includes(action)) throw new UsageError(`--action must be one of ${MLS_SETUP_ACTIONS.join(", ")}.`);
   if ((action === "publish" || action === "refresh") !== !!values.room) throw new UsageError("--room is needed for publish and refresh, and only for them.");
-  if (!values["mls-dev-config"]) throw new UsageError("--mls-dev-config <path> is required.");
   const settled = await settings(values, { key: !values["relay-config"] });
   const { environmentId, profile } = settled;
   const relay = values["relay-config"] ? await loadRelayConfiguration(values["relay-config"], { environmentId }) : void 0;
@@ -469,7 +482,8 @@ async function mlsSetup(values) {
   }
   const apiKey = stored ? stored.credential : settled.apiKey;
   const home = stored ? relayRunnerHome(settled.home, stored.installationId) : settled.home;
-  const config = await loadMlsDevConfiguration(values["mls-dev-config"], { environmentId });
+  const config = await mlsDevice(values, environmentId, home);
+  if (!config) throw new Error(`@canonmsg/agent-sdk ships no MLS custody helper for ${process.platform}-${process.arch}: give --mls-dev-config <path>.`);
   let client;
   let lock;
   try {
@@ -489,7 +503,7 @@ async function mlsSetup(values) {
     });
     const me = await client.getAgentMe();
     lock = acquireLock(runnerLockName(environmentId, me.agentId), home);
-    console.log(JSON.stringify(await runMlsDevSetup(await client.getEndpoint(), action, values.room, config.provision)));
+    console.log(JSON.stringify(await runMlsDevSetup(await client.getEndpoint(), action, values.room, config.provision, config.provisioned)));
   } finally {
     try {
       await client?.close();

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type { Runner, RunnerOptions } from './runner/runner.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';
+export { bundledMlsCustodyHelper, MLS_ENVIRONMENT_PINS } from './runner/mls-bundled.js';
+export { managedMlsDevice, type ManagedMlsDevice, type ManagedMlsDeviceOptions } from './runner/mls-managed.js';
 export type { ActivityEvent, AskAnswer, AskRequest, DriverCapabilities, DriverResult, DriverState, DriverTurn, ErrandFacts, RuntimeDriver, ToolDefinition, ToolResult, TurnInput, TurnInputMessage, TurnTools, } from './runner/types.js';
 export { errandJournal, errandsDirectory, queueErrand } from './runner/errands.js';
 export type { ErrandCommand, ErrandInput, ErrandKind, ErrandRecord, ErrandStatus } from './runner/errands.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 import {
   ConnectorRelayError,
   DriverSessionError,
+  MLS_ENVIRONMENT_PINS,
   MLS_SETUP_ACTIONS,
+  bundledMlsCustodyHelper,
   checkCodex,
   claudeDriver,
   codeDriver,
@@ -13,12 +15,13 @@ import {
   loadClaudeQuery,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  managedMlsDevice,
   mlsDevRoomPackageId,
   queueErrand,
   runMlsDevSetup,
   runtimeDescriptor,
   startRelayChannel
-} from "./chunks/chunk-HI2SVCUL.js";
+} from "./chunks/chunk-NXL4C2R6.js";
 import {
   CanonApiError,
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
@@ -43,8 +46,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-SKFI2MJA.js";
-import "./chunks/chunk-5MI6Q3VS.js";
+} from "./chunks/chunk-6PKXASSK.js";
+import "./chunks/chunk-GWQF4WFT.js";
 export {
   CanonApiError,
   ConnectorRelayError,
@@ -55,7 +58,9 @@ export {
   MAX_ANTHROPIC_IMAGE_RAW_BYTES,
   MAX_ANTHROPIC_REQUEST_BYTES,
   MAX_CANON_MEDIA_BYTES,
+  MLS_ENVIRONMENT_PINS,
   MLS_SETUP_ACTIONS,
+  bundledMlsCustodyHelper,
   checkCodex,
   claudeDriver,
   clearPendingRegistration,
@@ -74,6 +79,7 @@ export {
   loadClaudeQuery,
   loadMlsDevConfiguration,
   loadRelayConfiguration,
+  managedMlsDevice,
   materializeAttachment,
   materializeMessageMedia,
   materializeReplyContextMedia,

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

@@ -8,6 +8,11 @@ export type EndpointContentLane = 'operation.request' | 'operation.receipt' | 'q
  * authenticated encrypted protocol before they can operate on a protected room.
  * Their routing fields remain public metadata; classification is not authority. */
 export declare const MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS: readonly ["forward_message"];
+/** Operations that send their private content to a named processor in an encrypted room too, disclosed where the
+ * app offers them, with the fields reviewed for that: an image's description and source photo go through Canon to
+ * Google (image-generation.md). The fields stay classified as private; only the encrypted room's plaintext fence lets
+ * them through, and any other field still keeps the operation out. */
+export declare const MLS_DEV_DISCLOSED_PROCESSING_FIELDS: Readonly<Record<string, readonly string[]>>;
 export declare const ENDPOINT_CONTENT_ACTIONS: readonly ["mls_application", "mls_group_control", "initialize_endpoint", "append_artifact_command", "retain_artifact_asset", "sync_phone_contacts", "update_agent_behavior_policy", "update_conversation_agent_behavior_policy", "send_message", "delete_message", "forward_message", "react", "verb_execute", "send_contextual_message", "create_interaction", "consume_interaction", "start_conversation", "create_conversation", "add_member", "remove_member", "leave_conversation", "update_member_role", "update_conversation", "rename_conversation", "update_topic", "update_group_avatar", "mark_read", "cancel_queued_message", "set_conversation_preferences", "set_block", "save_contact", "remove_contact", "respond_interaction", "session_control", "approve_contact_request", "reject_contact_request", "cancel_direct_request", "update_message_disposition", "create_upload", "finalize_upload", "delete_upload", "retry_video_processing", "stage_media_message", "cancel_media_message", "renew_media_message_upload", "finalize_memo_stream", "abort_memo_stream", "create_voice_session", "join_voice_session", "decline_voice_session", "end_voice_session", "consume_runtime_signal", "consume_runtime_primitive", "generate_image"];
 export declare const ENDPOINT_CONTENT_FUNCTION_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status", "same_owner_agents"];
 export declare const ENDPOINT_CONTENT_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status", "same_owner_agents", "admit_messages"];

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

@@ -105,6 +105,14 @@ export interface MlsDevGroupClient {
         operationId?: string;
     }): Promise<EndpointOperation>;
     refresh(conversationId: string): Promise<MlsDevGroupView | undefined>;
+    /** Whether a room snapshot Canon just returned shows nothing this device lacks of the room's feed: no entry past its
+     * cursor, the membership it last fetched under, and no held removal. Then there is nothing to fetch, and this counts
+     * as catching up on the room. */
+    heldCurrent(conversationId: string, snapshot: {
+        mlsFeedOrdinal?: unknown;
+        membershipRevision?: unknown;
+        mlsRemoval?: unknown;
+    }): Promise<boolean>;
     read(conversationId: string): Promise<MlsDevGroupView | undefined>;
     readVerifiedMessageBinding(input: {
         conversationId: string;

package/dist/media.js

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

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

@@ -0,0 +1,25 @@
+import type { MlsEnvironmentId } from '../internal/backend-contracts/index.js';
+/**
+ * Each environment's Cloud KMS issuer and feed-receipt key versions (public keys, raw Ed25519 in base64url). During an
+ * issuer rotation `issuerKeys` holds both versions (docs/mls-dev-activation.md, "Planned issuer rotation"), and an SDK
+ * release carrying the new one ships before issuance switches.
+ */
+export declare const MLS_ENVIRONMENT_PINS: Readonly<Record<MlsEnvironmentId, {
+    issuerKeys: ReadonlyArray<{
+        keyVersion: string;
+        signaturePublicKey: string;
+    }>;
+    receiptKeys: ReadonlyArray<{
+        keyVersion: string;
+        signaturePublicKey: string;
+    }>;
+}>>;
+/**
+ * The custody helper this package ships for this host (`dist/mls/<platform>/canon-mls-custody`), checked against its
+ * pin, or undefined where it ships none: an Intel Mac, musl, Windows, or a build of this package without helpers. A
+ * file that is there but differs from its pin is refused.
+ */
+export declare function bundledMlsCustodyHelper(): {
+    path: string;
+    sha256: string;
+} | undefined;

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

@@ -0,0 +1,31 @@
+import type { MlsDevDeviceContext, MlsEnvironmentId } from '../internal/backend-contracts/index.js';
+import type { RunnerMlsOptions } from './mls.js';
+export interface ManagedMlsDeviceOptions {
+    /** The runner's home (CANON_HOME, or a relay installation's home). */
+    home: string;
+    environmentId: MlsEnvironmentId;
+    /** Another helper than this package's for the host, such as one built from mls/native. */
+    helper?: {
+        path: string;
+        sha256: string;
+    };
+    /** Other public pins than this package's for the environment. */
+    pins?: {
+        issuerKeys: ReadonlyArray<{
+            keyVersion: string;
+            signaturePublicKey: string;
+        }>;
+        receiptKeys: ReadonlyArray<{
+            keyVersion: string;
+            signaturePublicKey: string;
+        }>;
+    };
+    timeoutMs?: number;
+}
+export type ManagedMlsDevice = RunnerMlsOptions & {
+    provision(context: MlsDevDeviceContext): Promise<void>;
+    /** Whether this context's vault exists: its device was provisioned here. */
+    provisioned(context: MlsDevDeviceContext): boolean;
+    close(): Promise<void>;
+};
+export declare function managedMlsDevice(options: ManagedMlsDeviceOptions): ManagedMlsDevice;

package/dist/runner/mls.d.ts

@@ -1,9 +1,14 @@
 import { type CanonEndpoint, type CanonMlsDevOptions, type MlsDevCurrentAudience } from '../internal/core/index.js';
 import { type MlsDevDeviceContext } from '../internal/backend-contracts/index.js';
 import type { ToolDefinition } from './types.js';
-/** What `createRunner({ mls })` takes: issuer pins and custody, plus the custody's own shutdown. */
+/**
+ * What `createRunner({ mls })` takes: issuer pins and custody, plus the custody's own shutdown. With `provisioned`
+ * (managed custody, `managedMlsDevice`) the runner sets the device up itself at start.
+ */
 export type RunnerMlsOptions = CanonMlsDevOptions & {
     close?(): Promise<void>;
+    provision?(context: MlsDevDeviceContext): Promise<void>;
+    provisioned?(context: MlsDevDeviceContext): boolean;
 };
 /** A closed copy of the public audience (no provider input or key material), in a fixed field order. */
 export declare function snapshotMlsAudience(value: unknown): MlsDevCurrentAudience;
@@ -70,7 +75,7 @@ export declare function loadMlsDevConfiguration(filePath: string, input: {
     provision?: (context: MlsDevDeviceContext) => Promise<void>;
     close(): Promise<void>;
 }>;
-export declare const MLS_SETUP_ACTIONS: readonly ["status", "provision", "enroll", "renew", "publish", "refresh"];
+export declare const MLS_SETUP_ACTIONS: readonly ["status", "setup", "provision", "enroll", "renew", "publish", "refresh"];
 export type MlsSetupAction = typeof MLS_SETUP_ACTIONS[number];
 /** The KeyPackage an agent publishes for one room: stable for its installation, so a repeated publish is the same intent. */
 export declare function mlsDevRoomPackageId(identity: {
@@ -81,13 +86,15 @@ export declare function mlsDevRoomPackageId(identity: {
 }, room: string): string;
 /**
  * One operator step for the agent's device (`canon-agent mls`), on the same engine store the runner uses. It never
- * starts a model, and prints only public device state: no credentials, proofs, envelopes or history.
+ * starts a model, and prints only public device state: no credentials, proofs, envelopes or history. `setup` does what
+ * is left of provision then enroll, so it also finishes a setup that stopped part way; it never replaces a vault, and
+ * with `provisioned` (managed custody) it provisions only where this installation has none.
  */
-export declare function runMlsDevSetup(endpoint: CanonEndpoint, action: MlsSetupAction, room?: string, provision?: (context: MlsDevDeviceContext) => Promise<void>): Promise<{
+export declare function runMlsDevSetup(endpoint: CanonEndpoint, action: MlsSetupAction, room?: string, provision?: (context: MlsDevDeviceContext) => Promise<void>, provisioned?: (context: MlsDevDeviceContext) => boolean): Promise<{
     conversationId?: string | undefined;
     version: number;
-    action: "status" | "publish" | "enroll" | "renew" | "provision" | "refresh";
-    environmentId: "canon-dev-v1" | "canon-prod-v1";
+    action: "status" | "publish" | "enroll" | "renew" | "provision" | "setup" | "refresh";
+    environmentId: string;
     principalId: string;
     installationId: string;
     ownershipVersion: number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "12.3.1",
+  "version": "12.4.1",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
   "scripts": {
     "build": "node ../../scripts/build-agent-sdk.mjs",
     "dev": "tsc --watch --noEmit",
-    "prepack": "npm run build"
+    "prepack": "node ../../scripts/build-agent-sdk.mjs --pack"
   },
   "engines": {
     "node": ">=22.23.4 <23 || >=24.22.1 <25 || >=26.12.1 <27"