@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,23 @@
+import { type MlsEnvironmentId } from './mlsEnvironment.js';
+export declare const MLS_PRINCIPAL_ALIAS_PREFIX = "mlsa_";
+export interface MlsPrincipalOpening {
+    readonly type: 'human' | 'ai_agent';
+    readonly accountId: string;
+    /** 32 random bytes, canonical base64url. */
+    readonly salt: string;
+}
+/** An alias's shape; whether it opens to an account needs its opening. Account IDs never have it. */
+export declare function isMlsPrincipalAlias(value: unknown): value is string;
+export declare function parseMlsPrincipalOpening(value: unknown): MlsPrincipalOpening;
+/**
+ * SHA-256 over the domain above, LP environment, u8 type (human 0/agent 1), LP account ID and the raw 32-byte salt,
+ * where LP is a u32 big-endian byte length followed by UTF-8, as in the enrollment proof.
+ */
+export declare function encodeMlsPrincipalAliasInput(environmentId: MlsEnvironmentId, opening: MlsPrincipalOpening): Uint8Array;
+export declare function mlsPrincipalAlias(environmentId: MlsEnvironmentId, opening: MlsPrincipalOpening): Promise<string>;
+/** Whether `opening` opens `alias` in this environment. A malformed opening opens nothing. */
+export declare function opensMlsPrincipalAlias(environmentId: MlsEnvironmentId, alias: string, opening: unknown): Promise<boolean>;
+/** A fresh opening for an account: Canon's server makes one the first time the account needs an alias. */
+export declare function createMlsPrincipalOpening(type: MlsPrincipalOpening['type'], id: string): MlsPrincipalOpening;
+/** A room's openings, `{[alias]: opening}`: the shape only. Readers still check each opening against its alias. */
+export declare function parseMlsRoomIdentities(value: unknown): Readonly<Record<string, MlsPrincipalOpening>>;

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

@@ -0,0 +1,7 @@
+export type ModerationStatus = 'active' | 'ejected';
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+export declare function readModerationStatus(data: unknown): ModerationStatus;

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

@@ -0,0 +1,63 @@
+/** Existing server content readers. Classification is not encryption: these
+ * processors intentionally inspect plaintext in the current JSON release.
+ * Their input boundary must be redesigned before enabling encrypted rooms. */
+export declare const PLAINTEXT_PROCESSORS: {
+    readonly preview: {
+        readonly current: "Read message/display text to derive conversation and notification previews.";
+        readonly beforeMls: "Derive on authorized endpoints; clear/reconcile deleted-message previews there.";
+    };
+    readonly push: {
+        readonly current: "Send visible titles and message previews to FCM/APNs.";
+        readonly beforeMls: "Use generic wake notifications or endpoint-decrypted notification extensions.";
+    };
+    readonly topic: {
+        readonly current: "Derive the initial topic from message text.";
+        readonly beforeMls: "Derive on an authorized endpoint and publish as encrypted conversation content.";
+    };
+    readonly forward: {
+        readonly current: "Read source content and copy plaintext attachments into the target room.";
+        readonly beforeMls: "Decrypt and re-encrypt on an authorized endpoint; keep server target admission checks.";
+    };
+    readonly message_validation: {
+        readonly current: "Inspect text, attachment descriptors and rich content before storing messages.";
+        readonly beforeMls: "Validate decrypted content on endpoints; retain bounded ciphertext/envelope checks on the server.";
+    };
+    readonly interaction_validation: {
+        readonly current: "Validate card/input/approval/plan render contracts and submitted responses.";
+        readonly beforeMls: "Validate content on authorized requesting/responding endpoints; retain public admission and lifecycle checks.";
+    };
+    readonly image_generation: {
+        readonly current: "Send prompts/source image bytes to Vertex and persist generated output.";
+        readonly beforeMls: "Require explicit provider disclosure and an authorized endpoint/processing participant; no silent server decryption.";
+    };
+    readonly media_assembly: {
+        readonly current: "Decode prepared JSON and combine ordered accepted blob descriptors into canonical publication.";
+        readonly beforeMls: "Pass an immutable encrypted envelope without interpreting or rewriting it; private blob metadata stays inside the payload.";
+    };
+    readonly streaming: {
+        readonly current: "Validate and publish plaintext live text, chunks and provisional content.";
+        readonly beforeMls: "Encrypt and validate streaming content on authorized endpoints with explicit ordering and key-epoch boundaries.";
+    };
+    readonly video_processing: {
+        readonly current: "Download plaintext video, normalize it and create a poster.";
+        readonly beforeMls: "Process on an endpoint or an explicitly authorized processing participant before encrypted upload.";
+    };
+    readonly owner_observation: {
+        readonly current: "Allow authenticated owners to inspect managed agent conversations without room membership.";
+        readonly beforeMls: "Explicitly enroll authorized owner keyholders or retire content observation; ownership alone supplies no decryption keys.";
+    };
+    readonly moderation_evidence: {
+        readonly current: "Accept user-selected plaintext message evidence for moderation.";
+        readonly beforeMls: "Design explicit selective disclosure/authenticity (including franking policy); never infer access to room keys.";
+    };
+};
+export type PlaintextProcessorName = keyof typeof PLAINTEXT_PROCESSORS;
+export interface PlaintextProcessorInput<T> {
+    encoding: 'json';
+    value: T;
+}
+/** The callback is the actual content processor, not a telemetry hook. Keeping
+ * the codec explicit ensures an opaque body cannot accidentally be processed by
+ * the JSON path. This is not authorization; callers still enforce their domain
+ * policy and every enabled transport currently requires JSON. */
+export declare function runPlaintextProcessor<T, R>(name: PlaintextProcessorName, input: PlaintextProcessorInput<T>, process: (value: T) => R): R;

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

