@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,174 @@
+import { type MlsDevEnrollmentPrincipal, type MlsDevDeviceContext, type MlsDevGroupContext, type MlsDevGroupCommand, type MlsDevGroupPreparation, type MlsDevGroupHead, type MlsDevGroupRosterEntry, type MlsDevGroupQuery, type MlsDevGroupQueryResult, type MlsDevGroupFeedQuery, type MlsDevGroupFeedResult, type MlsDevTextProtocol, type MlsDevInteractionAnswer, type MlsDevInteractionRequestBody, type MlsDevInteractionWithdrawReason, type EndpointOperationReceipt } from '../backend-contracts/index.js';
+import type { EndpointOperation } from './engine.js';
+import type { MlsDevDeviceClientContext, MlsDevDeviceClientOptions } from './mls-dev-client.js';
+import { type MlsDevKeyPackageClient } from './mls-dev-key-packages.js';
+import { type EndpointStoreTransaction } from './store.js';
+import { EndpointError } from './transport.js';
+import { type MlsDevInteractionView } from './mls-dev-interactions.js';
+import type { EndpointSyncPage, EndpointSyncOptions } from './sync.js';
+export type MlsDevProtectedGroupPreparer = (identityContext: MlsDevDeviceContext, groupContext: MlsDevGroupContext, command: MlsDevGroupCommand, wrappedIdentity: string, wrappedGroup: string | null, wrappedKeyPackage: string | null) => Promise<MlsDevGroupPreparation>;
+export interface MlsDevGroupView {
+    readonly status: 'pending' | 'active' | 'removed';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly head: MlsDevGroupHead | null;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly pendingOperationId: string | null;
+}
+declare const roomRecoveryCodes: readonly ["MLS_DEV_GROUP_PREPARATION_FAILED", "MLS_DEV_GROUP_CREDENTIAL_EXPIRED", "MLS_DEV_CREDENTIAL_EXPIRED"];
+export interface MlsDevGroupRecoveryFailure {
+    readonly version: 1;
+    readonly conversationId: string;
+    readonly code: typeof roomRecoveryCodes[number];
+    readonly lastAppliedSequence: number;
+    readonly observedAtMs: number;
+}
+/** Only these fixed room-local failures may let the shared stream continue. */
+export declare function isMlsDevGroupRoomRecoveryFailure(error: unknown): error is EndpointError;
+/** Derived exclusively from an atomically committed, native-verified application. */
+export interface MlsDevVerifiedMessageBinding {
+    readonly version: 1;
+    readonly protocol: MlsDevTextProtocol;
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly groupId: string;
+    readonly operationId: string;
+    readonly feedOrdinal: number;
+    readonly envelopeHash: string;
+    readonly senderDeviceId: string;
+    readonly senderPrincipal: MlsDevEnrollmentPrincipal;
+    readonly head: MlsDevGroupHead;
+    readonly acceptedAtMs: number;
+    /** The account the sender's alias opens to in this room, or the erased sender (mls-dev-groups.md, erasure privacy). */
+    readonly senderId: string;
+}
+/** An online, fully caught-up audience snapshot for a model turn and its delivery guard. */
+export interface MlsDevAdmissionHold {
+    readonly held: boolean;
+    readonly waitingPrincipalIds: readonly string[];
+}
+export interface MlsDevCurrentAudience {
+    readonly version: 1;
+    readonly protocol: MlsDevTextProtocol;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly ownDeviceId: string;
+    readonly head: MlsDevGroupHead;
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+    readonly roster: readonly MlsDevGroupRosterEntry[];
+    readonly feedOrdinal: number;
+}
+/** One encrypted card operation in a v2 room (encrypted-interactions.md §2.3): exactly one of `request` (agents),
+ * `response` (the responder; a secret's plaintext goes in `secret`, which native seals and the endpoint never stores)
+ * or `withdraw` (the requesting device). */
+export interface MlsDevInteractionInput {
+    readonly conversationId: string;
+    readonly messageId?: string;
+    readonly operationId?: string;
+    readonly guardId?: string;
+    readonly request?: Omit<MlsDevInteractionRequestBody, 'secretKey'>;
+    readonly response?: {
+        readonly requestId: string;
+        readonly agentId: string;
+        readonly answer: MlsDevInteractionAnswer;
+    } | {
+        readonly requestId: string;
+        readonly agentId: string;
+        readonly secret: string;
+    };
+    readonly withdraw?: {
+        readonly requestId: string;
+        readonly reason: MlsDevInteractionWithdrawReason;
+    };
+}
+export interface MlsDevGroupClient {
+    createRoom(input: {
+        conversationId: string;
+        name: string;
+        memberIds: string[];
+        operationId?: string;
+        protocol?: MlsDevTextProtocol;
+    }): Promise<EndpointOperation>;
+    create(input: {
+        conversationId: string;
+        operationId?: string;
+    }): Promise<EndpointOperation>;
+    add(input: {
+        conversationId: string;
+        claimRequestId: string;
+        operationId?: string;
+    }): Promise<EndpointOperation>;
+    remove(input: {
+        conversationId: string;
+        removedDeviceId: string;
+        operationId?: string;
+    }): Promise<EndpointOperation>;
+    refresh(conversationId: string): Promise<MlsDevGroupView | undefined>;
+    read(conversationId: string): Promise<MlsDevGroupView | undefined>;
+    readVerifiedMessageBinding(input: {
+        conversationId: string;
+        messageId: string;
+    }): Promise<MlsDevVerifiedMessageBinding | undefined>;
+    readCurrentAudience(conversationId: string): Promise<MlsDevCurrentAudience>;
+    /** D2 (mls-rooms-by-default.md §2.7): in a room Canon made, the current members with no device in this device's group;
+     * while there are any, the room sends nothing. Local state only, as of the last refresh. */
+    readAdmissionHold(conversationId: string): Promise<MlsDevAdmissionHold>;
+    assertCurrentAudience(expected: MlsDevCurrentAudience): Promise<void>;
+    readRecoveryFailure(conversationId: string): Promise<MlsDevGroupRecoveryFailure | undefined>;
+    /** Encrypts, journals and queues one card operation from this device; never inbox input for anyone. */
+    sendInteraction(input: MlsDevInteractionInput): Promise<EndpointOperation>;
+    /** The local reduction of one request, with its derived state (the local deadline is authoritative). */
+    readInteraction(input: {
+        conversationId: string;
+        agentId: string;
+        requestId: string;
+    }): Promise<MlsDevInteractionView | undefined>;
+    /** The requester opens its answered secret once, in memory; the one-time key is deleted in the same commit. */
+    openSecretAnswer(input: {
+        conversationId: string;
+        requestId: string;
+    }): Promise<string>;
+}
+export interface MlsDevGroupBridge {
+    hash(value: string): Promise<string>;
+    hashBytes?(value: Uint8Array): Promise<string>;
+    resolveProtocol?(conversationId: string): Promise<MlsDevTextProtocol | undefined>;
+    queryFeed?(request: MlsDevGroupFeedQuery): Promise<MlsDevGroupFeedResult>;
+    query(request: MlsDevGroupQuery): Promise<MlsDevGroupQueryResult>;
+    queue(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<EndpointOperation>;
+    settle(tx: EndpointStoreTransaction, operation: EndpointOperation, receipt: EndpointOperationReceipt, acceptedEcho: boolean): Promise<EndpointOperation>;
+    afterReceipt(operation: EndpointOperation): Promise<void>;
+    submitted(operation: EndpointOperation): void;
+    lookup(operationId: string, installationId: string): Promise<EndpointOperationReceipt | null>;
+    /** Renews this device's credential when due, before an operation captures it. Best effort: the operation's own
+     * credential checks still decide. */
+    ensureDevice?(): Promise<unknown>;
+    /** A Welcome used up one of this device's KeyPackages; called after its commit. */
+    keyPackageConsumed?(): void;
+    /** A control of this device's settled, accepted or lost to another device's: what waited on it can go on now. A hint
+     * announcing the room's change may have come while it was pending, and none may follow (D2 holds the room's sends). */
+    controlSettled?(conversationId: string): void;
+    /** Reads and applies the room's conversation snapshot from Canon, for openings of members admitted since. */
+    readRoom?(conversationId: string): Promise<unknown>;
+}
+/** 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): {
+    client: MlsDevGroupClient;
+    commitHeldRemoval(conversationId: string): Promise<EndpointOperation | undefined>;
+    /** Forwards an encrypted text by re-encryption: this device's own decrypted copy, sent as new text to another
+     * 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>;
+    queryTextHistory(conversationId: string, name: string, parameters: Record<string, unknown>): Promise<{
+        messages: Record<string, unknown>[];
+        nextBefore?: string | null;
+        missingMessageIds?: string[];
+    }>;
+    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>;
+};
+export {};

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

@@ -0,0 +1,46 @@
+import { type MlsDevDeviceBinding, type MlsDevKeyPackagePayload, type MlsDevKeyPackagePublicationReceipt, type MlsDevKeyPackageClaimReceipt, type MlsDevKeyPackageClaimPreconditions } from '../backend-contracts/index.js';
+import type { createMlsDevDeviceCoordinator, MlsDevKeyPackagePrerequisite } from './mls-dev-device.js';
+import type { MlsDevDeviceClientContext, MlsDevDeviceClientOptions } from './mls-dev-client.js';
+import { type EndpointStore, type EndpointStoreTransaction } from './store.js';
+/** Historical authenticated receipt; neither view grants current room authority. */
+export interface MlsDevKeyPackagePublicationView {
+    readonly status: 'published';
+    readonly receipt: MlsDevKeyPackagePublicationReceipt;
+}
+export interface MlsDevKeyPackageClaimView {
+    readonly status: 'claimed';
+    readonly receipt: MlsDevKeyPackageClaimReceipt;
+}
+export interface MlsDevKeyPackageClaimInput {
+    readonly requestId: string;
+    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: {
+        keyPackageId: string;
+    }): Promise<MlsDevKeyPackagePublicationView>;
+    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. */
+export declare function createMlsDevKeyPackageService(options: MlsDevDeviceClientOptions, context: MlsDevDeviceClientContext, store: EndpointStore, initialized: () => Promise<{
+    binding: MlsDevDeviceBinding;
+    device: ReturnType<typeof createMlsDevDeviceCoordinator>;
+}>, readPrepared: (tx: EndpointStoreTransaction, binding: MlsDevDeviceBinding, id: string, current: MlsDevKeyPackagePrerequisite, historical?: boolean) => Promise<MlsDevKeyPackagePayload | undefined>): MlsDevKeyPackageServiceClient;

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

@@ -0,0 +1,62 @@
+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, 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';
+export type MlsDevProtectedKeyPackagePreparer = (context: MlsDevDeviceContext, command: MlsDevKeyPackageCommand, wrappedIdentityState: string) => Promise<MlsDevKeyPackagePreparation>;
+/** A committed local preparation, never a current publication authorization. */
+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;
+    }): Promise<MlsDevKeyPackageView>;
+    /** 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>;
+export interface MlsDevPreparedKeyPackageSnapshot {
+    readonly binding: MlsDevDeviceBinding;
+    readonly command: MlsDevKeyPackageCommand;
+    readonly payload: MlsDevKeyPackagePayload;
+    readonly wrappedState: string;
+    readonly fingerprint: string;
+}
+/** Internal private-provider capture for Welcome, never exported on Endpoint. */
+export declare function captureMlsDevPreparedKeyPackage(tx: EndpointStoreTransaction, binding: MlsDevDeviceBinding, id: string, current: MlsDevKeyPackagePrerequisite): Promise<MlsDevPreparedKeyPackageSnapshot | undefined>;
+/** The caller has already verified the accepted Welcome and group snapshot.
+ * Consumption shares that transaction; failure rolls back private state erasure. */
+export declare function consumeMlsDevPreparedKeyPackage(tx: EndpointStoreTransaction, captured: MlsDevPreparedKeyPackageSnapshot, current: MlsDevKeyPackagePrerequisite, control: {
+    conversationId: string;
+    groupId: string;
+    controlSequence: number;
+}): Promise<void>;
+/** 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

@@ -0,0 +1,38 @@
+import { type MlsDevKeyPackagePublishRequest, type MlsDevKeyPackagePublicationReceipt, type MlsDevKeyPackageClaimRequest, type MlsDevKeyPackageClaimReceipt, type MlsDevEnrollmentBeginRequest, type MlsDevEnrollmentCompleteRequest, type MlsDevEnrollmentChallenge, type MlsDevEnrollmentResult, type MlsDevCredentialBeginRequest, type MlsDevCredentialCompleteRequest, type MlsDevCredentialChallenge, type MlsDevCredentialReceipt, type MlsDevCredentialRevokeRequest, type MlsDevCredentialRevocationReceipt, type MlsDevCredentialReconciliationBeginRequest, type MlsDevCredentialReconciliationCompleteRequest, type MlsDevCredentialReconciliationChallenge, type MlsDevCredentialReconciliationReceipt } from '../backend-contracts/index.js';
+import { type EndpointCredentials } from './transport.js';
+export interface MlsDevKeyPackageTransport {
+    publish(request: MlsDevKeyPackagePublishRequest, signal?: AbortSignal): Promise<MlsDevKeyPackagePublicationReceipt>;
+    claim(request: MlsDevKeyPackageClaimRequest, signal?: AbortSignal): Promise<MlsDevKeyPackageClaimReceipt>;
+}
+/** Authenticated Dev registration/issuance only; no room or history authority. */
+export interface MlsDevDeviceTransport {
+    readonly keyPackages?: MlsDevKeyPackageTransport;
+    beginEnrollment(request: MlsDevEnrollmentBeginRequest, signal?: AbortSignal): Promise<MlsDevEnrollmentChallenge>;
+    completeEnrollment(request: MlsDevEnrollmentCompleteRequest, signal?: AbortSignal): Promise<MlsDevEnrollmentResult>;
+    beginCredential(request: MlsDevCredentialBeginRequest, signal?: AbortSignal): Promise<MlsDevCredentialChallenge>;
+    completeCredential(request: MlsDevCredentialCompleteRequest, signal?: AbortSignal): Promise<MlsDevCredentialReceipt>;
+    beginReconciliation(request: MlsDevCredentialReconciliationBeginRequest, signal?: AbortSignal): Promise<MlsDevCredentialReconciliationChallenge>;
+    completeReconciliation(request: MlsDevCredentialReconciliationCompleteRequest, signal?: AbortSignal): Promise<MlsDevCredentialReconciliationReceipt>;
+    revokeCredential(request: MlsDevCredentialRevokeRequest, signal?: AbortSignal): Promise<MlsDevCredentialRevocationReceipt>;
+    verifyGenerationObservation(receipt: MlsDevCredentialReconciliationReceipt): boolean;
+}
+export interface MlsDevDeviceHttpOptions {
+    enrollmentUrl: string;
+    credentialUrl: string;
+    reconciliationUrl: string;
+    keyPackagesUrl?: string;
+    /** Explicit origins trusted to receive the endpoint's login/API-key bearer. */
+    trustedOrigins: readonly string[];
+    /** Synthetic tests only: literal 127.0.0.1 or [::1], never DNS/remote HTTP. */
+    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.
+ * Only a declared MLS environment, and only responses that name that environment. */
+export declare function createMlsDevDeviceHttpTransport(config: MlsDevDeviceHttpOptions, dependencies: {
+    environmentId: string;
+    credentials: EndpointCredentials;
+    fetch: typeof globalThis.fetch;
+    timeoutMs?: number;
+    ownershipHeaders(): Record<string, string>;
+}): MlsDevDeviceTransport;

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

@@ -0,0 +1,29 @@
+import type { MlsDevProtectedPreparer } from './mls-dev-device.js';
+import type { MlsDevProtectedKeyPackagePreparer } from './mls-dev-key-packages.js';
+import type { MlsDevProtectedGroupPreparer } from './mls-dev-groups.js';
+export interface NodeMlsDevCustody {
+    readonly prepareProtected: MlsDevProtectedPreparer;
+    readonly prepareProtectedKeyPackage: MlsDevProtectedKeyPackagePreparer;
+    readonly prepareProtectedGroup: MlsDevProtectedGroupPreparer;
+    /** Cancels owned processes; never destroys custody or committed wrapped state. */
+    close(): Promise<void>;
+}
+export declare class NodeMlsDevCustodyError extends Error {
+    readonly code = "MLS_NODE_CUSTODY_REJECTED";
+    constructor();
+}
+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;
+export declare function frame(operation: number, values: readonly (string | null)[]): Buffer;
+/** JSON.parse supplies grammar validation; this pass rejects duplicate object
+ * names (including escaped aliases) before the closed contract parsers run. */
+export declare function parseJson(bytes: Buffer): unknown;
+export declare function typedNodeMlsDevCustody(job: <T>(work: (signal: AbortSignal) => Promise<T>) => Promise<T>, invoke: (operation: number, values: readonly (string | null)[], signal: AbortSignal) => Promise<unknown>, close: () => Promise<void>): NodeMlsDevCustody;

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

@@ -0,0 +1,15 @@
+import { type NodeMlsDevCustody } from './node-mls-custody-protocol.js';
+export interface NodeMlsDevCustodyOptions {
+    /** Canonical absolute path to the installed, signed .app (no symlink components). */
+    readonly bundlePath: string;
+    /** SHA-256 of the adjacent <bundlePath>.manifest.json; provision independently. */
+    readonly manifestSha256: string;
+    readonly executableSha256: string;
+    readonly bundleIdentifier: string;
+    readonly teamIdentifier: string;
+    /** Whole preparation, including signature checks and initialization. Default 30s. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export { NodeMlsDevCustodyError, type NodeMlsDevCustody } from './node-mls-custody-protocol.js';
+export declare function createNodeMlsDevCustody(options: NodeMlsDevCustodyOptions): NodeMlsDevCustody;

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

@@ -0,0 +1,7 @@
+import type { EndpointStore } from './store.js';
+export declare function createNodeEndpointStore(options: {
+    directory: string;
+    namespace: string;
+}): Promise<EndpointStore>;
+export { createNodeMlsDevCustody, NodeMlsDevCustodyError, type NodeMlsDevCustody, type NodeMlsDevCustodyOptions } from './node-mls-custody.js';
+export { createPortableNodeMlsDevCustody, type PortableNodeMlsDevCustody, type PortableNodeMlsDevCustodyOptions } from './portable-node-mls-custody.js';

package/dist/internal/endpoint/observe-query.d.ts

@@ -0,0 +1,17 @@
+export interface EndpointQueryObserver {
+    observe<T>(query: string, parameters: Record<string, unknown>, listener: (value: T) => void, onError?: (error: unknown) => void): () => void;
+    invalidate(affected?: (query: string, parameters: Record<string, unknown>) => boolean): void;
+    /** Re-arm idle subscriptions when the connection changes their polling cadence. */
+    reschedule(): void;
+    close(): void;
+}
+/**
+ * One temporary polling subscription per query per endpoint. UI components only
+ * subscribe; the endpoint owns fetching, coalescing, retry and lifecycle. A
+ * durable change-feed can call invalidate without changing any consumers.
+ */
+export declare function createEndpointQueryObserver(options: {
+    query: <T>(query: string, parameters: Record<string, unknown>) => Promise<T>;
+    intervalMs?: number;
+    getPollInterval?: () => number;
+}): EndpointQueryObserver;

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

@@ -0,0 +1,23 @@
+import { type MlsDevDeviceContext } from '../backend-contracts/index.js';
+import { type NodeMlsDevCustody } from './node-mls-custody-protocol.js';
+export interface PortableNodeMlsDevCustodyOptions {
+    readonly executablePath: string;
+    readonly executableSha256: string;
+    /** Independently provisioned public identity, vault location and issuer pins. */
+    readonly configurationPath: string;
+    readonly configurationSha256: string;
+    /** An operator-managed credential mount, separate from the vault. JS opens but never reads it. */
+    readonly secretSource: {
+        readonly kind: 'managed-file';
+        readonly path: string;
+    };
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PortableNodeMlsDevCustody extends NodeMlsDevCustody {
+    /** Deliberate first provisioning only. An existing or missing-on-restart vault is never replaced. */
+    provision(context: MlsDevDeviceContext): Promise<void>;
+}
+/** Portable software custody. Qualification currently covers Unix descriptor
+ * inheritance only; Windows must get its own ACL/handle acceptance before use. */
+export declare function createPortableNodeMlsDevCustody(options: PortableNodeMlsDevCustodyOptions): PortableNodeMlsDevCustody;

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

@@ -0,0 +1,22 @@
+import type { EndpointInboundRecord, EndpointIntent, EndpointOperation } from './engine.js';
+import type { EndpointStoreTransaction } from './store.js';
+/** `provider`: a job the server runs inline for as long as its provider takes; unordered, and never awaited by a drain. */
+export type EndpointOrdering = 'conversation' | 'message' | 'signal' | 'artifact' | 'independent' | 'provider';
+/** Derived here, never an adapter override. Unknown/state-changing actions stay ordered. */
+export declare function endpointIntentOrdering(intent: EndpointIntent): EndpointOrdering;
+/** Transaction sequence is ordering metadata, never an idempotency identity. */
+export declare function nextQueueSequence(tx: EndpointStoreTransaction, name: string): Promise<number>;
+export declare function orderOperation(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<EndpointOperation>;
+export declare const outboxKey: (operation: EndpointOperation) => string;
+/** Per-work lane of non-terminal shared-work operations, in authoring order. */
+export declare const artifactOrderingPrefix: (conversationId: string, artifactId: string) => string;
+export declare const operationOrderingKey: (operation: EndpointOperation) => string | undefined;
+export declare function trackOperationOrder(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<void>;
+export declare function enqueueOperation(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<void>;
+export declare function removeOperationOutbox(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<void>;
+export declare function settleOperationOrder(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<void>;
+export declare function isFirstOrderedOperation(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<boolean>;
+export declare const inboundReadyKey: (record: EndpointInboundRecord) => string;
+export declare function orderInbound(tx: EndpointStoreTransaction, record: EndpointInboundRecord): Promise<EndpointInboundRecord>;
+export declare function enqueueInbound(tx: EndpointStoreTransaction, record: EndpointInboundRecord): Promise<void>;
+export declare function removeInboundReady(tx: EndpointStoreTransaction, record: EndpointInboundRecord): Promise<void>;