@canonmsg/agent-sdk 11.2.0 → 12.0.0

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

@@ -0,0 +1,28 @@
+import { type CommunicationRule } from './communication.js';
+/** Shared social membership semantics; presentation and runtime ownership are separate. */
+export type ConversationRole = 'admin' | 'member';
+export type ConversationParticipantType = 'human' | 'ai_agent';
+export interface ConversationParticipantSummary {
+    humanCount: number;
+    agentCount: number;
+    totalCount: number;
+}
+/** `owner` is a read-only legacy spelling, never superior to another admin. */
+export declare function normalizeConversationRole(value: unknown): ConversationRole | null;
+export declare function isConversationAdminRole(value: unknown): boolean;
+export declare function readMembershipRevision(value: unknown): number;
+/** Behavioral scope follows the current roster, never the legacy shape label. */
+export declare function resolveConversationPolicyScope(memberIdsOrCount: unknown): 'direct' | 'group' | 'unknown';
+export declare function buildConversationParticipantSummary(participants: readonly {
+    userId: string;
+    userType: unknown;
+}[]): {
+    participantTypes: Record<string, ConversationParticipantType>;
+    participantSummary: ConversationParticipantSummary;
+    isAgentChat: boolean;
+};
+/** Legacy fields are compatibility inputs to one conservative invitation policy. */
+export declare function readConversationInvitationPolicy(data: {
+    inboundPolicy?: unknown;
+    groupJoinPolicy?: unknown;
+} | null | undefined): CommunicationRule;

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

@@ -0,0 +1,23 @@
+/** Transport execution and message publication are different facts. Only an
+ * authenticated delivery observation can establish a remote terminal outcome. */
+export type DeliveryRemoteOutcome = 'unknown' | 'pending' | 'published' | 'cancelled' | 'expired' | 'rejected';
+export type DeliveryExecutionPhase = 'preparing' | 'uploading' | 'waiting_for_connection' | 'sending' | 'cancelling' | 'idle';
+export interface DeliveryObservation {
+    schemaVersion: 2;
+    deliveryId: string;
+    messageId: string;
+    conversationId: string;
+    installationId: string;
+    environmentId: string;
+    revision: number;
+    outcome: DeliveryRemoteOutcome;
+}
+export interface DeliveryAttention {
+    code: string;
+    retryable: boolean;
+}
+export declare const isTerminalDeliveryOutcome: (outcome: DeliveryRemoteOutcome) => boolean;
+/** No timestamps/arrival order: a delayed callback cannot undo a server fact. */
+export declare function mergeDeliveryObservation(current: DeliveryObservation | undefined, next: DeliveryObservation, expected: Pick<DeliveryObservation, 'deliveryId' | 'messageId' | 'conversationId'> & Partial<Pick<DeliveryObservation, 'installationId' | 'environmentId'>>): DeliveryObservation | undefined;
+/** Compatibility only; domain state (interaction/agent execution) stays separate. */
+export declare function projectDeliveryStatus(outcome: DeliveryRemoteOutcome, phase: DeliveryExecutionPhase): 'pending' | 'sending' | 'succeeded' | 'cancelled' | 'rejected';

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

@@ -0,0 +1,6 @@
+/** Matches the header line of a PEM private-key block. */
+export declare const PRIVATE_KEY_BLOCK: RegExp;
+/** True when a diff file path (or rename source) matches the sensitive list. */
+export declare function isSensitiveDiffPath(path: string): boolean;
+/** Replace high-confidence credential shapes inside hunk text with `[redacted]`. */
+export declare function redactSecretTokens(text: string): string;

package/dist/internal/backend-contracts/endpoint-unread.d.ts

@@ -0,0 +1,4 @@
+/** Metadata-only unread projection, shared by serving and the offline migration. */
+export declare function computeEndpointUnreadProjection(principalId: string, conversation: Record<string, unknown> | undefined, member: Record<string, unknown> | undefined): {
+    unmutedAtMs: number;
+} | null;

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

