@canonmsg/agent-sdk 12.0.0 → 12.2.0

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

@@ -0,0 +1,99 @@
+import type { MlsDevGroupHead, MlsDevInteractionAnswer, MlsDevInteractionKind, MlsDevInteractionRequestBody, MlsDevInteractionWithdrawReason } from '../backend-contracts/index.js';
+import type { MlsDevLocalTextMessage } from './mls-dev-text.js';
+/**
+ * The local reduction of encrypted approvals and questions in a v2 room (docs/design/encrypted-interactions.md §2.3,
+ * §5): one record per (agent, request), built only from MLS-verified feed entries in feed order. Responses and
+ * withdrawals update it; only the request is a history bubble. Never include these records in an HTTP request.
+ */
+export interface MlsDevLocalInteraction {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly agentId: string;
+    readonly requestId: string;
+    readonly requesterDeviceId: string;
+    /** Includes a secret request's one-time public key; never an answer's plaintext. */
+    readonly request: MlsDevInteractionRequestBody;
+    readonly requestMessageId: string;
+    readonly requestOrdinal: number;
+    /** The audience the request was sent to: the group head and membership revision it was encrypted under. */
+    readonly head: MlsDevGroupHead;
+    readonly membershipRevision: number;
+    readonly acceptedAtMs: number;
+    readonly status: 'pending' | 'answered' | 'withdrawn';
+    readonly response?: {
+        readonly responderId: string;
+        readonly responderDeviceId: string;
+        readonly messageId: string;
+        readonly ordinal: number;
+        /** A secret answer stays sealed here; only `openSecretAnswer` opens it, once, in memory. */
+        readonly answer: MlsDevInteractionAnswer;
+        /** This device's clock when the verified answer was applied: the local deadline is authoritative (§6). */
+        readonly appliedAtMs: number;
+    };
+    readonly withdrawal?: {
+        readonly reason: MlsDevInteractionWithdrawReason;
+        readonly messageId: string;
+        readonly ordinal: number;
+    };
+    /** Set when the requester opened a sealed answer; its key is gone. */
+    readonly opened?: true;
+}
+/** `voided`: the room's audience changed after the request (§4); `expired`: the local deadline passed first. */
+export type MlsDevInteractionState = 'pending' | 'answered' | 'withdrawn' | 'expired' | 'voided';
+export interface MlsDevInteractionView {
+    readonly conversationId: string;
+    readonly agentId: string;
+    readonly requestId: string;
+    readonly kind: MlsDevInteractionKind;
+    readonly state: MlsDevInteractionState;
+    readonly requestMessageId: string;
+    readonly responderIds: readonly [string];
+    readonly expiresAtMs: number;
+    readonly answer?: MlsDevInteractionAnswer;
+    readonly respondedBy?: string;
+    readonly withdrawReason?: MlsDevInteractionWithdrawReason;
+    readonly opened?: true;
+    /** Still pending, with this device's own answer committed and on its way (never set by `viewMlsDevInteraction`). */
+    readonly sending?: true;
+}
+export declare const mlsDevInteractionKey: (conversationId: string, agentId: string, requestId: string) => string;
+export declare const mlsDevInteractionIntegrityKey: (conversationId: string, ordinal: number) => string;
+export declare function viewMlsDevInteraction(value: MlsDevLocalInteraction, now: number, audience: {
+    readonly head: MlsDevGroupHead | null;
+    readonly membershipRevision: number;
+} | undefined): MlsDevInteractionView;
+/** A view for an account-facing caller: its agent, responders and answerer as accounts (mls-dev-groups.md, erasure privacy). */
+export declare function accountMlsDevInteractionView(view: MlsDevInteractionView, account: (principal: {
+    type: string;
+    id: string;
+}) => string): MlsDevInteractionView;
+/**
+ * The card's outcome as clients render it (§5), shared by the history projection and `get_runtime_card_state`: an
+ * approval's decision, a question's or secret's answer (`submitted`; never its content) or the responder's Cancel/Skip,
+ * the local deadline, and `withdrawn` for a withdrawal or a card voided by an audience change (§4); `sending` while this
+ * device's own answer is committed and on its way (only its responder's device sees it).
+ */
+export type MlsDevInteractionCardStatus = 'pending' | 'sending' | 'allow' | 'deny' | 'submitted' | 'cancelled' | 'expired' | 'withdrawn';
+export declare function mlsDevInteractionCardStatus(view: Pick<MlsDevInteractionView, 'state' | 'answer' | 'sending'>): MlsDevInteractionCardStatus;
+/**
+ * Maps the answer a card sends as `respond_interaction` (the shapes `ApprovalCard` and `RuntimeInputCard` already send)
+ * onto this request's encrypted answer (§5): an approval's Allow once, Allow for this session (only when the request
+ * offered it) or Deny; a question's option ids, several only when it allows several, or its free text; a secret's
+ * plaintext, which only native custody seals; and Cancel/Skip as `{ cancelled: true }`. Anything else (a plaintext
+ * session rule, a plan or rich-card answer, a kind that does not match the request) is refused before encryption.
+ */
+export declare function mlsDevInteractionResponse(request: MlsDevInteractionRequestBody, body: Readonly<Record<string, unknown>>): {
+    readonly answer: MlsDevInteractionAnswer;
+} | {
+    readonly secret: string;
+};
+/**
+ * Projects a decrypted request into the plaintext interaction shape (`contentType: 'interaction'`, the `interaction`
+ * envelope and `metadata.type`), so `classifyChatMessage`, `buildBubbleModel`, `ApprovalCard` and `RuntimeInputCard`
+ * render it unchanged; `mlsInteraction` carries the local reduction (state, the card status, a non-secret answer, who
+ * answered).
+ */
+export declare function projectMlsDevInteractionMessage(local: MlsDevLocalTextMessage, view: MlsDevInteractionView | undefined, account: (principal: {
+    type: string;
+    id: string;
+}) => string): Record<string, unknown>;

