@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,179 @@
+/**
+ * The class-C relay (docs/design/agent-runner.md §11): a Canon-operated process that relays a connector agent's
+ * encrypted rooms, holding an MLS device for the agent and decrypting and re-encrypting messages for the assistant (which
+ * its provider runs, not Canon), so those rooms are not end-to-end encrypted to that agent. Its installation id carries a
+ * reserved prefix, which the device's registration shows, and with it every MLS credential the issuer signs and every
+ * room roster: that is the machine-readable marker that a member is relayed. Only the agent's owner-approved relay
+ * installation may be enrolled under the prefix, and only with that relay's own credential.
+ */
+export declare const CONNECTOR_RELAY_INSTALLATION_PREFIX = "canon-relay:";
+export declare const CONNECTOR_RELAY_INSTALLATION_PATTERN: RegExp;
+export declare function isConnectorRelayInstallation(installationId: unknown): boolean;
+/**
+ * Canon's per-relay credential (§11.4): minted when the owner approves (or re-approves) the relay and delivered once, over
+ * the channel, to that agent's relay alone; Canon keeps only its SHA-256, on the agent's relay binding. It authenticates
+ * the relay as its agent for the relay's own work only: its installation's endpoint operations and MLS device, and the
+ * encrypted rooms' live hints. It is never accepted for plaintext rooms or any other route, and it stops working when the
+ * relay is disabled or re-approved, its connection is revoked, replaced or expires, or the agent's ownership changes.
+ */
+export declare const CONNECTOR_RELAY_CREDENTIAL_PREFIX = "canon_relay_";
+export declare const CONNECTOR_RELAY_CREDENTIAL_PATTERN: RegExp;
+export declare function isConnectorRelayCredential(value: unknown): value is string;
+/** What the channel's `credential` operation carries; the connection is the request's `grantId`. */
+export interface ConnectorRelayCredentialDelivery {
+    installationId: string;
+    generation: number;
+    credential: string;
+}
+/**
+ * A relay binding is current for `installationId` (and, given one, the credential with that hash): the agent is active,
+ * not mid-transfer, and still at the binding's ownership generation; its connection's grant is active, unexpired, for the
+ * same agent, owner and generation; neither agent nor owner is ejected. Functions and the stream service read the same
+ * documents (`users/{agentId}`, the binding's `connectorGrants/{grantId}`) and decide with this one rule.
+ */
+export declare function isConnectorRelayBindingCurrent(input: {
+    agentId: string;
+    installationId: string;
+    ownershipVersion?: number;
+    credentialDigest?: string;
+    agent: Record<string, any> | undefined;
+    grant: Record<string, any> | undefined;
+    agentEjected: boolean;
+    ownerEjected: boolean;
+    now: number;
+}): boolean;
+/** A relayed turn as the connector's pickup tools name it: never reused, and it names nothing about the turn. */
+export declare const CONNECTOR_RELAY_INPUT_ID_PATTERN: RegExp;
+export declare const CONNECTOR_RELAY_MAX_BODY_BYTES: number;
+/** An encrypted room's text is one message of at most 32 KiB. */
+export declare const CONNECTOR_RELAY_MAX_TEXT_BYTES: number;
+/**
+ * The one budget for a relay answer, serialized: Functions refuses a longer response body, and the relay fits every answer
+ * under it before it changes any state (a claim's input is fitted before the claim is taken, a history page is cut short).
+ */
+export declare const CONNECTOR_RELAY_MAX_RESPONSE_BYTES: number;
+/** Functions' deadline for one exchange with the relay, request to last response byte. */
+export declare const CONNECTOR_RELAY_CHANNEL_TIMEOUT_MS = 10000;
+/**
+ * The relay answers every exchange within this, measured from the request's arrival, leaving the rest of Functions'
+ * deadline for the network. Work that may outlast it answers before it changes state (a busy refusal) or after it is
+ * durable (a send answers `pending` only once it is journaled).
+ */
+export declare const CONNECTOR_RELAY_ANSWER_WITHIN_MS = 7000;
+/** A value's size as the channel serializes it (UTF-8 JSON). */
+export declare function connectorRelayResponseBytes(value: unknown): number;
+export type ConnectorRelaySettleOutcome = 'completed' | 'no_reply' | 'failed';
+/** One request from Functions to the relay; Functions initiates every exchange (§11.6). */
+export type ConnectorRelayRequest = {
+    version: 1;
+    agentId: string;
+    grantId: string;
+} & ({
+    op: 'pending';
+    args: {
+        conversationId: string;
+        limit?: number;
+    };
+} | {
+    op: 'claim';
+    args: {
+        inputId: string;
+        requestId: string;
+    };
+} | {
+    op: 'reply';
+    args: {
+        inputId: string;
+        requestId: string;
+        text: string;
+    };
+} | {
+    op: 'settle';
+    args: {
+        inputId: string;
+        requestId: string;
+        outcome: ConnectorRelaySettleOutcome;
+    };
+} | {
+    op: 'read';
+    args: {
+        conversationId: string;
+        limit?: number;
+        before?: string;
+    };
+} | {
+    op: 'send';
+    args: {
+        conversationId: string;
+        messageId: string;
+        text: string;
+    };
+} | {
+    op: 'credential';
+    args: ConnectorRelayCredentialDelivery;
+});
+export type ConnectorRelayOp = ConnectorRelayRequest['op'];
+export interface ConnectorRelayInputRef {
+    inputId: string;
+    conversationId: string;
+    messageId: string;
+    createdAt: string;
+}
+export interface ConnectorRelayMessage {
+    id: string;
+    senderId: string;
+    senderName?: string;
+    senderType: 'human' | 'ai_agent';
+    isOwner?: boolean;
+    text: string;
+    createdAt: string;
+}
+/**
+ * What the assistant gets with its first claim: the turn's messages and, for context, the history window before them,
+ * each once (structured, as the plaintext connector's claim is; no rendered prompt repeats them). History is trimmed,
+ * oldest first, to fit the response budget; the turn's own messages always fit.
+ */
+export interface ConnectorRelayInput {
+    conversationId: string;
+    room: 'direct' | 'group';
+    sender: {
+        id: string;
+        name?: string;
+        type: 'human' | 'ai_agent';
+        isOwner: boolean;
+    };
+    messages: ConnectorRelayMessage[];
+    history: ConnectorRelayMessage[];
+}
+export interface ConnectorRelayClaim {
+    inputId: string;
+    requestId: string;
+    runAllowed: boolean;
+    state: 'claimed' | 'answered' | 'withdrawn';
+    input?: ConnectorRelayInput;
+}
+export interface ConnectorRelayAck {
+    inputId: string;
+    state: 'accepted';
+    outcome: 'reply' | ConnectorRelaySettleOutcome;
+}
+/** Messages Canon accepted into the room's feed, newest first; the relay's own unaccepted sends are not history. */
+export interface ConnectorRelayPage {
+    messages: ConnectorRelayMessage[];
+    nextBefore: string | null;
+}
+/**
+ * `messageId` is the send's identity: sending again with it (or with the id the caller first gave) is the same message,
+ * never a second one. `historyMessageId` is the id the message has in the conversation's history.
+ */
+export interface ConnectorRelaySent {
+    conversationId: string;
+    messageId: string;
+    historyMessageId: string;
+    status: 'sent' | 'pending';
+}
+export declare class ConnectorRelayRequestError extends Error {
+    name: string;
+}
+/** The closed request schema both sides check: Functions before it signs, the relay after it verifies the signature. */
+export declare function parseConnectorRelayRequest(value: unknown): ConnectorRelayRequest;

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,120 @@
+import { type PreparedContent } from './preparedContent.js';
+import type { MlsPrincipalOpening } from './mlsPrincipalAlias.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;
+    /** Only for a principal eligible for MLS here: how new rooms are born (functions `rollout.ts`, `CANON_MLS_DEV_ROOMS`). */
+    mls?: {
+        eligible: true;
+        roomMode: 'allowlist' | 'eligible' | 'default';
+        /** The principal's MLS identity, its alias (mls-dev-groups.md, erasure privacy), and the opening that proves the alias
+         * is its own; null until it has an alias, when the account is its own principal. Absent from older servers. */
+        principal?: {
+            type: 'human' | 'ai_agent';
+            id: string;
+        };
+        opening?: MlsPrincipalOpening | null;
+    };
+    /** While a client floor exists (`clientFloor.ts`): the minimum for the caller's kind, or null when it has none. */
+    clientFloor?: {
+        minimum: string | null;
+    };
+}
+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,48 @@
+/** 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 ["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", "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", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "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", "same_owner_agents"];
+export declare const ENDPOINT_CONTENT_QUERIES: readonly ["mls_group_feed", "mls_group_controls", "mls_group_admissions", "mls_interactions", "list_artifacts", "get_artifact_log", "get_artifact_asset", "discover_agents", "get_unread_summary", "peek_runtime_signal", "list_runtime_primitives", "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", "same_owner_agents", "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);
+}
+/**
+ * An encrypted room's content-free turn state (owner ruling 2026-10-16; agent-runner.md §6): Canon learns when an agent
+ * is busy there, never what it does. On `publish_turn` a closed state (`thinking` while the agent works, `waiting_input`
+ * while a card waits on a person, `interrupted`, `idle`), the runner's random turn id and two times are public metadata,
+ * each only with such a value; queue depth, speaker, active messages, capabilities, `streaming`/`tool` and anything else
+ * stay private, so an encrypted room refuses them.
+ */
+export declare const ENDPOINT_TURN_PRESENCE_STATES: readonly ["thinking", "waiting_input", "interrupted", "idle"];
+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;
+/** Whether every leaf of an ephemeral body is public metadata: all an encrypted (MLS) room may receive on that lane. The
+ * endpoint applies this before publishing (its MLS preflight); Functions applies it again on receipt. */
+export declare function endpointEphemeralIsMetadataOnly(name: string, body: unknown): boolean;

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,54 @@
+export * from './diffRedaction.js';
+export * from './environment.js';
+export * from './clientFloor.js';
+export * from './api-origins.generated.js';
+export * from './media.js';
+export * from './mediaDelivery.js';
+export * from './media-url.js';
+export * from './upload-mime-types.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 type { WebPhoneAccountRequest, WebPhoneTokenResponse } from './webAuth.js';
+export * from './conversationMembership.js';
+export * from './endpoint.js';
+export * from './externalInbound.js';
+export * from './connectorRelay.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 './mlsEnvironment.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';
+export * from './mlsDevFeedReceipt.js';
+export * from './mlsDevInteraction.js';
+export * from './mlsPrincipalAlias.js';

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

@@ -0,0 +1,20 @@
+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;
+/** Whether `url` is on one of Canon's media origins (its `/files` download links). */
+export declare function isCanonMediaOrigin(url: string): boolean;
+/**
+ * Whether `url` is Canon's own download link for one upload of this room in this environment: its media origin, the
+ * room's object path, the upload's canonical file (or, with `poster`, its video poster) and a bearer token, nothing
+ * else. An encrypted item names its upload by such a link (mls-payload-v3.md §4); any other URL would have every
+ * member's phone and agent fetch it.
+ */
+export declare function isCanonUploadUrl(url: string, input: {
+    environmentId: string;
+    conversationId: string;
+    uploadId: string;
+    poster?: boolean;
+}): boolean;
+/** 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[];
+}