@@ -0,0 +1,54 @@
+import { type EndpointPreconditions } from './endpoint.js';
+export declare const PREPARED_CONTENT_VERSION: 1;
+export declare const PREPARED_JSON_CODEC: "canon.json.v1";
+/** Reviewed public routing context. Authentication and installation/operation
+ * identity stay in the containing endpoint request, never in this payload. */
+export interface PreparedContentContext {
+    readonly action: string;
+    readonly conversationId?: string;
+    readonly messageId?: string;
+}
+export interface PreparedBlobDependency {
+    /** Logical identity survives replacement of a transport upload session. */
+    readonly id: string;
+    readonly index: number;
+}
+export interface PreparedContentExpected {
+    readonly installationGeneration: number;
+    readonly protocolRevision: number;
+    readonly admission?: Readonly<EndpointPreconditions>;
+}
+export interface PreparedContent {
+    readonly version: typeof PREPARED_CONTENT_VERSION;
+    readonly context: PreparedContentContext;
+    readonly codec: typeof PREPARED_JSON_CODEC;
+    /** Exact immutable bytes represented as UTF-8 JSON; transport retries reuse it. */
+    readonly payload: string;
+    readonly blobs: readonly PreparedBlobDependency[];
+    readonly expected: PreparedContentExpected;
+}
+export interface PreparedJsonInput {
+    context: PreparedContentContext;
+    body: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    blobs?: readonly PreparedBlobDependency[];
+    expected: PreparedContentExpected;
+}
+export interface DecodedPreparedJsonContent {
+    body: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+}
+export declare class PreparedContentError extends Error {
+    readonly code: 'INVALID_PREPARED_CONTENT' | 'UNSUPPORTED_PREPARED_CONTENT_VERSION' | 'UNSUPPORTED_PREPARED_CONTENT_CODEC' | 'PREPARED_CONTENT_MEMORY_ONLY';
+    constructor(code: 'INVALID_PREPARED_CONTENT' | 'UNSUPPORTED_PREPARED_CONTENT_VERSION' | 'UNSUPPORTED_PREPARED_CONTENT_CODEC' | 'PREPARED_CONTENT_MEMORY_ONLY');
+}
+/** Shared deterministic JSON after normal transport serialization. This keeps
+ * existing endpoint fingerprint semantics, including omitted undefined fields. */
+export declare function canonicalEndpointJson(value: unknown): string;
+/** Only the JSON processor may inspect this payload. It returns a fresh copy;
+ * neither decoding nor transport can mutate the sealed publication. */
+export declare function decodePreparedJsonContent(value: unknown): DecodedPreparedJsonContent;
+export declare function isPreparedContent(value: unknown): value is PreparedContent;
+export declare function prepareJsonContent(input: PreparedJsonInput): PreparedContent;
+/** Stable media dependency identity contains no renewable upload id or URL. */
+export declare function logicalMediaBlobId(conversationId: string, messageId: string, index: number): string;

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

