@canonmsg/agent-sdk 12.0.0 → 12.2.0

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

@@ -141,25 +141,6 @@ export interface CanonConversation {
     activeCall?: CanonActiveCallSummary | null;
     createdAt: string;
 }
-/** Opt-in paging for `GET /conversations`. Omit both fields for the full list. */
-export interface CanonConversationsPageOptions {
-    /** Page size, 1..100 (server default 50 when the parameter is present). */
-    limit?: number;
-    /** Cursor from a previous page's `nextBefore`. */
-    before?: string;
-}
-/**
- * One page of conversations. Pages are cut in conversation-id order (stable
- * under live traffic); each page's array is still sorted most-recent-first
- * *within the page*, so concatenating pages is not globally recency-sorted.
- * `nextBefore` is null when the sweep is exhausted — a short page is not a
- * reliable end signal, because hidden conversations are filtered after the
- * page is read.
- */
-export interface CanonConversationsPage {
-    conversations: CanonConversation[];
-    nextBefore: string | null;
-}
 export interface CanonMessagesPage {
     messages: CanonMessage[];
     nextBefore?: string | null;
@@ -185,34 +166,9 @@ export interface CanonRuntimeProvenance {
         type?: CanonSelfContext['type'] | string | null;
     } | null;
 }
-/**
- * Outcome of `CanonClient.addMember` / `agent.addMember`. The REST endpoint
- * returns 201 on immediate add and 202 when a group invite is waiting for
- * policy approval.
- * Both are success from the protocol's perspective — distinct outcomes for
- * the caller.
- */
-export type AddMemberResult = {
-    status: 'added';
-} | {
-    status: 'pending';
-    requestId: string;
-};
 export type ContactSource = 'direct_add' | 'phone_book' | 'contact_request' | 'link' | 'qr' | 'group' | 'open_inbound_message'
 /** Sentinel value emitted by stream-service when a doc lacks a source field. */
  | 'unknown';