@@ -0,0 +1,103 @@
+import { type PreparedContent } from './preparedContent.js';
+/** Plaintext endpoint protocol. Identity and authority come from authenticated transport. */
+export declare const CANON_ENDPOINT_PROTOCOL: "canon.endpoint.v1";
+export interface EndpointPreconditions {
+    conversationId?: string;
+    membershipRevision?: number;
+    admissionId?: string;
+    targetAdmissionId?: string;
+}
+export interface EndpointOperationRequest {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    operationId: string;
+    installationId: string;
+    action: string;
+    /** Agent ownership generation selected when authored; absent for humans. */
+    ownershipVersion?: number;
+    envelope?: Record<string, unknown>;
+    preconditions?: EndpointPreconditions;
+    body: {
+        encoding: 'json';
+        value: Record<string, unknown>;
+    };
+    /** Additive sealed submission, sent only after capability negotiation. */
+    preparedContent?: PreparedContent;
+}
+export interface EndpointOperationError {
+    code: string;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+    retryAfterMs?: number;
+}
+export type EndpointReceiptStatus = 'pending' | 'succeeded' | 'rejected' | 'uncertain';
+export type EndpointResultReference = {
+    kind: 'artifact_asset';
+    conversationId: string;
+    artifactId: string;
+    assetId: string;
+} | {
+    kind: 'interaction';
+    conversationId: string;
+    interactionKind: 'input' | 'approval' | 'card' | 'plan';
+    requestId: string;
+    operationKey: string;
+} | {
+    kind: 'upload';
+    uploadId: string;
+} | {
+    kind: 'media_delivery';
+    deliveryId: string;
+    installationId: string;
+} | {
+    kind: 'voice';
+    conversationId: string;
+    sessionId: string;
+};
+export interface EndpointOperationReceipt<T = unknown> {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    operationId: string;
+    installationId: string;
+    action: string;
+    status: EndpointReceiptStatus;
+    result?: T;
+    /** Sensitive/bearer results are hydrated for the response, never journaled. */
+    resultReference?: EndpointResultReference;
+    /** Transient hydration failure: the durable mutation remains succeeded. */
+    resultError?: EndpointOperationError;
+    error?: EndpointOperationError;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EndpointQueryRequest {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    query: string;
+    parameters: Record<string, unknown>;
+}
+export interface EndpointQueryResponse<T = unknown> {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    result: T;
+}
+/** Durable application cursors differ from the live transport's reconnect token. */
+export interface EndpointEvent {
+    id: string;
+    kind: string;
+    conversationId?: string;
+    revision?: number;
+    cursor?: string;
+    durable: boolean;
+    data: Record<string, unknown>;
+}
+export interface EndpointCapabilities {
+    preparedContentVersion?: 1;
+    preparedMediaContentVersion?: 1;
+    mediaDeliveryObservationVersion?: 2;
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    actions: string[];
+    queries: string[];
+    maintenance: boolean;
+}
+export declare const ENDPOINT_ID_PATTERN: RegExp;
+export declare const ENDPOINT_ACTION_PATTERN: RegExp;
+export declare function isEndpointOperationRequest(value: unknown): value is EndpointOperationRequest;
+export declare function isEndpointOperationReceipt(value: unknown): value is EndpointOperationReceipt;

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

@@ -0,0 +1,37 @@
+/** Classification, not confidentiality: every enabled endpoint codec is JSON.
+ * Unknown fields are private content, including inside an `envelope`. Adding a
+ * lane requires review; adding content to an existing schema does not make it
+ * public. These definitions refer to existing payload schemas, not copies. */
+export type EndpointContentClass = 'public-metadata' | 'private-content' | 'restricted-secret';
+export type EndpointContentLane = 'operation.request' | 'operation.receipt' | 'query.request' | 'query.result' | 'ephemeral.request' | 'ephemeral.result' | 'event';
+/** ID-only operations can still mutate encrypted semantics. These require an
+ * authenticated encrypted protocol before they can operate on a protected room.
+ * Their routing fields remain public metadata; classification is not authority. */
+export declare const MLS_DEV_UNSUPPORTED_CONTENT_ACTIONS: readonly ["delete_message", "forward_message"];
+export declare const ENDPOINT_CONTENT_ACTIONS: readonly ["mls_application", "mls_group_control", "initialize_endpoint", "append_artifact_command", "retain_artifact_asset", "sync_phone_contacts", "request_work_session", "resolve_work_session_request", "update_agent_behavior_policy", "update_conversation_agent_behavior_policy", "send_message", "delete_message", "forward_message", "react", "verb_execute", "send_contextual_message", "create_interaction", "consume_interaction", "start_conversation", "create_conversation", "add_member", "remove_member", "leave_conversation", "update_member_role", "update_conversation", "rename_conversation", "update_topic", "update_group_avatar", "mark_read", "cancel_queued_message", "set_conversation_preferences", "set_block", "save_contact", "remove_contact", "respond_interaction", "session_control", "approve_contact_request", "reject_contact_request", "cancel_direct_request", "update_message_disposition", "create_upload", "finalize_upload", "delete_upload", "retry_video_processing", "stage_media_message", "cancel_media_message", "renew_media_message_upload", "finalize_memo_stream", "abort_memo_stream", "create_voice_session", "join_voice_session", "decline_voice_session", "end_voice_session", "consume_runtime_signal", "consume_runtime_primitive", "generate_image"];
+export declare const ENDPOINT_CONTENT_FUNCTION_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_work_session_catalog", "get_work_session_details", "get_work_session_request", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status"];
+export declare const ENDPOINT_CONTENT_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "get_work_session_catalog", "get_work_session_details", "get_work_session_request", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_media_message", "get_voice_session", "get_image_generation", "get_image_generation_status", "admit_messages"];
+export declare const ENDPOINT_CONTENT_EPHEMERALS: readonly ["create_memo_stream", "publish_presence", "publish_typing", "publish_streaming", "publish_turn", "publish_runtime_status", "publish_session_state", "publish_runtime_info", "publish_runtime_activity", "append_memo_chunk"];
+export declare const ENDPOINT_CONTENT_EPHEMERAL_FAMILIES: readonly ["typing", "streaming", "turn-state", "agent-session", "runtime-card-state", "memo-streams", "runtime-info", "runtime-activity", "runtime-suppression", "runtime-silence", "runtime-attention", "call-attention", "agent-runtime", "presence"];
+export declare const ENDPOINT_CONTENT_EVENTS: readonly ["connected", "heartbeat", "agent.context", "replay.expired", "error", "participation.suppressed", "artifact.changed", "message.created", "message.snapshot", "message.updated", "message.deleted", "message.media_terminal", "conversation.updated", "conversation.changed", "conversation.removed", "conversations.changed", "contacts.changed", "contact.added", "contact.updated", "contact.removed", "presence", "typing", "runtime.updated", "runtime.control", "turn.updated", "voice.session.started", "voice.session.ended", ...string[]];
+export declare class EndpointContentPolicyError extends Error {
+    readonly code = "ENDPOINT_CONTENT_UNCLASSIFIED";
+    constructor(lane: string, name: string);
+}
+export interface EndpointContentBoundary {
+    readonly lane: EndpointContentLane;
+    readonly name: string;
+    readonly defaultClass: 'private-content';
+    /** Paths address the actual payload. Query/result/event paths are relative to
+     * their parameters/result/data; operation paths include body.value. */
+    classify(path: readonly string[]): EndpointContentClass;
+}
+/** Local journal policy is separate from wire classification. Input answers and
+ * card values can carry passwords even when the response omits the original
+ * request's secret/sudo/field metadata. Only reviewed response shapes without
+ * those value bags may be retried from durable storage. Unknown response fields
+ * fail closed; a caller's `sensitive: false` cannot weaken this policy. */
+export declare function endpointOperationRequestRetention(action: string, body: Record<string, unknown>, envelope?: Record<string, unknown>): 'journal' | 'memory';
+/** Validate the lane before accepting/transmitting its payload. No body values
+ * are logged, copied into metadata, or claimed to be encrypted by this API. */
+export declare function endpointContentBoundary(lane: EndpointContentLane, name: string, payload?: unknown): EndpointContentBoundary;

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