@@ -0,0 +1,14 @@
+/**
+ * Opaque, server-issued authority for one agent reply to one inbound message.
+ *
+ * The stream delivers this beside the triggering message. Runtimes keep it out
+ * of model-visible schemas and return it only on the ordinary reply path.
+ */
+export interface AgentReplyAuthorityV1 {
+    schema: 'canon.agent-reply-authority.v1';
+    sourceMessageId: string;
+    token: string;
+    expiresAt: string;
+    /** Agent membership admission at issuance; absent/null only for legacy membership. */
+    admissionId?: string | null;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into the Hermes plugin's committed
+ * rich-cards SKILL.md, and `npm run check:skill-bundles` fails on a byte change.
+ */
+export declare const RUNTIME_CARD_FIELD_TYPES: readonly ["text", "textarea", "select", "multiSelect", "boolean", "date", "number", "currency", "searchSelect", "lineItems"];
+export type RuntimeCardFieldType = (typeof RUNTIME_CARD_FIELD_TYPES)[number];
+/**
+ * Caps shared across runtime-card normalizers, response validation, and
+ * authoring tools. Keep these backend-safe so Functions can import them.
+ */
+export declare const RUNTIME_CARD_LIMITS: {
+    readonly detailsRows: 32;
+    readonly lineItemRows: 50;
+    readonly lineItemColumns: 8;
+    readonly searchSelectChoices: 100;
+};
+export interface RuntimeCardFieldChoice {
+    label: string;
+    value?: string;
+    description?: string;
+    preview?: string;
+}
+/** Column cell types allowed inside a `lineItems` field. */
+export declare const RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES: readonly ["text", "number", "currency", "date", "select"];
+export type RuntimeCardLineItemColumnType = (typeof RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES)[number];
+export interface RuntimeCardLineItemColumn {
+    id: string;
+    label: string;
+    type: RuntimeCardLineItemColumnType;
+    required?: boolean;
+    choices?: RuntimeCardFieldChoice[];
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    allowOther?: boolean;
+}
+export interface RuntimeCardField {
+    id: string;
+    label: string;
+    type: RuntimeCardFieldType;
+    required?: boolean;
+    placeholder?: string;
+    choices?: RuntimeCardFieldChoice[];
+    allowOther?: boolean;
+    sensitive?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    columns?: RuntimeCardLineItemColumn[];
+    minRows?: number;
+    maxRows?: number;
+}
+export declare function validateRuntimeCardFieldValues(input: {
+    actionId: string | undefined;
+    actionFields: ReadonlyArray<RuntimeCardField> | undefined;
+    values: Record<string, unknown> | undefined;
+}): string | null;

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

@@ -0,0 +1,3 @@
+export declare function decodeStoredRuntimeCard(input: {
+    runtimeCardJson?: unknown;
+}): Record<string, unknown> | undefined;

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

@@ -0,0 +1,88 @@
+export type CanonControlValue = string;
+export type CanonRuntimeStreamingMode = 'none' | 'status' | 'snapshot' | 'block' | 'delta';
+export type CanonRuntimeDetailTier = 'primary' | 'detail' | 'diagnostic';
+export type CanonRuntimeVisibility = 'conversation' | 'hidden';
+export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
+export type CanonRuntimeActionPlacement = 'composer_slash' | 'command_palette' | 'session_strip';
+export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'runtime' | 'details' | 'skill' | 'custom';
+export type CanonRuntimePrimitiveId = 'runtime.status' | 'runtime.reasoning.set' | 'runtime.verbosity.set' | 'runtime.usage' | 'context.compact' | 'session.new' | 'session.reset';
+export type CanonRuntimeCommandArgumentKind = 'string' | 'enum' | 'boolean';
+export interface CanonRuntimeCommandArgumentChoice {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface CanonRuntimeCommandArgumentDescriptor {
+    id: string;
+    label: string;
+    kind: CanonRuntimeCommandArgumentKind;
+    required?: boolean;
+    captureRemaining?: boolean;
+    choices?: ReadonlyArray<CanonRuntimeCommandArgumentChoice>;
+}
+export type CanonRuntimeActionDispatch = {
+    kind: 'control';
+    controlId: string;
+    value?: CanonControlValue;
+} | {
+    kind: 'signal';
+    signal: 'interrupt' | 'stop_and_drop' | 'new_session';
+} | {
+    kind: 'primitive';
+    primitive: CanonRuntimePrimitiveId;
+} | {
+    kind: 'text_passthrough';
+    template: string;
+} | {
+    kind: 'compose';
+    text: string;
+} | {
+    kind: 'open_details';
+    target?: string;
+};
+export interface CanonRuntimeActionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+    visibility?: CanonRuntimeVisibility;
+    tier?: CanonRuntimeDetailTier;
+    sensitive?: boolean;
+    primitive?: CanonRuntimePrimitiveId;
+    aliases?: ReadonlyArray<string>;
+    category?: CanonRuntimeActionCategory;
+    placements?: ReadonlyArray<CanonRuntimeActionPlacement>;
+    availability?: ReadonlyArray<CanonRuntimeActionAvailability>;
+    ownerOnly?: boolean;
+    disabledReason?: string | null;
+    trailingTextBehavior?: 'ignore' | 'send_as_prompt';
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+    dispatch: CanonRuntimeActionDispatch;
+}
+export interface CanonRuntimeCommandDescriptor extends CanonRuntimeActionDescriptor {
+    primitive?: CanonRuntimePrimitiveId;
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+}
+export declare function normalizeRuntimeCommandAlias(value: string): string | null;
+export declare function normalizeRuntimeCommandAliases(command: Pick<CanonRuntimeCommandDescriptor, 'id' | 'aliases'>): string[];
+export declare const MAX_PUBLIC_RUNTIME_COMMANDS = 256;
+export declare function isRuntimePrimitiveId(value: unknown): value is CanonRuntimePrimitiveId;
+/** Public command metadata shared by endpoint-backed runtime publishers. Never copies local configuration. */
+export declare function normalizePublicRuntimeCommands(value: unknown): CanonRuntimeCommandDescriptor[];
+export interface PublicRuntimeDescriptor {
+    supportsInterrupt?: boolean;
+    supportsInputInterrupt?: boolean;
+    streamingTextMode?: CanonRuntimeStreamingMode;
+    commands?: CanonRuntimeCommandDescriptor[];
+}
+export declare function normalizePublicRuntimeDescriptor(value: unknown): PublicRuntimeDescriptor;
+/** Read-only session facts, excluding local paths, inventories, and hidden/sensitive values. */
+export declare function normalizePublicRuntimeFacts(value: unknown): {
+    id: string;
+    group: "runtime" | "model" | "connection" | "route";
+    label: string;
+    value: string;
+    tier: "primary" | "detail" | "diagnostic" | undefined;
+    tone: "neutral" | "good" | "warning" | "danger" | undefined;
+    copyable: boolean | undefined;
+    updatedAt: number | undefined;
+}[];

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

@@ -0,0 +1,9 @@
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export declare function normalizeStoredSelfContextId(value: unknown): string | null;
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+export declare function serializeSelfContext(id: string, data: Record<string, unknown>): Record<string, unknown> | null;

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

@@ -0,0 +1,43 @@
+export type SenderType = 'human' | 'ai_agent';
+export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
+export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
+export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
+export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected' | 'cancelled';
+export interface TurnMetadata {
+    turnId?: string | null;
+    turnSemantics?: TurnMessageSemantics;
+    deliveryIntent?: DeliveryIntent;
+    replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
+    inboundDisposition?: InboundDisposition;
+    requestedTurnMode?: string;
+}
+export interface TriggerDecision {
+    allow: boolean;
+    semantics: TurnMessageSemantics;
+    reason: string;
+}
+export interface TurnStateLike {
+    state: TurnLifecycleState;
+    openedAt?: number;
+    updatedAt?: number;
+    turnUpdatedAt?: number | null;
+}
+export declare const ACTIVE_TURN_STALE_THRESHOLD_MS: number;
+export declare const WAITING_INPUT_STALE_THRESHOLD_MS: number;
+export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
+export declare function isTurnOpen(turnState: TurnStateLike | null | undefined): boolean;
+export declare function getTurnStateStaleThresholdMs(state: TurnLifecycleState): number;
+export declare function isTurnStateStale(turnState: TurnStateLike | null | undefined): boolean;
+export declare function resolveTurnMessageSemantics(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): TurnMessageSemantics;
+export declare function shouldPromoteConversationMessage(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): boolean;
+export declare function shouldTriggerAgentTurn(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): TriggerDecision;
+export declare function normalizeRuntimeTurnState(value: unknown): TurnStateLike | null;

package/dist/internal/backend-contracts/upload-mime-types.d.ts

@@ -0,0 +1,17 @@
+/** The media types Canon accepts for an upload, resolved the same way on a device and on the server. */
+export type AllowedUploadKind = 'image' | 'audio' | 'video' | 'file';
+export declare const SAFE_IMAGE_MIME_TYPES: Set<string>;
+export declare const SAFE_AUDIO_MIME_TYPES: Set<string>;
+export declare const SAFE_VIDEO_MIME_TYPES: Set<string>;
+export declare const SAFE_FILE_MIME_TYPES: Set<string>;
+export declare function normalizeMimeType(value: unknown): string | null;
+export declare function classifyAllowedUploadMimeType(value: unknown): AllowedUploadKind | null;
+export declare function normalizeAllowedUploadMimeType(value: unknown): string | null;
+export declare function resolveAllowedUploadMimeType(input: {
+    mimeType?: unknown;
+    fileName?: unknown;
+}): string | null;
+export declare function getAllowedUploadExtension(input: {
+    mimeType: string;
+    fileName?: unknown;
+}): string;