-/** A single entry from the agent's `users/{agentId}/contacts/` subcollection. */
-export interface CanonContact {
-    /** The contact's userId. */
-    id: string;
-    source: ContactSource;
-    addedAt: string | null;
-    displayNameOverride: string | null;
-}
-export type ContactAddedPayload = CanonContact;
-export type ContactRemovedPayload = {
-    id: string;
-};
 export type ResolvedAdmissionState = 'self' | 'not-found' | 'allowed' | 'request-required' | 'pending-outbound' | 'blocked' | 'inactive';
 export interface ResolvedAdmissionTargetSummary {
     id: string;
@@ -236,49 +192,12 @@ export interface ResolvedTargetAdmissionPayload {
     blockedByViewer?: boolean;
     blockedByTarget?: boolean;
 }
-export type ResolveAdmissionTargetInput = {
-    targetUserId: string;
-    canonContactId?: never;
-} | {
-    canonContactId: string;
-    targetUserId?: never;
-};
 export interface CanonResolveAdmissionResult {
     resolvedTargetUserId?: string | null;
     target: ResolvedAdmissionTargetSummary | null;
     admission: ResolvedTargetAdmissionPayload;
 }
 export type AgentClientType = SerializedAgentClientType;
-export interface ResolvedAdmission {
-    discoverable: boolean;
-    inboundPolicy: CommunicationRule;
-    outboundPolicy?: CommunicationRule;
-    groupJoinPolicy: CommunicationRule;
-}
-/** Declares what session controls an agent type supports. */
-export interface AgentCapabilities {
-    supportsModelSwitch: boolean;
-    supportsPermissionMode: boolean;
-    /**
-     * Whether permissionMode can be changed mid-session. When undefined,
-     * defaults to `supportsPermissionMode` — keep the UI chip non-interactive
-     * for agents whose approval mode is locked at session creation.
-     */
-    supportsRuntimePermissionMode?: boolean;
-    supportsEffort: boolean;
-    supportsSessionState: boolean;
-    supportsInterrupt: boolean;
-    supportsQueue?: boolean;
-    supportsInterleave?: boolean;
-    /**
-     * Whether the agent can present a plan for approval before executing
-     * (Mac-app "plan mode"). First-class so clients can advertise/query it
-     * instead of inferring it from the descriptor's turnModes shape.
-     */
-    supportsPlanMode?: boolean;
-    /** Whether the agent asks the user structured questions (AskUserQuestion-style). */
-    supportsQuestions?: boolean;
-}
 export interface ModelOption {
     value: string;
     label: string;
@@ -553,8 +472,6 @@ export interface RuntimeInfoPayload {
     notes?: ReadonlyArray<string>;
     updatedAt?: number;
 }
-/** Capability map keyed by clientType. Add new agent types here. */
-export declare const AGENT_CAPABILITIES: Record<AgentClientType, AgentCapabilities>;
 /** Trusted agent identity & access context, provided by the server */
 export interface AgentContext {
     agentId: string;
@@ -578,11 +495,6 @@ export interface AgentContext {
     clientType?: AgentClientType;
     defaultBehavior?: ResolvedAgentBehaviorPolicy;
 }
-export interface UpdateAgentProfileOptions {
-    name?: string;
-    avatarUrl?: string | null;
-    description?: string;
-}
 export interface CanonTurnDispatch {
     kind: 'run_turn' | 'observe_only';
     reason: string;
@@ -628,29 +540,6 @@ export interface MessageCreatedPayload {
         contactCard?: ContactCardPayload;
     };
 }
-export interface MessageUpdatedPayload {
-    conversationId: string;
-    messageId: string;
-    actorId?: string;
-    updatedAt?: string;
-    changes: {
-        reactions?: Record<string, string[]>;
-        /** Canonical ready attachments after asynchronous media processing. */
-        attachments?: MediaAttachment[];
-        [key: string]: unknown;
-    };
-}
-export interface TypingPayload {
-    conversationId: string;
-    userId: string;
-    isTyping: boolean;
-    status?: 'thinking' | 'typing';
-    timestamp?: number;
-}
-export interface PresencePayload {
-    userId: string;
-    online: boolean;
-}
 export interface RuntimeUpdatedPayload {
     conversationId: string;
     agentId: string;
@@ -658,126 +547,6 @@ export interface RuntimeUpdatedPayload {
     runtimeInfo?: RuntimeInfoPayload | null;
     agentSession: AgentSessionSnapshot | null;
 }
-export interface TurnUpdatedPayload {
-    conversationId: string;
-    agentId: string;
-    turn: import('./turn-protocol.js').TurnState | null;
-}
-/**
- * Observe-only notice that the participation gate suppressed a turn this
- * agent would otherwise have been dispatched (cap reached, mention required,
- * agent-to-agent disabled). Hosts must not run a turn off this event; it
- * exists so a benched agent can tell deliberate policy from a dead stream.
- */
-export interface ParticipationSuppressedPayload {
-    conversationId: string;
-    /** The triggering message whose dispatch was suppressed. */
-    messageId: string;
-    /** Machine code, e.g. 'agent_turn_limit_reached' | 'group_mention_required'. */
-    reasonCode: string;
-    /** Human-readable form of the same reason. */
-    reason: string;
-    /** ISO timestamp stamped by stream-service at suppression time. */
-    suppressedAt: string;
-}
-export type RuntimeControlEventKind = 'interaction_response' | 'session' | 'signal' | 'primitive' | 'runtimeInput' | 'runtimeCard' | 'runtimeApproval';
-export interface RuntimeControlEventPayload {
-    conversationId: string;
-    agentId: string;
-    kind: RuntimeControlEventKind;
-    requestId?: string;
-    updatedAt?: number;
-    value: Record<string, unknown>;
-    /** Conversation-scoped reply capability for an accepted interaction receipt. */
-    replyAuthority?: import('../backend-contracts/index.js').AgentReplyAuthorityV1;
-}
-export interface CanonMembershipChange {
-    addedMemberIds: string[];
-    removedMemberIds: string[];
-    memberCount: number;
-}
-export interface CanonKnownRecentParticipant {
-    id: string;
-    name: string;
-    userType: 'human' | 'ai_agent' | 'unknown';
-    isOwner: boolean;
-    isSelf: boolean;
-}
-export interface CanonGroupContext {
-    memberCount: number;
-    memberIds: string[];
-    ownerId: string;
-    ownerName: string;
-    ownerPresent: boolean;
-    knownRecentParticipants: CanonKnownRecentParticipant[];
-    /** Complete current roster, including participants who have not spoken. */
-    participants?: CanonKnownRecentParticipant[];
-    membershipChange?: CanonMembershipChange;
-}
-export type CanonGroupContextMode = 'initial' | 'membership_change';
-export interface ConversationUpdatedPayload {
-    conversationId: string;
-    changes: Record<string, unknown>;
-    membershipChange?: CanonMembershipChange;
-}
-export interface VoiceSessionEventPayload {
-    conversationId: string;
-    session: CanonVoiceSession;
-    /**
-     * True when this call targets the receiving agent (runtime_voice aimed at
-     * it). Voice events are conversation-scoped — group and human-mode calls
-     * arrive with targetsMe false; never auto-join on a bare 'started'.
-     * Absent on streams older than the media/video rollout: treat as targeted
-     * (the legacy filter only delivered targeted sessions).
-     */
-    targetsMe?: boolean;
-}
-export type CanonStreamEvent = {
-    type: 'agent.context';
-    payload: AgentContext;
-} | {
-    type: 'message.created';
-    payload: MessageCreatedPayload;
-} | {
-    type: 'message.updated';
-    payload: MessageUpdatedPayload;
-} | {
-    type: 'contact.added';
-    payload: ContactAddedPayload;
-} | {
-    type: 'contact.removed';
-    payload: ContactRemovedPayload;
-} | {
-    type: 'typing';
-    payload: TypingPayload;
-} | {
-    type: 'presence';
-    payload: PresencePayload;
-} | {
-    type: 'runtime.updated';
-    payload: RuntimeUpdatedPayload;
-} | {
-    type: 'turn.updated';
-    payload: TurnUpdatedPayload;
-} | {
-    type: 'runtime.control';
-    payload: RuntimeControlEventPayload;
-} | {
-    type: 'message.deleted';
-    payload: {
-        conversationId: string;
-        messageId: string;
-    };
-} | {
-    type: 'conversation.updated';
-    payload: ConversationUpdatedPayload;
-} | {
-    type: 'voice.session.started';
-    payload: VoiceSessionEventPayload;
-} | {
-    type: 'voice.session.ended';
-    payload: VoiceSessionEventPayload;
-};
 export interface SendMessageOptions {
     messageId?: string;
     contentType?: 'text' | 'audio' | 'image' | 'video' | 'file' | 'contact_card';
@@ -794,13 +563,6 @@ export interface SendMessageOptions {
     /** Trusted transport context injected by the host, never by the model. */
     replyAuthority?: import('../backend-contracts/index.js').AgentReplyAuthorityV1;
 }
-export interface CreateGroupOptions {
-    memberIds: string[];
-    name: string;
-}
-export interface CreateGroupResult {
-    conversationId: string;
-}
 export type CanonVoiceSessionMode = 'human' | 'runtime_voice';
 export type CanonVoiceSessionStatus = 'active' | 'ended' | 'error';
 /** Call media. Absent anywhere in the wire always means 'audio'. */
@@ -848,52 +610,6 @@ export interface CanonVoiceSessionToken {
     targetAgentId?: string | null;
     expiresAt: string;
 }
-export interface CreateVoiceSessionOptions {
-    conversationId: string;
-    targetAgentId?: string | null;
-    /** Requested call media; the server defaults absent/unknown to 'audio'. */
-    media?: CanonVoiceSessionMedia;
-}
-export type CanonMemoStreamStatus = 'live' | 'finalizing' | 'finalized' | 'aborted';
-export interface CreateMemoStreamOptions {
-    conversationId: string;
-    /** v1 accepts 'wav' only (byte-append decodable and seekable everywhere). */
-    container: 'wav';
-    codec: {
-        mimeType: string;
-        sampleRate: number;
-        channels: number;
-        bitsPerSample: number;
-    };
-    /** Byte offset of PCM data in the sender's file (RIFF headers precede it). */
-    dataOffset?: number;
-    /** Pre-allocated durable message id, for the live→durable timeline handoff. */
-    messageId?: string | null;
-}
-export interface CreateMemoStreamResult {
-    streamId: string;
-    bucket: string;
-}
-export interface AppendMemoStreamChunkOptions {
-    /** Zero-based, strictly sequential. Retries of the last chunk are acked. */
-    seq: number;
-    /** Base64 chunk bytes; may be empty when only carrying the final marker. */
-    data: string;
-    /** Normalized 0..1 amplitude bars for live waveforms. */
-    peaks?: number[];
-    /** Running duration of the recording in milliseconds. */
-    durationMs?: number;
-    /** Marks the recording finished; the stream leaves the live window. */
-    final?: boolean;
-}
-export interface MemoStreamChunkAck {
-    chunkCount: number;
-    totalBytes: number;
-    applied: boolean;
-}
-export interface JoinVoiceSessionOptions {
-    conversationId: string;
-}
 export type StreamingStatus = 'thinking' | 'streaming' | 'tool' | 'waiting_input';
 export interface SetStreamingOptions {
     conversationId: string;
@@ -1057,14 +773,6 @@ export interface RegistrationInput {
     requestedAgentId?: string;
     localRegistrationId?: string;
 }
-export interface RegistrationResult {
-    status: 'approved' | 'rejected' | 'timeout';
-    apiKey?: string;
-    agentId?: string;
-    agentName?: string;
-    requestId?: string;
-    pollToken?: string;
-}
 export interface RegistrationStatus {
     status: 'pending' | 'approving' | 'approved' | 'rejected';
     agentName: string;

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

@@ -1,5 +1,5 @@
 import { type EndpointMessageGroupInput } from './delivery.js';
-import { type PreparedContent, type EndpointEvent, type EndpointOperationReceipt, type EndpointOperationRequest, type EndpointCapabilities, type EndpointPreconditions } from '../backend-contracts/index.js';
+import { type PreparedContent, type EndpointEvent, type EndpointOperationReceipt, type EndpointOperationRequest, type EndpointCapabilities, type EndpointPreconditions, type StartDirectInput, type StartDirectResult } from '../backend-contracts/index.js';
 import { type EndpointStore } from './store.js';
 import { type EndpointCredentials, type EndpointTransport } from './transport.js';
 import { type EndpointInboundConsumer, type EndpointInboundConsumerOptions } from './inbound.js';
@@ -116,6 +116,12 @@ export interface EndpointOptions {
     hashBytes?: (value: Uint8Array) => Promise<string>;
     queryIntervalMs?: number;
     leaseMs?: number;
+    /** The admission duty's retry while a member still has no device in an encrypted room (mls-rooms-by-default.md §2.4):
+     * the first delay and the most it backs off to. Defaults 30 s and 2 min. */
+    mlsAdmissionRetryMs?: {
+        initial: number;
+        maximum: number;
+    };
     /** Must remain shorter than the server's guaranteed receipt retention. */
     retryHorizonMs?: number;
     /** Agent input must pass the same server admission policy as live delivery. */
@@ -154,6 +160,18 @@ export interface Endpoint {
     subscribe(listener: (operation: EndpointOperation) => void): () => void;
     query<T>(query: string, parameters?: Record<string, unknown>): Promise<T>;
     capabilities(): Promise<EndpointCapabilities | null>;
+    /** This account's MLS principal ID: its alias, checked against its opening, or its account ID while it has none
+     * (mls-dev-groups.md, erasure privacy). */
+    mlsPrincipalId(): Promise<string>;
+    /** The account an MLS principal in this room's group stands for, by the room's checked openings; undefined when nothing
+     * opens it as that type (an erased account's alias). */
+    mlsAccountOf(conversationId: string, principal: {
+        type: string;
+        id: string;
+    }): Promise<string | undefined>;
+    /** The alias an account of this type carries in this room's group, among `admitted` aliases when given; undefined when
+     * none or several do (its account ID while it has none, until step 14c). */
+    mlsAliasOf(conversationId: string, accountId: string, type: 'human' | 'ai_agent', admitted?: readonly string[]): Promise<string | undefined>;
     publish<T = unknown>(action: string, body: Record<string, unknown>): Promise<T>;
     observeQuery<T>(query: string, parameters: Record<string, unknown>, listener: (value: T) => void, onError?: (error: unknown) => void): () => void;
     refreshQueries(): void;
@@ -171,6 +189,18 @@ export interface Endpoint {
      * Return false to defer, or throw a nonretryable EndpointError to retire an
      * unsent operation. An attempted operation still needs its server receipt. */
     registerDeliveryGuard(id: string, allow: () => Promise<boolean>): () => void;
+    /** Keep a start's opening line that Canon did not store, and send it once the room and the request allow (§2a.13). */
+    deferOpener(input: {
+        conversationId: string;
+        messageId: string;
+        text: string;
+        requestId?: string | null;
+    }): Promise<void>;
+    /** Persist the opening line before starting a room; recover the start through its durable receipt. */
+    startWithheldOpener(input: Omit<StartDirectInput, 'opener'> & {
+        messageId: string;
+        text: string;
+    }): Promise<StartDirectResult>;
     applyConversationSnapshot<T extends EndpointConversation>(snapshot: T): Promise<T>;
     getConversation<T extends EndpointConversation = EndpointConversation>(id: string): Promise<T | null>;
     applyEvent(event: EndpointEvent): Promise<boolean>;

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

@@ -29,4 +29,4 @@ export { createMlsDevDeviceCoordinator, type MlsDevDeviceView, type MlsDevProtec
 export type { MlsDevDeviceClient, MlsDevDeviceClientOptions } from './mls-dev-client.js';
 export type { MlsDevDeviceTransport, MlsDevDeviceHttpOptions, MlsDevKeyPackageTransport } from './mls-dev-transport.js';
 export type { MlsDevKeyPackageClient, MlsDevKeyPackageView, MlsDevProtectedKeyPackagePreparer, MlsDevKeyPackagePublicationView, MlsDevKeyPackageClaimView, MlsDevKeyPackageClaimInput } from './mls-dev-key-packages.js';
-export type { MlsDevGroupClient, MlsDevVerifiedMessageBinding, MlsDevCurrentAudience, MlsDevGroupView, MlsDevGroupRecoveryFailure, MlsDevProtectedGroupPreparer } from './mls-dev-groups.js';
+export type { MlsDevGroupClient, MlsDevVerifiedMessageBinding, MlsDevCurrentAudience, MlsDevAdmissionHold, MlsDevGroupView, MlsDevGroupRecoveryFailure, MlsDevProtectedGroupPreparer } from './mls-dev-groups.js';

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

@@ -52,6 +52,8 @@ export interface EndpointMediaFlow {
         uploadId?: string;
         generation?: number;
         attachment?: Record<string, unknown>;
+        /** How many times a resend asked Canon to process this encrypted room's failed video again. */
+        processingRetries?: number;
     }>;
     purpose?: 'prepare';
     publicationGeneration?: number;
@@ -144,8 +146,11 @@ export interface EndpointMediaPipeline<Source> {
             descriptor: EndpointMediaDescriptor;
         }>;
     }, options?: EndpointMediaSendOptions): Promise<string>;
+    /** With `conversationId`, false for an encrypted room (or one whose mode is unknown): its files are prepared on the
+     * device and sent without the background handoff, so a caller decides before building their descriptors. */
     canSendInBackground(options?: {
         maxProbeWaitMs?: number;
+        conversationId?: string;
     }): Promise<boolean>;
     resume(id: string, options?: EndpointMediaSendOptions): Promise<string>;
     resumePending(): Promise<void>;

package/dist/internal/endpoint/mls-crypto.d.ts

@@ -1,4 +1,4 @@
-import { type MlsDevCredentialReceipt } from '../backend-contracts/index.js';
+import { type MlsDevCredentialReceipt, type MlsEnvironmentId } from '../backend-contracts/index.js';
 import type { MlsDevDeviceHttpOptions } from './mls-dev-transport.js';
 export interface MlsDevIssuerKey {
     readonly keyVersion: string;
@@ -6,13 +6,20 @@ export interface MlsDevIssuerKey {
 }
 export interface MlsDevClientConfiguration {
     readonly version: 1;
-    readonly environmentId: 'canon-dev-v1';
+    /** A declared MLS environment (`MLS_ENVIRONMENT_PROFILES`); every issuer key belongs to it. */
+    readonly environmentId: MlsEnvironmentId;
     readonly enabled: true;
-    readonly principalIds: readonly string[];
+    /**
+     * A Dev build's synthetic accounts, the only ones it sets a device up for. A production build lists none: Canon's
+     * eligibility (`/endpoint/capabilities`) decides who uses MLS, so an account made after the build can.
+     */
+    readonly principalIds?: readonly string[];
     readonly issuerKeys: readonly MlsDevIssuerKey[];
+    /** The feed-receipt keys native checks Canon's signed acceptance times with (mls-signed-acceptance.md). */
+    readonly receiptKeys: readonly MlsDevIssuerKey[];
 }
-/** Reviewed Dev gateway routes, never values learned from a credential response. */
-export declare const MLS_DEV_DEVICE_HTTP_CONFIGURATION: Readonly<MlsDevDeviceHttpOptions>;
+/** An environment's reviewed gateway routes on its own API origin, never values learned from a credential response. */
+export declare function mlsDevDeviceHttpConfiguration(environmentId: MlsEnvironmentId): Readonly<MlsDevDeviceHttpOptions>;
 /** Public build configuration. Issuer pins must come from reviewed provisioning;
  * authenticated service responses are not a trust-root distribution channel. */
 export declare function parseMlsDevClientConfiguration(value: unknown): MlsDevClientConfiguration;

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

@@ -23,9 +23,14 @@ export interface MlsDevDeviceClient {
     /** Requires a committed same-key credential proof, but not an issuer receipt. */
     reconcile(): Promise<MlsDevDeviceView>;
     /** Resume deliberate provisioning and keep an enrolled device ready, renewing
-     * within five minutes of expiry. Never creates an unrequested enrollment. */
+     * once less than half the credential's lifetime remains, so whatever this
+     * device sends stays valid for receivers at least that long. While the
+     * current credential is valid, a failed renewal returns it and is retried
+     * after a minute. Never creates an unrequested enrollment. */
     ensureReady(): Promise<MlsDevDeviceView>;
 }
+/** Whether readiness would renew this registered device: it has no credential, or less than half its lifetime remains. */
+export declare function isMlsDevCredentialRenewalDue(view: MlsDevDeviceView, now: number): boolean;
 /** Internal factory: the engine owns storage, lifetime, identity and generation. */
 export interface MlsDevDeviceClientContext {
     store: EndpointStore;
@@ -33,6 +38,9 @@ export interface MlsDevDeviceClientContext {
         identity: EndpointResolvedIdentity;
         installationGeneration: number;
     }>;
+    /** The account's MLS principal ID, its alias (mls-dev-groups.md, erasure privacy), as Canon gave and this device checked
+     * it; the account ID itself while it has none. Bindings, credentials and rosters carry it. */
+    mlsPrincipalId(): Promise<string>;
     signal: AbortSignal;
     assertOpen(): void;
     assertCurrent(tx: EndpointStoreTransaction): Promise<void>;

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

@@ -37,6 +37,8 @@ export interface MlsDevKeyPackagePrerequisite {
 export declare function createMlsDevDeviceCoordinator(input: {
     store: EndpointStore;
     binding: MlsDevDeviceBinding;
+    /** The endpoint identity's account, when the binding's principal is its alias. */
+    accountId?: string;
     installationGeneration: number;
     prepareProtected: MlsDevProtectedPreparer;
     /** Required independent issuer signature/trust validation, outside storage.

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

@@ -1,9 +1,10 @@
-import { type MlsDevEnrollmentPrincipal, type MlsDevDeviceContext, type MlsDevGroupContext, type MlsDevGroupCommand, type MlsDevGroupPreparation, type MlsDevGroupHead, type MlsDevGroupRosterEntry, type MlsDevGroupQuery, type MlsDevGroupQueryResult, MLS_DEV_TEXT_PROTOCOL, type MlsDevGroupFeedQuery, type MlsDevGroupFeedResult, type EndpointOperationReceipt } from '../backend-contracts/index.js';
+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 {
@@ -27,7 +28,7 @@ export declare function isMlsDevGroupRoomRecoveryFailure(error: unknown): error
 /** Derived exclusively from an atomically committed, native-verified application. */
 export interface MlsDevVerifiedMessageBinding {
     readonly version: 1;
-    readonly protocol: typeof MLS_DEV_TEXT_PROTOCOL;
+    readonly protocol: MlsDevTextProtocol;
     readonly conversationId: string;
     readonly messageId: string;
     readonly groupId: string;
@@ -38,11 +39,17 @@ export interface MlsDevVerifiedMessageBinding {
     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: typeof MLS_DEV_TEXT_PROTOCOL;
+    readonly protocol: MlsDevTextProtocol;
     readonly conversationId: string;
     readonly groupId: string;
     readonly ownDeviceId: string;
@@ -52,13 +59,36 @@ export interface MlsDevCurrentAudience {
     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?: typeof MLS_DEV_TEXT_PROTOCOL;
+        protocol?: MlsDevTextProtocol;
     }): Promise<EndpointOperation>;
     create(input: {
         conversationId: string;
@@ -81,13 +111,29 @@ export interface MlsDevGroupClient {
         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<typeof MLS_DEV_TEXT_PROTOCOL | undefined>;
+    resolveProtocol?(conversationId: string): Promise<MlsDevTextProtocol | undefined>;
     queryFeed?(request: MlsDevGroupFeedQuery): Promise<MlsDevGroupFeedResult>;
     query(request: MlsDevGroupQuery): Promise<MlsDevGroupQueryResult>;
     queue(tx: EndpointStoreTransaction, operation: EndpointOperation): Promise<EndpointOperation>;
@@ -95,11 +141,25 @@ export interface MlsDevGroupBridge {
     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>[];