package/dist/internal/endpoint/mls-dev-key-package-service.d.ts

@@ -16,6 +16,13 @@ export interface MlsDevKeyPackageClaimInput {
     readonly recipientDeviceId: string;
     readonly preconditions: MlsDevKeyPackageClaimPreconditions;
 }
+/** A claim in this device's journal; `claimedAtMs` is null while Canon's answer is not known. */
+export interface MlsDevKeyPackageRoomClaim {
+    readonly requestId: string;
+    readonly recipientDeviceId: string;
+    readonly preconditions: MlsDevKeyPackageClaimPreconditions;
+    readonly claimedAtMs: number | null;
+}
 export interface MlsDevKeyPackageServiceClient {
     /** Revalidates online, including when a historical receipt exists. */
     publish(input: {
@@ -24,6 +31,12 @@ export interface MlsDevKeyPackageServiceClient {
     claim(input: MlsDevKeyPackageClaimInput): Promise<MlsDevKeyPackageClaimView>;
     readPublication(keyPackageId: string): Promise<MlsDevKeyPackagePublicationView | undefined>;
     readClaim(requestId: string): Promise<MlsDevKeyPackageClaimView | undefined>;
+    /** This device's journaled claims in the conversation. Through a claim's lease Canon holds its recipient's slot for it
+     * and lists the device to no one, so a claim whose Add did not go is resumed from here, not claimed afresh. */
+    readRoomClaims(conversationId: string): Promise<readonly MlsDevKeyPackageRoomClaim[]>;
+    /** Forgets answered claims made before `beforeMs`. A claim matters only until its Add is accepted or its slot's lease
+     * ends, so the journal's 32 rows hold only recent claims. Returns how many it removed. */
+    pruneClaims(beforeMs: number): Promise<number>;
 }
 /** Uses the same device lifetime/store. Explicit calls only; no second drain loop.
  * Publication reads public committed TLS; no provider ciphertext enters a request. */

package/dist/internal/endpoint/mls-dev-key-packages.d.ts

@@ -1,6 +1,6 @@
 import { type MlsDevDeviceBinding, type MlsDevDeviceContext, type MlsDevKeyPackageCommand, type MlsDevKeyPackagePayload, type MlsDevKeyPackagePreparation } from '../backend-contracts/index.js';
 import { type MlsDevKeyPackagePrerequisite } from './mls-dev-device.js';
-import type { MlsDevDeviceClientContext, MlsDevDeviceClientOptions } from './mls-dev-client.js';
+import { type MlsDevDeviceClientContext, type MlsDevDeviceClientOptions } from './mls-dev-client.js';
 import { type MlsDevKeyPackageServiceClient } from './mls-dev-key-package-service.js';
 export type { MlsDevKeyPackagePublicationView, MlsDevKeyPackageClaimView, MlsDevKeyPackageClaimInput } from './mls-dev-key-package-service.js';
 import { type EndpointStoreTransaction } from './store.js';
@@ -10,6 +10,14 @@ export interface MlsDevKeyPackageView {
     readonly status: 'prepared';
     readonly payload: MlsDevKeyPackagePayload;
 }
+export interface MlsDevKeyPackagePoolView {
+    /** Published, unconsumed packages in the first half of their lifetime. */
+    readonly fresh: number;
+    /** Published by this call. */
+    readonly published: number;
+    /** Consumed or expired packages whose local records this call removed. */
+    readonly retired: number;
+}
 export interface MlsDevKeyPackageClient extends MlsDevKeyPackageServiceClient {
     prepare(input: {
         keyPackageId: string;
@@ -17,7 +25,19 @@ export interface MlsDevKeyPackageClient extends MlsDevKeyPackageServiceClient {
     /** Returns exact committed bytes, including after credential expiry/renewal.
      * Requires a committed registration/credential and no local revocation. */
     read(keyPackageId: string): Promise<MlsDevKeyPackageView | undefined>;
+    /**
+     * Keeps this device admissible without anyone typing its ID: at least `MLS_DEV_KEY_PACKAGE_POOL_SIZE` published,
+     * room-independent packages in the first half of their lifetime, so any room can claim one (the server picks the
+     * oldest available). It retires the pool's consumed packages and, a lifetime after expiry, its expired ones with
+     * their private state, so the local caps of 32 never fill. Needs a ready device (`mlsDevDevice.ensureReady()`).
+     * Calls share one run. Packages prepared by `prepare` outside the pool are left alone.
+     */
+    maintainPool(): Promise<MlsDevKeyPackagePoolView>;
 }
+export declare const MLS_DEV_KEY_PACKAGE_POOL_SIZE = 4;
+export declare const MLS_DEV_KEY_PACKAGE_RETENTION_MS: number;
+/** Every private package this device may hold: the live inventory and the retained ones. */
+export declare const MLS_DEV_KEY_PACKAGE_STORE_MAX: number;
 /** Consumed identities survive active-inventory removal until logout resets the
  * installation. A regenerated RefHash must never resurrect a used private key. */
 export declare function assertMlsDevKeyPackageUnconsumed(tx: EndpointStoreTransaction, id: string, ref?: string): Promise<void>;
@@ -37,6 +57,6 @@ export declare function consumeMlsDevPreparedKeyPackage(tx: EndpointStoreTransac
     groupId: string;
     controlSequence: number;
 }): Promise<void>;
-/** Internal endpoint attachment. Uses the device's existing store/lifetime and
- * has no timer, signer generation or automatic inventory replenishment. */
+/** Internal endpoint attachment. Uses the device's existing store/lifetime and has
+ * no timer or signer generation; only `maintainPool` replenishes, when called. */
 export declare function createMlsDevKeyPackageClient(options: MlsDevDeviceClientOptions, context: MlsDevDeviceClientContext): MlsDevKeyPackageClient;

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

@@ -0,0 +1,67 @@
+import { MLS_DEV_TEXT_PROTOCOL, type MlsDevApplicationPayload } from '../backend-contracts/index.js';
+import type { EndpointOperation } from './engine.js';
+import type { EndpointStoreTransaction } from './store.js';
+/** Local authorized plaintext cache, independent of MLS epoch keys and the
+ * business-inbox lifetime. Never include these records in an HTTP request. */
+export interface MlsDevLocalTextMessage {
+    version: 1;
+    /** Text, or in a v2 room an encrypted card payload (a secret answer only in its sealed form). */
+    message: MlsDevApplicationPayload;
+    senderId: string;
+    senderType: 'human' | 'ai_agent';
+    status: 'queued' | 'sent' | 'rejected' | 'uncertain';
+    createdAtMs: number;
+    feedOrdinal: number | null;
+    /** Its sender deleted it for everyone: the decrypted text is erased, and the row stays only to keep feed order. */
+    deleted?: true;
+}
+export declare const mlsDevTextProtocolKey: (conversationId: string) => string;
+export { MLS_DEV_TEXT_PROTOCOL };
+export declare const mlsDevTextMessageKey: (conversationId: string, messageId: string) => string;
+/** This device's own latest answer to a card: a pointer to its authored (never secret) copy. */
+export declare const mlsDevOwnAnswerKey: (conversationId: string, agentId: string, requestId: string) => string;
+/** Whether this device's answer to a card is committed and still on its way: queued, or its outcome uncertain, and not
+ * yet applied from the feed (where the reduction takes over) nor refused. The card waits for it rather than answer twice. */
+export declare function isMlsDevOwnAnswerSending(tx: EndpointStoreTransaction, conversationId: string, agentId: string, requestId: string): Promise<boolean>;
+/** A deletion for everyone that reached this device, before or after the message itself (mls-payload-v3.md §4). */
+export declare const mlsDevTextDeletedKey: (conversationId: string, messageId: string) => string;
+/** The reactions Canon holds for a message's public stub, which the history shows beside its decrypted text. */
+export declare const mlsDevTextReactionsKey: (conversationId: string, messageId: string) => string;
+/**
+ * Its sender deleted a message for everyone. The decrypted text is erased now, and the tombstone keeps it erased if the
+ * feed brings the message again, on catch-up or replay. An own send whose echo is not applied yet keeps its text until
+ * the echo applies (the echo is checked against it); the history already shows it deleted. Cards are not deleted this
+ * way: Canon refuses to delete an encrypted card, which is withdrawn instead. Returns whether anything changed.
+ */
+export declare function deleteMlsDevTextMessage(tx: EndpointStoreTransaction, conversationId: string, messageId: string): Promise<boolean>;
+/** The stub's reactions, as Canon reports them; an empty set clears them. Returns whether they changed. */
+export declare function setMlsDevTextReactions(tx: EndpointStoreTransaction, conversationId: string, messageId: string, reactions: Readonly<Record<string, readonly string[]>> | undefined): Promise<boolean>;
+export declare function putMlsDevTextMessage(tx: EndpointStoreTransaction, value: MlsDevLocalTextMessage): Promise<void>;
+/** What a v3 reply quotes from this device's copy of the message it answers, trimmed to the payload's bound: a text, or
+ * an item's caption or else what it is. Nothing for a card, a message deleted for everyone, or one not held here. */
+export declare function mlsDevReplyQuote(value: MlsDevLocalTextMessage | undefined, maximum: number): string | undefined;
+/** `account` opens the stored sender alias to its account (mls-dev-groups.md, erasure privacy). */
+export declare function projectMlsDevTextMessage(value: MlsDevLocalTextMessage, account: MlsDevAccountResolver): Record<string, unknown>;
+/** Opens a stored principal (an alias, with the type its credential gave) to its account. */
+export type MlsDevAccountResolver = (principal: {
+    type: string;
+    id: string;
+}) => string;
+export interface MlsDevHistoryAudience {
+    readonly now: number;
+    /** Opens a stored alias to its account, or to the erased sender (mls-dev-groups.md, erasure privacy). */
+    readonly account: MlsDevAccountResolver;
+    readonly current: {
+        readonly head: import('../backend-contracts/index.js').MlsDevGroupHead | null;
+        readonly membershipRevision: number;
+    } | undefined;
+}
+/** Existing UI history queries read only this endpoint's accepted plaintext
+ * reduction. Feed recovery, authorization and lifecycle fencing are caller-owned. */
+export declare function queryMlsDevTextHistory(tx: EndpointStoreTransaction, conversationId: string, name: string, parameters: Record<string, unknown>, audience?: MlsDevHistoryAudience): Promise<{
+    messages: Record<string, unknown>[];
+    nextBefore?: string | null;
+    missingMessageIds?: string[];
+}>;
+/** Rendering-only transition; an unsuccessful send never rewinds MLS state. */
+export declare function settleMlsDevTextOperation(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<void>;

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

@@ -27,7 +27,8 @@ export interface MlsDevDeviceHttpOptions {
     allowSyntheticLoopbackHttp?: boolean;
 }
 /** Internal constructor. The ordinary endpoint and Dev capability share credentials,
- * fetch and ownership settings; the Dev deadline also covers auth and body reads. */
+ * fetch and ownership settings; the Dev deadline also covers auth and body reads.
+ * Only a declared MLS environment, and only responses that name that environment. */
 export declare function createMlsDevDeviceHttpTransport(config: MlsDevDeviceHttpOptions, dependencies: {
     environmentId: string;
     credentials: EndpointCredentials;

package/dist/internal/endpoint/node-mls-custody-protocol.d.ts

@@ -14,6 +14,11 @@ export declare class NodeMlsDevCustodyError extends Error {
 }
 export declare const MAX_INPUT: number, MAX_OUTPUT: number;
 export declare function rejected(): never;
+/** A helper's result value. Its one non-result the endpoint sees is native's fixed clock pause (mls-signed-acceptance.md
+ * §2.9), which only a group operation (4) can return: a retryable error, never a custody failure. */
+export declare function custodyValue(output: Buffer, operation: number): unknown;
+/** A job's failure: the clock pause passes through, everything else is the fixed custody rejection. */
+export declare function custodyFailure(error: unknown): never;
 export declare function requireValue(value: unknown): asserts value;
 export declare function record(value: unknown, fields: string[]): Record<string, unknown>;
 export declare function sealed(value: unknown, maximum: number, nullable?: boolean): string | null;

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

@@ -1,4 +1,4 @@
-import { type EndpointContentLane, type EndpointOperationRequest, type EndpointOperationReceipt, type EndpointCapabilities } from '../backend-contracts/index.js';
+import { type CanonClientIdentity, type EndpointContentLane, type EndpointOperationRequest, type EndpointOperationReceipt, type EndpointCapabilities } from '../backend-contracts/index.js';
 import { type EndpointTransportEvent, type EndpointEventFamily } from './events.js';
 import { type MlsDevDeviceHttpOptions, type MlsDevDeviceTransport } from './mls-dev-transport.js';
 export declare class EndpointError extends Error {
@@ -55,4 +55,9 @@ export declare function createHttpEndpointTransport(options: {
     streamId?: string | (() => string | Promise<string>);
     ownershipVersion?: number | (() => number | undefined);
     mlsDevDevice?: MlsDevDeviceHttpOptions;
+    /** Names this client on every request and stream (`X-Canon-Client`), so Canon can apply its client floor. */
+    client?: CanonClientIdentity;
+    /** Canon refused this client as below its floor (`426 CLIENT_UPDATE_REQUIRED`), on any request or stream. Called
+     * before the error is thrown, so a host can stop wherever the refusal surfaces. */
+    onClientUpdateRequired?(error: EndpointError): void;
 }): EndpointTransport;

package/dist/media.js

@@ -18,8 +18,8 @@ import {
   toAnthropicImageBlock,
   toAnthropicImageBlocksWithinBudget,
   uploadMediaFile
-} from "./chunks/chunk-OLJ7H4E2.js";
-import "./chunks/chunk-FPQFTTND.js";
+} from "./chunks/chunk-O5C3ZGI4.js";
+import "./chunks/chunk-J63YVAKA.js";
 export {
   DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
   DEFAULT_MEDIA_CACHE_DIR,

package/dist/runner/errands.d.ts

@@ -0,0 +1,118 @@
+/** `tell` and `post` (§12.3, §12.4), `errand` (§12.6) and `cancel`, which ends an errand. */
+export declare const ERRAND_KINDS: readonly ["tell", "post", "errand", "cancel"];
+export type ErrandKind = (typeof ERRAND_KINDS)[number];
+/** At most what one encrypted message holds (§6), so a post is never cut. */
+export declare const ERRAND_TEXT_MAX_BYTES: number;
+/** An errand's why, at most. */
+export declare const ERRAND_WHY_MAX_BYTES: number;
+/** A command not taken within a day is refused, and a note no turn used within a day expires. */
+export declare const ERRAND_TTL_MS: number;
+/** An errand stays open for replies this long after the agent reached its recipient, or after the last reply. */
+export declare const ERRAND_OPEN_MS: number;
+/** What the operator asks for: a note or a post for a room, an errand, or the end of an errand. */
+export type ErrandInput = {
+    kind: 'tell' | 'post';
+    conversationId: string;
+    text: string;
+}
+/** `to`: a room the agent is in, or a person or agent to start a new conversation with; `text`: the instruction. */
+ | {
+    kind: 'errand';
+    to: string;
+    why: string;
+    text: string;
+    origin?: string;
+} | {
+    kind: 'cancel';
+    errand: string;
+};
+/** One command, as the CLI writes it into the inbox. */
+export type ErrandCommand = ErrandInput & {
+    version: 1;
+    id: string;
+    createdAt: string;
+};
+/**
+ * What the runner did with a command. A note: `pending` until its room's next turn marks it `used`. A post: `sending`,
+ * then `sent`. An errand: `pending`, `running` (its turn), then `waiting` once the agent reached the recipient, `replied`
+ * when a turn ran there on a reply, `done` when its turn ended without reaching them, `failed`, `cancelled` (Stop in the
+ * origin, or `cancel`), `interrupted` (the runner stopped during its turn, which never runs again) or `expired`. A cancel
+ * is `applied`. Any command: `refused` (valid, but the runner could not apply it), `rejected` (not a valid command file),
+ * `expired` (too old).
+ */
+export type ErrandStatus = 'pending' | 'used' | 'sending' | 'sent' | 'running' | 'waiting' | 'replied' | 'done' | 'failed' | 'cancelled' | 'interrupted' | 'applied' | 'refused' | 'rejected' | 'expired';
+export interface ErrandRecord {
+    version: 1;
+    id: string;
+    status: ErrandStatus;
+    updatedAt: string;
+    kind?: ErrandKind;
+    createdAt?: string;
+    reason?: string;
+    /** A note's or a post's room; an errand's once the agent reached its recipient there. */
+    conversationId?: string;
+    /** The installation scope it was taken under (§5): a note or an errand is acted on only under the same one. */
+    scope?: string;
+    /** A pending note's text, dropped once the note leaves `pending`; an errand's instruction. */
+    text?: string;
+    /** The turn that used a note; an errand's turn. */
+    turnId?: string;
+    /** An errand: its recipient (a room, or a person or agent to start a conversation with), why, and origin room. */
+    to?: string;
+    target?: 'room' | 'contact';
+    why?: string;
+    origin?: string;
+    /** An errand: when its turn reached the recipient, and the last reply there. */
+    reachedAt?: string;
+    repliedAt?: string;
+    /** An errand: its report kept here, when it may not go to the origin (§12.7), and how the one sent there went. */
+    report?: string;
+    reported?: 'sending' | 'sent' | 'refused';
+    /** A cancel: the errand it ends. */
+    errand?: string;
+}
+/** An agent's errands in the home: `runner/<env>/<agentId>/errands/` (spec §5). */
+export declare function errandsDirectory(home: string, environmentId: string, agentId: string): string;
+/** The inbox directory, created private if missing; one that is not this uid's private directory is refused. */
+export declare function errandInbox(directory: string): string;
+/** The operator's side (the CLI, or a library caller): one durable command file in the inbox. Throws on an invalid command. */
+export declare function queueErrand(directory: string, input: ErrandInput): ErrandCommand;
+/** The runner's records, one file per command taken (§12.2). */
+export declare function errandJournal(directory: string): {
+    has: (id: string) => boolean;
+    get: (id: string) => ErrandRecord | undefined;
+    put: (record: ErrandRecord) => void;
+    list(): ErrandRecord[];
+};
+export type ErrandJournal = ReturnType<typeof errandJournal>;
+/**
+ * `--wait` (§12.1): the command's record once the runner has answered it, or as it stands after `ms`, and whether it was
+ * accepted. A post (or an errand's report) Canon has not answered stays `sending` and is not accepted, though the runner
+ * keeps it and goes on delivering it: it may yet be refused.
+ */
+export declare function awaitErrand(directory: string, command: Pick<ErrandCommand, 'id' | 'kind'>, ms: number): Promise<{
+    record: ErrandRecord | undefined;
+    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, 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.
+     */
+    take(id: string, command: ErrandCommand | {
+        problem: string;
+    }): Promise<boolean>;
+}
+/**
+ * §12.1: watches the inbox and scans it every `intervalMs` as a backstop (and at once), one scan at a time, files in
+ * name order. A file is removed only after the handler has journaled what it did with it.
+ */
+export declare function watchErrandInbox(directory: string, handler: ErrandHandler, options: {
+    log: (line: string) => void;
+    intervalMs?: number;
+}): {
+    close(): Promise<void>;
+};
+export type ErrandInbox = ReturnType<typeof watchErrandInbox>;

package/dist/runner/mls.d.ts

@@ -0,0 +1,97 @@
+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. */
+export type RunnerMlsOptions = CanonMlsDevOptions & {
+    close?(): Promise<void>;
+};
+/** 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;
+/**
+ * The principals who can read the room, each with its admission (an agent also with its ownership version), sorted: the
+ * set the server's device-only re-ask rule compares (encrypted-interactions.md §4), never the devices themselves. A
+ * principal reading through a device Canon operates (a class-C relay, §11) counts apart, so a relay device joining or
+ * leaving is never a device-only change.
+ */
+export declare function mlsAudiencePrincipals(value: MlsDevCurrentAudience): string[];
+/**
+ * The audience's epoch: who can read the room, which is its principals with their admissions, the membership revision
+ * and this device's own place in the group. A device-only change (a member adds or removes a device and keeps one) is a
+ * re-key, not an audience change (§4), so the group head and the device set are left out, as is the feed cursor, which
+ * ordinary text moves.
+ */
+export declare function mlsAudienceEpoch(value: MlsDevCurrentAudience): string;
+/** What an encrypted room's text message is to the runner; Canon never learns it (`MlsIds.text`). */
+export type MlsTextKind = 'final' | 'failed' | 'restart' | 'said' | 'item';
+/**
+ * §6 ids. Canon sees the message id of everything the runner sends to an encrypted room, and a card's request id (its
+ * public binding), so these are keyed with a secret only this installation holds (`privateKey`): HMAC-SHA256 over
+ * domain-separated inputs, cut to 128 bits. Canon can test no guess of the text, question or turn an id names, and every
+ * text message (a final, a failure or restart notice, a `communicate` send, an item) has the same shape, `msg-<32 hex>`, so none
+ * says what kind it is. The same inputs give the same id after a restart, so journal replay, a repeated `communicate`,
+ * a re-asked card and a restart notice keep theirs.
+ */
+export interface MlsIds {
+    /** A text message's id: `parts` name it (the turn, or the turn and a `communicate` send's text). */
+    text(kind: MlsTextKind, conversationId: string, ...parts: string[]): string;
+    /** A card's request id, `ask-<32 hex>` (`MLS_DEV_INTERACTION_ID_PATTERN`), for the runtime's ask `askId` in turn `turnId`. */
+    request(conversationId: string, turnId: string, askId: string): string;
+}
+/** The installation's id key: random bytes, created once under CANON_HOME. */
+export declare const MLS_ID_KEY_BYTES = 32;
+export declare function createMlsIds(key: Uint8Array): MlsIds;
+/**
+ * Encrypted rooms are for agents whose outbound communication is not closed, in an environment with an MLS profile. Canon
+ * decides who joins a room under the invitation policies, as for plaintext rooms, and whether that environment runs MLS.
+ */
+export declare function requireMlsSupport(input: {
+    environmentId: string;
+    agent: {
+        outboundPolicy: string;
+    };
+}): void;
+/**
+ * Whether `text` @mentions any of `names` (an agent's display name, id or aliases). Encrypted text carries no `mentions[]`,
+ * so this is how one agent addresses another there: `@`, not preceded by a letter, digit, `_` or `@` (so no address
+ * like `ops@example.com`), then the name in any case, with any run of whitespace for a space, not followed by a letter,
+ * digit, mark or `_` (`@Cipher A` does not mention `Cipher AB`).
+ */
+export declare function mentionsAgent(text: string, names: ReadonlyArray<string | undefined>): boolean;
+/** An encrypted turn's `communicate`: listing, and text to its own room, which the runner encrypts. */
+export declare const ENCRYPTED_COMMUNICATE: ToolDefinition;
+/**
+ * The operator's MLS configuration file: public issuer pins and the custody helper's identity, never credentials or
+ * private keys. A canonical, current-user-owned regular file, not group- or other-writable, at most 64 KiB, read once.
+ * Its configuration must be for the environment the runner runs in.
+ */
+export declare function loadMlsDevConfiguration(filePath: string, input: {
+    environmentId: string;
+}): Promise<RunnerMlsOptions & {
+    provision?: (context: MlsDevDeviceContext) => Promise<void>;
+    close(): Promise<void>;
+}>;
+export declare const MLS_SETUP_ACTIONS: readonly ["status", "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: {
+    environmentId: string;
+    principalId: string;
+    installationId: string;
+    ownershipVersion?: number;
+}, 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.
+ */
+export declare function runMlsDevSetup(endpoint: CanonEndpoint, action: MlsSetupAction, room?: string, provision?: (context: MlsDevDeviceContext) => Promise<void>): Promise<{
+    conversationId?: string | undefined;
+    version: number;
+    action: "status" | "publish" | "enroll" | "renew" | "provision" | "refresh";
+    environmentId: "canon-dev-v1" | "canon-prod-v1";
+    principalId: string;
+    installationId: string;
+    ownershipVersion: number | undefined;
+    status: "absent" | "identity_committed" | "registered" | "credential_committed" | "revoked";
+    deviceId: string | null;
+    credentialGeneration: number;
+}>;

package/dist/runner/relay.d.ts

@@ -0,0 +1,87 @@
+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). */
+export interface RelayTarget {
+    runner: Pick<Runner, 'relayRead' | 'relaySend'>;
+    inbox: ConnectorInbox;
+}
+/** Canon's credential for this relay, as delivered: the connection it serves is the delivering request's. */
+export type RelayCredentialDelivery = ConnectorRelayCredentialDelivery & {
+    grantId: string;
+};
+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'>;
+    inbox?: ConnectorInbox;
+    /** The relayed agent: requests naming another agent are refused. */
+    agentId: string;
+    /**
+     * The connector connection served: requests naming another are refused. A credential delivery (the owner's approval)
+     * names its own connection and moves the relay to it.
+     */
+    grantId?: string;
+    /** The Standard Webhooks secret (`whsec_…`) Functions signs with: this agent's alone. */
+    secret: string;
+    /**
+     * Canon delivers the relay's credential here when the owner approves, or re-approves, the relay; the channel confirms
+     * the delivery once this resolves, so it should keep the credential durably first. Without it, deliveries are refused.
+     */
+    onCredential?: (delivery: RelayCredentialDelivery) => void | Promise<void>;
+    /** Default 127.0.0.1 and a random port. */
+    host?: string;
+    port?: number;
+    /** Never receives message text. */
+    log?: (line: string) => void;
+    /** Test seam: the clock signatures are checked against. */
+    now?: () => number;
+    /** Test seam: how long an exchange may take before it is answered (default `CONNECTOR_RELAY_ANSWER_WITHIN_MS`). */
+    answerWithinMs?: number;
+}
+export interface RelayChannel {
+    readonly url: string;
+    /** Serves this runner and inbox for `grantId` (default: the connection already served), or nothing (`undefined`). */
+    serve(target: RelayTarget | undefined, grantId?: string): void;
+    close(): Promise<void>;
+}
+export declare function relaySecretKey(secret: string): Buffer;
+/** The headers Functions sends (as the `standardwebhooks` library signs them); the tests' stand-in for Functions uses it. */
+export declare function signRelayRequest(secret: string, id: string, body: string, nowMs?: number): Record<string, string>;
+/** Starts the channel. Every request is authenticated before its body is parsed; refusals carry no detail. */
+export declare function startRelayChannel(options: RelayChannelOptions): Promise<RelayChannel>;
+export interface RelayConfiguration {
+    environmentId: string;
+    agentId: string;
+    listen: {
+        host: string;
+        port: number;
+    };
+    secret: string;
+}
+/**
+ * The operator's relay configuration (`--relay-config`): which agent this process relays, where the channel listens, and
+ * the path of the channel secret, itself a private file. The connection, installation and credential come from Canon,
+ * with the credential, when the owner approves the relay.
+ */
+export declare function loadRelayConfiguration(path: string, input: {
+    environmentId: string;
+}): Promise<RelayConfiguration>;
+/** The relay's credential as it keeps it: `<CANON_HOME>/relay/credential.json`, 0600, written whole or not at all. */
+export interface StoredRelayCredential {
+    version: 1;
+    environmentId: string;
+    agentId: string;
+    grantId: string;
+    installationId: string;
+    generation: number;
+    credential: string;
+}
+/** The credential Canon delivered to this relay, if any; one for another agent or environment is refused. */
+export declare function readRelayCredential(home: string, relay: Pick<RelayConfiguration, 'environmentId' | 'agentId'>): Promise<StoredRelayCredential | undefined>;
+/** Keeps a delivered credential durably (fsync, then rename), private to this user, before the delivery is confirmed. */
+export declare function writeRelayCredential(home: string, relay: Pick<RelayConfiguration, 'environmentId' | 'agentId'>, delivery: RelayCredentialDelivery): StoredRelayCredential;
+/**
+ * Where the runner for one relay installation keeps its state (engine store, journal, lock): a private directory per
+ * installation, so a new approval (a new installation and device) starts clean beside the old one.
+ */
+export declare function relayRunnerHome(home: string, installationId: string): string;