@@ -0,0 +1,20 @@
+export declare const CANON_ENVIRONMENT_CONTRACTS: Readonly<{
+    readonly 'canon-dev-v1': Readonly<{
+        name: "dev";
+        projectId: "canonmail-dev";
+        region: "europe-west1";
+    }>;
+    readonly 'canon-prod-v1': Readonly<{
+        name: "prod";
+        projectId: "canonmail-prod";
+        region: "europe-west1";
+    }>;
+}>;
+export type CanonEnvironmentId = keyof typeof CANON_ENVIRONMENT_CONTRACTS;
+export type CanonEnvironmentName = (typeof CANON_ENVIRONMENT_CONTRACTS)[CanonEnvironmentId]['name'];
+export type CanonEnvironmentContract = {
+    [EnvironmentId in CanonEnvironmentId]: {
+        environmentId: EnvironmentId;
+    } & (typeof CANON_ENVIRONMENT_CONTRACTS)[EnvironmentId];
+}[CanonEnvironmentId];
+export declare function getCanonEnvironmentContract(value: string): CanonEnvironmentContract;

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

@@ -0,0 +1,24 @@
+/** A durable acceptance boundary for an episodic, externally hosted consumer.
+ * Replaying a claim reconciles an unknown response; it never authorizes a second run. */
+export interface EndpointExternalInboundClaimResult {
+    inputId: string;
+    requestId: string;
+    status: 'claimed' | 'replayed' | 'unavailable';
+    runAllowed: boolean;
+    state?: 'uncertain' | 'settled';
+}
+export type EndpointExternalInboundOutcome = 'completed' | 'no_reply';
+export interface EndpointExternalInboundSource {
+    conversationId: string;
+    messageId: string;
+    admissionId: string | null;
+}
+export interface EndpointExternalInboundReplyIntent {
+    fingerprint: string;
+    messageId: string;
+    turnId: string;
+}
+/** Closed communication view for delegated consumers. The stream's private
+ * memory/policy envelope may evolve without expanding an OAuth grant. Nested
+ * message bodies and metadata are already public conversation content. */
+export declare function projectExternalInboundContext(data: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,9 @@
+/** Trimmed string, or null when absent/empty. */
+export declare function normalizeStoredString(value: unknown): string | null;
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` keeps its own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+export declare function firestoreTimestampToISOString(value: unknown): string | null;

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

@@ -0,0 +1,48 @@
+export * from './diffRedaction.js';
+export * from './environment.js';
+export * from './api-origins.generated.js';
+export * from './media.js';
+export * from './mediaDelivery.js';
+export * from './media-url.js';
+export * from './message.js';
+export * from './messageText.js';
+export * from './runtimeCardFields.js';
+export * from './runtimeCardStorage.js';
+export * from './turnProtocol.js';
+export * from './agentBehaviorPolicy.js';
+export * from './agentSearch.js';
+export * from './agentDirectory.js';
+export * from './agentOrigin.js';
+export * from './verbContract.js';
+export * from './verbSchemas.js';
+export * from './verbWire.js';
+export * from './communication.js';
+export * from './apiErrors.js';
+export * from './firestoreValues.js';
+export * from './moderation.js';
+export * from './selfContext.js';
+export * from './replyAuthority.js';
+export * from './runtimeDescriptor.js';
+export * from './workSessions.js';
+export type { WebPhoneAccountRequest, WebPhoneTokenResponse } from './webAuth.js';
+export * from './conversationMembership.js';
+export * from './endpoint.js';
+export * from './externalInbound.js';
+export * from './endpointContentPolicy.js';
+export * from './plaintextProcessors.js';
+export { computeEndpointUnreadProjection } from './endpoint-unread.js';
+export * from './membershipChange.js';
+export * from './deliveryObservation.js';
+export * from './mediaTransferProtocol.js';
+export * from './preparedContent.js';
+export * from './artifacts.js';
+export * from './artifactActions.js';
+export * from './mlsDevEnrollment.js';
+export * from './mlsDevCredential.js';
+export * from './mlsDevCredentialReconciliation.js';
+export * from './mlsDevDeviceCustody.js';
+export * from './mlsDevKeyPackage.js';
+export * from './mlsDevKeyPackages.js';
+export * from './mlsDevGroup.js';
+export * from './mlsDevApplication.js';
+export * from './mlsDevGroupFeed.js';

package/dist/internal/backend-contracts/media-url.d.ts

@@ -0,0 +1,6 @@
+export declare function buildFirebaseMediaUrl(bucket: string, storagePath: string, token: string): string;
+export declare function buildMediaDownloadUrl(bucket: string, storagePath: string, token: string): string;
+/** Accept historical Firebase URLs and Canon links, only for the expected bucket. */
+export declare function parseMediaStoragePath(value: unknown, bucket: string): string | null;
+/** Presentation upgrade for existing messages without rewriting their stored URLs. */
+export declare function canonMediaDownloadUrl(value: string, downloadFileName?: string): string;

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

@@ -0,0 +1,51 @@
+export type MediaAttachmentKind = 'image' | 'audio' | 'video' | 'file';
+/** Allow private conditional caching, but recheck access before every reuse. */
+export declare const MEDIA_CACHE_CONTROL = "private, max-age=0, must-revalidate";
+/** Preserve Unicode and the extension while removing unsafe filesystem characters. */
+export declare function sanitizeDownloadFileName(value: unknown, fallback?: string): string;
+/** RFC 6266: readable ASCII fallback plus the exact UTF-8 filename. */
+export declare function buildMediaContentDisposition(input: {
+    fileName?: unknown;
+    fallbackFileName: string;
+    disposition?: 'inline' | 'attachment';
+}): string;
+/** The processor changes the container to MP4; keep its name consistent everywhere. */
+export declare function processedVideoFileName(value: unknown): string;
+/** Lifecycle for newly uploaded videos that are normalized server-side. */
+export type VideoProcessingStatus = 'processing' | 'ready' | 'failed';
+/** Stable, display-safe reasons for a terminal video processing failure. */
+export type VideoProcessingErrorCode = 'invalid_video' | 'video_limits_exceeded' | 'video_processing_failed';
+export interface MediaAttachment {
+    kind: MediaAttachmentKind;
+    url: string;
+    /**
+     * Server-issued identity for a finalized upload. The send path
+     * uses this to retain temporary canonical media atomically with the message.
+     * Older attachments and forwarded copies may omit it.
+     */
+    uploadId?: string;
+    mimeType?: string;
+    fileName?: string;
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    /** Server-generated poster for a normalized video. */
+    thumbnailUrl?: string;
+    /** Missing means a legacy attachment that is immediately playable. */
+    processingStatus?: VideoProcessingStatus;
+    processingErrorCode?: VideoProcessingErrorCode;
+}
+export declare function inferMediaAttachmentKind(mimeType: string): MediaAttachmentKind;
+export declare function getStoredFileExtension(input: {
+    mimeType?: string | null;
+    fileName?: string | null;
+}): string;
+export declare function normalizeStoredAttachments(value: unknown): MediaAttachment[] | null;
+export declare function getMessageAttachments(input: {
+    attachments?: unknown;
+}): MediaAttachment[];
+export declare function getPrimaryAttachment(input: {
+    attachments?: unknown;
+}): MediaAttachment | null;
+export declare function describeAttachment(attachment: MediaAttachment | null | undefined): string | null;

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

@@ -0,0 +1,46 @@
+import type { PreparedContent } from './preparedContent.js';
+/** A background transfer remains one message even when its files finish separately. */
+export interface MediaDeliveryFileDescriptor {
+    fileId: string;
+    kind: 'image' | 'video' | 'audio' | 'file';
+    mimeType: string;
+    fileName?: string;
+    sizeBytes: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+}
+export interface StageMediaMessageBody {
+    /** Capability-gated JSON preparation; absent records settle by their original contract. */
+    contentVersion?: 1;
+    preparedContent?: PreparedContent;
+    conversationId: string;
+    messageId: string;
+    /** Original send_message body, excluding attachments. The server binds IDs. */
+    message: Record<string, unknown>;
+    /** Array order is the eventual message attachment order. */
+    files: MediaDeliveryFileDescriptor[];
+}
+export type MediaDeliveryStatus = 'pending' | 'published' | 'cancelled' | 'expired' | 'rejected';
+export interface MediaDeliveryFileSession {
+    fileId: string;
+    uploadId: string;
+    generation: number;
+    status: 'pending' | 'accepted';
+    /** Restricted bearer material, never persisted in an endpoint receipt. */
+    uploadUrl?: string;
+    expiresAt?: string;
+}
+export interface MediaDeliverySnapshot {
+    /** Semantic ordering, independent of callback arrival or device clocks. */
+    revision?: number;
+    schemaVersion?: 2;
+    conversationId?: string;
+    installationId?: string;
+    environmentId?: string;
+    deliveryId: string;
+    messageId: string;
+    status: MediaDeliveryStatus;
+    expiresAt: string;
+    files: MediaDeliveryFileSession[];
+}

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

@@ -0,0 +1,17 @@
+export type TransferReceiptDecision = 'result' | 'pending' | 'uncertain' | 'rejected' | 'invalid';
+export interface TransferReceiptIdentity {
+    protocol: string;
+    operationId: string;
+    installationId: string;
+    action: string;
+}
+/** A transport failure is local attention, never a remote delivery outcome. */
+export declare function classifyTransferHttpFailure(status: number): 'retry' | 'attention';
+/** A successful mutation with failed restricted-result hydration is still
+ * unresolved locally. Never translate an operation rejection into a delivery outcome. */
+export declare function classifyTransferReceipt(value: unknown, expected: TransferReceiptIdentity): TransferReceiptDecision;
+/** Shared native recovery policy. Random is injected so all implementations run
+ * the same fixture corpus; a longer server retry hint is never truncated. */
+export declare function transferRetryDelay(attempt: number, random: number, retryAfterMs?: number): number;
+/** Expiry bounds automatic work, not the ability to reconcile an unknown result. */
+export declare function mayAttemptMediaTransfer(nowMs: number, createdAtMs: number, expiresAtMs?: number | null): boolean;

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

@@ -0,0 +1,21 @@
+/** A server-written membership transition stored in the ordinary chat history. */
+export interface MembershipChangeMetadata extends Record<string, unknown> {
+    type: 'membership_change';
+    action: 'added' | 'removed' | 'left';
+    actorId: string | null;
+    actorName: string | null;
+    memberId: string | null;
+    memberName: string;
+    membershipRevision: number;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+/** Recognize the reserved marker even when the remaining metadata is malformed. */
+export declare function isMembershipChangeMessage(message: {
+    metadata?: unknown;
+}): boolean;
+/** Membership revisions own these document IDs; user messages cannot claim them. */
+export declare function isMembershipChangeMessageId(messageId: unknown): boolean;
+export declare function readMembershipChangeMetadata(metadata: unknown): MembershipChangeMetadata | null;
+/** Uses stored names so the notice remains readable after a profile leaves the roster. */
+export declare function formatMembershipChangeNotice(metadata: MembershipChangeMetadata, currentUserId?: string): string;

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

@@ -0,0 +1,86 @@
+import { MediaAttachment } from './media.js';
+import { type MlsDevMessageReference } from './mlsDevApplication.js';
+export type SerializedSenderType = 'human' | 'ai_agent';
+/** Canonical agent client identifiers shared by Canon services and clients. */
+export declare const AGENT_CLIENT_TYPES: readonly ["claude-code", "openclaw", "codex", "hermes", "deepseek-harness", "generic"];
+export type SerializedAgentClientType = typeof AGENT_CLIENT_TYPES[number];
+export type SerializedContentType = 'text' | 'image' | 'audio' | 'video' | 'file' | 'contact_card' | 'interaction';
+export interface ForwardedFrom {
+    sourceConversationId: string;
+    messageId: string;
+}
+export type SerializedReactions = Record<string, string[]>;
+export interface SerializedContactCard {
+    userId: string;
+    canonContactId?: string;
+    displayName: string;
+    avatarUrl: string | null;
+    userType: SerializedSenderType;
+    clientType?: SerializedAgentClientType;
+    about?: string;
+    isActive?: boolean;
+    ownerId?: string;
+    ownerName?: string;
+    lifecycleState?: string;
+}
+export interface SerializedMessage {
+    /** Public encrypted-message hint; content is read only from the authenticated MLS feed. */
+    mls?: MlsDevMessageReference;
+    id: string;
+    senderId: string;
+    senderName?: string;
+    senderType: SerializedSenderType;
+    isOwner: boolean;
+    contentType: SerializedContentType;
+    text: string | null;
+    attachments: MediaAttachment[];
+    mentions: string[];
+    replyTo: string | null;
+    replyToPosition: number | null;
+    forwarded?: boolean;
+    forwardedFrom?: ForwardedFrom;
+    status: 'sent' | 'read';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+    contactCard?: SerializedContactCard;
+    /** Durable canon.card.v1 runtime card content, passed through opaquely. */
+    runtimeCard?: Record<string, unknown>;
+    /**
+     * Plaintext, server-authorized interaction envelope for `contentType:
+     * 'interaction'` messages (card / input / approval / plan / contact). The
+     * authorization contract (`response`) and preview live here; the opaque
+     * request payload rides in `body`.
+     */
+    interaction?: SerializedInteraction;
+    /** Opaque interaction payload (JSON string or ciphertext); never parsed here. */
+    body?: string;
+    reactions?: SerializedReactions;
+}
+export type SerializedInteractionKind = 'contact' | 'approval' | 'input' | 'plan' | 'card';
+export interface SerializedInteraction {
+    kind: SerializedInteractionKind;
+    requestId: string;
+    interactive: boolean;
+    responseUserId?: string;
+    expiresAt?: string;
+    schemaVersion?: string;
+    preview?: {
+        title?: string;
+        blockKinds?: string[];
+    };
+    response?: {
+        actionIds?: string[];
+        actionFields?: Record<string, unknown>;
+        questions?: Array<{
+            id: string;
+            sensitive?: boolean;
+        }>;
+    };
+}
+export interface SerializeMessageInput {
+    id: string;
+    data: Record<string, unknown>;
+    senderName?: string;
+    isOwner: boolean;
+}
+export declare function serializeStoredMessage(input: SerializeMessageInput): SerializedMessage;

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

@@ -0,0 +1,6 @@
+/** Maximum UTF-8 payload size for a human-authored message. */
+export declare const HUMAN_MESSAGE_TEXT_MAX_BYTES: number;
+/** Returns the encoded UTF-8 size used by the message API. */
+export declare function messageTextUtf8ByteLength(value: string): number;
+/** Whether human-authored message text fits the API's UTF-8 byte budget. */
+export declare function isHumanMessageTextWithinLimit(value: string): boolean;

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

@@ -0,0 +1,73 @@
+import { type MlsDevGroupHead } from './mlsDevGroup.js';
+export declare const MLS_DEV_TEXT_PROTOCOL: "canon.mls.dev-text.v1";
+export declare const MLS_DEV_APPLICATION_TLS_MAX_BYTES: number;
+export declare const MLS_DEV_APPLICATION_MAX_BYTES: number;
+export declare const MLS_DEV_TEXT_MAX_BYTES: number;
+export interface MlsDevApplicationPreconditions {
+    readonly membershipRevision: number;
+    readonly admissionId: string;
+}
+export interface MlsDevApplicationBinding {
+    readonly version: 1;
+    readonly environmentId: 'canon-dev-v1';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly senderCredential: string;
+    readonly expectedHead: MlsDevGroupHead;
+    readonly preconditions: MlsDevApplicationPreconditions;
+}
+export interface MlsDevApplicationUnsignedEnvelope extends MlsDevApplicationBinding {
+    readonly ciphertext: string;
+}
+export interface MlsDevApplicationEnvelope extends MlsDevApplicationUnsignedEnvelope {
+    readonly proof: string;
+}
+export interface MlsDevApplicationReceipt {
+    readonly version: 1;
+    readonly authorization: 'encrypted_text_only';
+    readonly operationId: string;
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly feedOrdinal: number;
+    readonly head: MlsDevGroupHead;
+    readonly acceptedAtMs: number;
+    readonly envelopeHash: string;
+}
+export interface MlsDevTextPayload {
+    readonly version: 1;
+    readonly kind: 'text';
+    readonly conversationId: string;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly senderDeviceId: string;
+    readonly text: string;
+}
+/** Public projection only. Plaintext is produced locally after authenticated MLS receive. */
+export interface MlsDevMessageReference {
+    readonly version: 1;
+    readonly protocol: typeof MLS_DEV_TEXT_PROTOCOL;
+    readonly groupId: string;
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly feedOrdinal: number;
+    readonly head: MlsDevGroupHead;
+    readonly envelopeHash: string;
+}
+export declare class MlsDevApplicationValidationError extends Error {
+    readonly code = "INVALID_MLS_DEV_APPLICATION";
+    constructor();
+}
+export declare function parseMlsDevApplicationWire(value: unknown): string;
+export declare function parseMlsDevApplicationPreconditions(value: unknown): MlsDevApplicationPreconditions;
+export declare function parseMlsDevApplicationBinding(value: unknown): MlsDevApplicationBinding;
+export declare function parseMlsDevApplicationUnsignedEnvelope(value: unknown): MlsDevApplicationUnsignedEnvelope;
+export declare function parseMlsDevApplicationEnvelope(value: unknown): MlsDevApplicationEnvelope;
+export declare function parseMlsDevApplicationReceipt(value: unknown): MlsDevApplicationReceipt;
+export declare function parseMlsDevTextPayload(value: unknown): MlsDevTextPayload;
+export declare function parseMlsDevMessageReference(value: unknown): MlsDevMessageReference;
+export declare function encodeMlsDevApplicationProof(value: unknown, operationId: string): Uint8Array;
+export declare function encodeMlsDevApplicationEnvelopeHash(value: unknown, operationId: string): Uint8Array;
+export declare function encodeMlsDevApplicationAad(value: unknown, operationId: string): Uint8Array;