@canonmsg/agent-sdk 12.3.2 → 12.5.1

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

package/dist/runner/mls.d.ts

@@ -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: {
@@ -79,15 +84,23 @@ export declare function mlsDevRoomPackageId(identity: {
     installationId: string;
     ownershipVersion?: number;
 }, room: string): string;
+/**
+ * Managed custody opens only the vaults it made in its home. A device the engine store holds with no vault there (set up
+ * with an operator's configuration, or its vault lost) is refused once, here, rather than failing in every room.
+ */
+export declare function assertMlsVaultInHome(endpoint: CanonEndpoint, provisioned: (context: MlsDevDeviceContext) => boolean): Promise<void>;
 /**
  * One operator step for the agent's device (`canon-agent mls`), on the same engine store the runner uses. It never
- * starts a model, and prints only public device state: no credentials, proofs, envelopes or history.
+ * 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, and refuses a device whose
+ * vault is elsewhere.
  */
-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/dist/runner/relay.d.ts

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

package/dist/runner/runner.d.ts

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

package/dist/runner/types.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "12.3.2",
+  "version": "12.5.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"