@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/internal/core/unified-diff.d.ts

@@ -0,0 +1,35 @@
+import { isSensitiveDiffPath } from '../backend-contracts/index.js';
+import type { CanonUnifiedDiff } from './types.js';
+export { isSensitiveDiffPath };
+/** Total unified hunk text budget across all files (~96 KB). */
+export declare const UNIFIED_DIFF_MAX_TOTAL_BYTES: number;
+/** Per-file unified hunk text budget (~24 KB). */
+export declare const UNIFIED_DIFF_MAX_FILE_BYTES: number;
+/** Maximum number of file entries carried on one diff payload. */
+export declare const UNIFIED_DIFF_MAX_FILES = 100;
+export interface TruncateUnifiedDiffOptions {
+    maxTotalBytes?: number;
+    maxFileBytes?: number;
+    maxFiles?: number;
+}
+/**
+ * Enforce the unified-diff payload budget: clips each file's hunk text at a
+ * line boundary to `maxFileBytes`, then drops hunk text entirely once the
+ * running total exceeds `maxTotalBytes`. File entries (path, status, counts)
+ * always survive — only hunk text is clipped or dropped — and every clip sets
+ * the corresponding `truncated` flag.
+ */
+export declare function truncateUnifiedDiff(diff: CanonUnifiedDiff, options?: TruncateUnifiedDiffOptions): CanonUnifiedDiff;
+/**
+ * Suppress and redact sensitive content in a diff before it leaves the host.
+ * Apply BEFORE truncateUnifiedDiff so byte budgets are spent on hunks that
+ * actually ship.
+ */
+export declare function sanitizeUnifiedDiffForSharing(diff: CanonUnifiedDiff): CanonUnifiedDiff;
+/**
+ * Parse an untrusted unified-diff payload (message metadata travels through
+ * Firestore and arbitrary hosts). Invalid file entries are dropped; the result
+ * is re-truncated to the standard budgets so clients never render an
+ * oversized payload. Returns undefined when nothing renderable remains.
+ */
+export declare function normalizeCanonUnifiedDiff(value: unknown): CanonUnifiedDiff | undefined;

package/dist/internal/endpoint/artifact-images.d.ts

@@ -0,0 +1,60 @@
+import { type ArtifactImageRegion, type ArtifactImageVariant, type MediaAttachment } from '../backend-contracts/index.js';
+import type { Endpoint } from './engine.js';
+import { type ArtifactClient, type ArtifactWriteResult } from './artifacts.js';
+import { isTerminalImageGenerationError } from './image-generation-errors.js';
+export { isTerminalImageGenerationError };
+export type { ArtifactImageRegion };
+export interface ArtifactImageGenerateInput {
+    prompt: string;
+    label: string;
+    /** 'current' edits the current version (or generates new when there is none). */
+    from: 'current' | 'new' | {
+        variantId: string;
+    };
+    /** Fractions of the source image, origin top-left. */
+    region?: ArtifactImageRegion;
+    /** UUID for one deliberate generation; reuse it to collect the same result. */
+    requestId: string;
+    /** Cancels the wait. Once the job is submitted, the result is `generating` and nothing is published. */
+    signal?: AbortSignal;
+    /** How long to wait for the provider before returning `generating` (default 180 s). */
+    timeoutMs?: number;
+}
+export type ArtifactImageGenerateResult = {
+    status: 'added';
+    variant: ArtifactImageVariant;
+    result: ArtifactWriteResult;
+    attachment: MediaAttachment;
+} | {
+    status: 'generating';
+    requestId: string;
+};
+export interface ArtifactImageAddInput {
+    assetId: string;
+    label: string;
+    prompt?: string;
+    sourceVariantId?: string;
+    select?: boolean;
+}
+export interface ArtifactImageClient {
+    generate(conversationId: string, artifactId: string, input: ArtifactImageGenerateInput): Promise<ArtifactImageGenerateResult>;
+    add(conversationId: string, artifactId: string, input: ArtifactImageAddInput): Promise<{
+        variant: ArtifactImageVariant;
+        result: ArtifactWriteResult;
+    }>;
+}
+/** Test hooks; production uses the defaults. */
+export interface ArtifactImageClientOptions {
+    pollIntervalMs?: number;
+    /** A job may not be visible yet while its request is still being delivered. */
+    notFoundGraceMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * The provider runs on the server under a durable `image-generation:<requestId>`
+ * operation; this client only waits for its result, retains it, and adds it as
+ * the current version. Repeating a call with the same requestId collects the
+ * same image and never starts a second generation.
+ */
+export declare function createArtifactImageClient(endpoint: Endpoint, artifacts?: ArtifactClient, options?: ArtifactImageClientOptions): ArtifactImageClient;

package/dist/internal/endpoint/artifact-reducer.d.ts

@@ -0,0 +1,35 @@
+import { type ArtifactCommandRecord, type ArtifactFormValue, type ArtifactReadResult, type ArtifactSnapshot } from '../backend-contracts/index.js';
+/**
+ * Integrity failures halt replay: a sequence gap, a changed artifact identity,
+ * an unsupported codec, or an envelope written by a newer Canon. Nothing else does.
+ */
+export declare class ArtifactReplayError extends Error {
+    readonly code: 'UNSUPPORTED_VERSION' | 'ARTIFACT_LOG_INVALID';
+    constructor(code: 'UNSUPPORTED_VERSION' | 'ARTIFACT_LOG_INVALID', message: string);
+}
+/** FEN without the half-move and full-move clocks. */
+export declare const chessPositionKey: (fen: string) => string;
+/** A form value that changed since the author looked. */
+export interface ArtifactConflict {
+    path: string[];
+    label: string;
+    expected: ArtifactFormValue;
+    current: ArtifactFormValue;
+    currentBy?: string;
+}
+/** Structured conflicts of a form command (form.set or form.fields) against the snapshot it was judged on. */
+export declare function artifactCommandConflicts(snapshot: ArtifactSnapshot, command: unknown): ArtifactConflict[];
+/** Structured conflicts of form.set changes against the snapshot they were judged on. */
+export declare function artifactFormConflicts(snapshot: ArtifactSnapshot, changes: unknown): ArtifactConflict[];
+/** Pure reduction of one relay record. Throws only for integrity halts. */
+export declare function reduceArtifactRecord(previous: ArtifactReadResult, record: ArtifactCommandRecord, conversationId: string): ArtifactReadResult;
+export interface ArtifactReplayPage {
+    previous: ArtifactReadResult;
+    commands: ArtifactCommandRecord[];
+    conversationId: string;
+    artifactId: string;
+    /** Stop once this revision is reached (historical read). */
+    revisionId?: string;
+}
+/** In-process replay of one log page. Built-in rules only: bounded and synchronous. */
+export declare function replayArtifactPage(page: ArtifactReplayPage): ArtifactReadResult;

package/dist/internal/endpoint/artifact-views.d.ts

@@ -0,0 +1,113 @@
+import { type ArtifactChessState, type ArtifactFormColumn, type ArtifactFormFieldType, type ArtifactFormRow, type ArtifactFormValue, type ArtifactKind, type ArtifactSnapshot } from '../backend-contracts/index.js';
+/** Readable projections of shared work for agents, prompts and compact UI. */
+export interface ArtifactPrincipalView {
+    id: string;
+    name?: string;
+    isYou?: boolean;
+}
+export interface ArtifactViewOptions {
+    /** The principal reading the view (marks `isYou`, seats and turn). */
+    viewerId?: string;
+    names?: Record<string, string>;
+    /** The snapshot this viewer saw last; adds `changesSinceLastView`. */
+    previous?: ArtifactSnapshot;
+}
+export interface ArtifactViewBase {
+    artifactId: string;
+    kind: ArtifactKind;
+    title: string;
+    revisionId: string;
+    archived: boolean;
+    createdBy: ArtifactPrincipalView;
+    updatedBy: ArtifactPrincipalView;
+    updatedAt: string;
+}
+export interface ArtifactChessMoveView {
+    ply: number;
+    notation: string;
+    san: string;
+    by: ArtifactPrincipalView;
+}
+export interface ArtifactChessView extends ArtifactViewBase {
+    kind: 'chess';
+    fen: string;
+    /** ASCII, rank 8 first, uppercase White, with file and rank labels. */
+    board: string;
+    turn: 'white' | 'black';
+    /** Full-move number. */
+    moveNumber: number;
+    /** e.g. "1. e4 e5 2. Nf3". */
+    moveList: string;
+    lastMove?: ArtifactChessMoveView;
+    players: {
+        white?: ArtifactPrincipalView;
+        black?: ArtifactPrincipalView;
+    };
+    yourColor?: 'white' | 'black';
+    yourTurn: boolean;
+    status: ArtifactChessState['status'];
+    result?: ArtifactChessState['result'];
+    resignedBy?: ArtifactPrincipalView;
+    check: boolean;
+    /** SAN, while the game is active. */
+    legalMoves?: string[];
+    /** Moves since the previous view. */
+    changesSinceLastView?: ArtifactChessMoveView[];
+}
+export interface ArtifactFormFieldView {
+    id: string;
+    label: string;
+    type: ArtifactFormFieldType;
+    value: ArtifactFormValue;
+    required?: boolean;
+    options?: string[];
+    placeholder?: string;
+    help?: string;
+    decimals?: number;
+}
+export interface ArtifactFormChangeView {
+    label: string;
+    path: string[];
+    before: ArtifactFormValue | Record<string, ArtifactFormValue>;
+    after: ArtifactFormValue | Record<string, ArtifactFormValue>;
+}
+export interface ArtifactFormView extends ArtifactViewBase {
+    kind: 'form';
+    fields: ArtifactFormFieldView[];
+    /** Labels of required fields that are empty. */
+    missingRequired: string[];
+    /**
+     * `sums` holds each summed column's total, rounded to the column's decimals.
+     * Form numbers are bounded, so a total is always finite; a total that is not
+     * (state written outside the shared rules) reads as null instead of failing.
+     */
+    table?: {
+        label?: string;
+        columns: ArtifactFormColumn[];
+        rows: ArtifactFormRow[];
+        sums: Record<string, number | null>;
+    };
+    changesSinceLastView?: ArtifactFormChangeView[];
+}
+export interface ArtifactImageVariantView {
+    id: string;
+    label: string;
+    prompt?: string;
+    by: ArtifactPrincipalView;
+    at: string;
+    sourceVariantId?: string;
+    assetId: string;
+    current: boolean;
+}
+export interface ArtifactImageView extends ArtifactViewBase {
+    kind: 'image';
+    variants: ArtifactImageVariantView[];
+    currentVariantId?: string;
+    /** Versions added since the previous view. */
+    changesSinceLastView?: ArtifactImageVariantView[];
+}
+export type ArtifactView = ArtifactChessView | ArtifactFormView | ArtifactImageView;
+export declare function chessBoardAscii(fen: string): string;
+export declare function describeArtifact(snapshot: ArtifactSnapshot, options?: ArtifactViewOptions): ArtifactView;
+/** One line, viewer-relative: "Chess “Game”: move 12, Black to move (you play Black). Your move. Last: 11...Nf6 by Alice." */
+export declare function summarizeArtifact(snapshot: ArtifactSnapshot, options?: Omit<ArtifactViewOptions, 'previous'>): string;

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

@@ -0,0 +1,75 @@
+import { type ArtifactAsset, type ArtifactCommand, type ArtifactCommandBody, type ArtifactDefinition, type ArtifactDomainOutcome, type ArtifactOutcomeCode, type ArtifactReadResult, type ArtifactSnapshot } from '../backend-contracts/index.js';
+import type { Endpoint } from './engine.js';
+import { type ArtifactConflict } from './artifact-reducer.js';
+/** The command was rejected by the shared rules; nothing new was accepted. */
+export declare class ArtifactRejectedError extends Error {
+    readonly code: ArtifactOutcomeCode | 'UNSUPPORTED_VERSION';
+    readonly outcome?: ArtifactDomainOutcome;
+    readonly conflicts?: ArtifactConflict[];
+    /** The projection the command was evaluated against: the author's fresh state. */
+    readonly current?: ArtifactReadResult;
+    constructor(message: string, options: {
+        code: ArtifactOutcomeCode | 'UNSUPPORTED_VERSION';
+        outcome?: ArtifactDomainOutcome;
+        conflicts?: ArtifactConflict[];
+        current?: ArtifactReadResult;
+    });
+}
+/**
+ * `accepted`: the relay stored the command and the shared rules accepted it.
+ * `queued`: the durable outbox keeps retrying delivery; snapshot and outcome
+ * are a local prediction. Callers must not resend.
+ */
+export interface ArtifactWriteResult extends ArtifactReadResult {
+    outcome: ArtifactDomainOutcome;
+    status: 'accepted' | 'queued';
+}
+/** `unavailable` codes include NO_DEFINITION and ARTIFACT_LOADING (a long log still replaying; a later listing has it). */
+export interface ArtifactLibrary {
+    artifacts: ArtifactSnapshot[];
+    unavailable: Array<{
+        artifactId: string;
+        code: string;
+        message: string;
+    }>;
+}
+/** The client stamps the schema; a caller-supplied schema must match it. */
+export type ArtifactCommandInput = ArtifactCommandBody | ArtifactCommand;
+export interface ArtifactWriteOptions {
+    commandId?: string;
+    waitMs?: number;
+}
+export interface ArtifactCreateOptions {
+    artifactId?: string;
+    commandId?: string;
+    waitMs?: number;
+}
+export interface ArtifactClientOptions {
+    encoding?: 'json' | 'mls';
+    /** How long a listing waits for one work before reporting it as still loading (default 4 s). */
+    listItemWaitMs?: number;
+}
+export interface ArtifactClient {
+    list(conversationId: string): Promise<ArtifactLibrary>;
+    read(conversationId: string, artifactId: string, options?: {
+        revisionId?: string;
+    }): Promise<ArtifactReadResult>;
+    create(conversationId: string, definition: ArtifactDefinition, options?: ArtifactCreateOptions): Promise<ArtifactWriteResult>;
+    apply(conversationId: string, artifactId: string, command: ArtifactCommandInput, options?: ArtifactWriteOptions): Promise<ArtifactWriteResult>;
+    retainAsset(conversationId: string, artifactId: string, assetId: string): Promise<ArtifactAsset>;
+    getAsset(conversationId: string, artifactId: string, assetId: string): Promise<ArtifactAsset>;
+    /** Polls the log head only; reads (and replays) when it moves. */
+    observe(conversationId: string, artifactId: string, listener: (value: ArtifactReadResult) => void, onError?: (error: unknown) => void): () => void;
+    observeList(conversationId: string, listener: (value: ArtifactLibrary) => void, onError?: (error: unknown) => void): () => void;
+    /**
+     * An opaque command ID for one deliberate request: `cmd-` and 40 hex
+     * characters of an HMAC-SHA256 over the canonical JSON of `material`, keyed
+     * by this installation's secret. Stable for retries on this installation,
+     * unrelated elsewhere, and never a server-testable hash of its content.
+     * Throws PREPARATION_INSTALLATION_FENCED on an endpoint another logout fenced.
+     */
+    deriveCommandId(material: unknown[]): Promise<string>;
+    /** The same derivation (separate domain) as an RFC 4122-shaped UUID, for image request IDs. */
+    deriveRequestId(material: unknown[]): Promise<string>;
+}
+export declare function createArtifactClient(endpoint: Endpoint, options?: ArtifactClientOptions): ArtifactClient;

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

@@ -0,0 +1,47 @@
+import type { Endpoint, EndpointIntent, EndpointOperation, EndpointResolvedIdentity } from './engine.js';
+import { type EndpointStore } from './store.js';
+export interface EndpointMessageGroupInput {
+    id: string;
+    replacesOperationId?: string;
+    children: Array<{
+        operationId: string;
+        intent: EndpointIntent;
+    }>;
+}
+export interface EndpointMessageGroup {
+    id: string;
+    conversationId: string;
+    installationId: string;
+    fingerprint: string;
+    children: Array<{
+        operationId: string;
+        messageId: string;
+    }>;
+    createdAt: string;
+    cancelled?: boolean;
+}
+export declare function messageGroupChildSucceeded(operation: EndpointOperation | undefined): boolean;
+/** Atomic ordered message plans; plaintext remains only in normal operation rows. */
+export declare function createMessageGroupCoordinator(input: {
+    store: EndpointStore;
+    endpoint(): Endpoint;
+    ready(): Promise<EndpointResolvedIdentity>;
+    hash(value: string): Promise<string>;
+    clock(): number;
+    wake(): void;
+    preparationGeneration?(): number;
+    supportsPreparedContent?(): Promise<boolean>;
+}): {
+    allowed(id: string): boolean;
+    close(): void;
+    settled(operation: EndpointOperation): Promise<void>;
+    register(plan: EndpointMessageGroupInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EndpointOperation>;
+    get(id: string): Promise<EndpointOperation | undefined>;
+    wait(id: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<import("../backend-contracts/index.js").EndpointOperationReceipt<unknown>>;
+    cancel(id: string): Promise<void>;
+};

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

@@ -0,0 +1,249 @@
+import { type EndpointMessageGroupInput } from './delivery.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';
+import { type EndpointSyncOptions, type EndpointSyncPage } from './sync.js';
+import { type EndpointEventObserver, type EndpointTransportEvent } from './events.js';
+import { type EndpointRecoveryOptions, type EndpointRecoveryBaseline } from './recovery.js';
+import { type EndpointRecoveryMigration, type EndpointMigrationReceipt } from './migration.js';
+import { type EndpointBackgroundMediaAdapter, type EndpointMediaBytes, type EndpointMediaPipeline } from './media.js';
+import { type EndpointOrdering } from './queue.js';
+import { type EndpointInboundHandoff, type EndpointInboundStartResult } from './handoff.js';
+import { type ExternalInboundClaim } from './external-inbound.js';
+import type { EndpointExternalInboundClaimResult, EndpointExternalInboundOutcome } from '../backend-contracts/index.js';
+import { type MlsDevGroupClient } from './mls-dev-groups.js';
+import { type MlsDevDeviceClientOptions, type MlsDevDeviceClient } from './mls-dev-client.js';
+import { type MlsDevKeyPackageClient } from './mls-dev-key-packages.js';
+export interface EndpointIdentity {
+    environmentId: string;
+    principalId: string;
+    installationId?: string;
+    ownershipVersion?: number;
+}
+export type EndpointResolvedIdentity = EndpointIdentity & {
+    installationId: string;
+};
+export interface EndpointIntent {
+    action: string;
+    body: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    preconditions?: EndpointPreconditions;
+}
+export interface EndpointExecuteOptions {
+    operationId?: string;
+    sensitive?: boolean;
+    guardId?: string;
+}
+export interface EndpointWaitOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export type EndpointLocalStatus = 'queued' | 'sending' | 'deferred' | 'pending' | 'succeeded' | 'rejected' | 'uncertain';
+export interface EndpointOperation {
+    operationId: string;
+    /** Durable authoring sequence, separate from the random operation identity. */
+    queueOrder?: number;
+    /** Derived dependency class retained even after the request payload is erased. */
+    ordering?: EndpointOrdering;
+    installationId: string;
+    action: string;
+    conversationId?: string;
+    messageId?: string;
+    agentId?: string;
+    /** Ordering scope for shared-work commands, retained after payload erasure. */
+    artifactId?: string;
+    status: EndpointLocalStatus;
+    fingerprint: string;
+    preconditions?: EndpointPreconditions;
+    sensitive: boolean;
+    resultEvicted?: boolean;
+    guardId?: string;
+    messageGroupId?: string;
+    childOperationIds?: string[];
+    messagePublished?: boolean;
+    request?: EndpointOperationRequest;
+    /** Exact sealed JSON bytes; retries do not run content preparation again. */
+    preparedContent?: PreparedContent;
+    /** Authored-input collision check, never recorded for memory-only answers. */
+    inputFingerprint?: string;
+    receipt?: EndpointOperationReceipt;
+    attempts: number;
+    attempted: boolean;
+    nextAttemptAt?: number;
+    lease?: {
+        owner: string;
+        expiresAt: number;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+export type EndpointInboundState = 'observed' | 'deferred' | 'offered' | 'uncertain' | 'settled';
+export interface EndpointInboundRecord {
+    event: EndpointEvent;
+    queueKey?: string;
+    deleted?: boolean;
+    state: EndpointInboundState;
+    reason?: string;
+    createdAt: string;
+    updatedAt: string;
+    lease?: {
+        owner: string;
+        expiresAt: number;
+    };
+    /** Opaque process generation; uncertain effects retain it until reconciliation. */
+    handoffGeneration?: string;
+    /** Installation epoch in which that handoff was acquired; logout fences replay. */
+    handoffInstallationGeneration?: number;
+    /** External acceptance survives the request process; it is never reoffered. */
+    externalClaim?: ExternalInboundClaim;
+}
+export interface EndpointConversation {
+    id: string;
+    membershipRevision?: number;
+    memberIds?: string[];
+    [key: string]: unknown;
+}
+export interface EndpointOptions {
+    identity: EndpointIdentity;
+    credentials?: EndpointCredentials;
+    transport: EndpointTransport;
+    store: EndpointStore;
+    clock?: () => number;
+    ids?: () => string;
+    hash?: (value: string) => Promise<string>;
+    /** SHA-256 of exact binary protocol frames, returned as lowercase hexadecimal. */
+    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. */
+    admitRecoveredMessages?: boolean;
+    /** Disable automatic delivery when inspecting or importing a stopped installation. Explicit execute/drain remains available. */
+    autoDrain?: boolean;
+    /** Explicit synthetic Dev device identity operations, using this endpoint's store and lifecycle. */
+    mlsDevDevice?: MlsDevDeviceClientOptions;
+}
+export type EndpointContentMode = 'plaintext' | 'mls-dev-text' | 'mls-required';
+export interface Endpoint {
+    readonly mlsDevDevice?: MlsDevDeviceClient;
+    readonly mlsDevKeyPackages?: MlsDevKeyPackageClient;
+    readonly mlsDevGroups?: MlsDevGroupClient;
+    ready(): Promise<EndpointResolvedIdentity>;
+    getConversationContentMode(conversationId: string): Promise<EndpointContentMode>;
+    submit(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<EndpointOperation>;
+    execute<T = unknown>(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<EndpointOperationReceipt<T>>;
+    executeResult<T = unknown>(intent: EndpointIntent, options?: EndpointExecuteOptions): Promise<T>;
+    /** reconcileOnly reads the server receipt; it never dispatches an operation. */
+    retry<T = unknown>(operationId: string, options?: {
+        reconcileOnly?: boolean;
+    }): Promise<EndpointOperationReceipt<T>>;
+    drain(options?: {
+        limit?: number;
+    }): Promise<void>;
+    getOperation(operationId: string): Promise<EndpointOperation | undefined>;
+    /** Observe shared delivery without creating an adapter retry loop. */
+    waitForOperation<T = unknown>(operationId: string, options?: EndpointWaitOptions): Promise<EndpointOperationReceipt<T>>;
+    listOperations(options?: {
+        statuses?: EndpointLocalStatus[];
+        conversationId?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<EndpointOperation[]>;
+    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;
+    observeEvents(listener: (event: EndpointTransportEvent) => void, options?: EndpointEventObserver): () => void;
+    createMediaPipeline<Source>(bytes: EndpointMediaBytes<Source>, options?: {
+        background?: EndpointBackgroundMediaAdapter<Source>;
+    }): EndpointMediaPipeline<Source>;
+    registerMessageGroup(input: EndpointMessageGroupInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<EndpointOperation>;
+    getMessageGroup(id: string): Promise<EndpointOperation | undefined>;
+    waitForMessageGroup(id: string, options?: EndpointWaitOptions): Promise<EndpointOperationReceipt>;
+    cancelMessageGroup(id: string): Promise<void>;
+    /** Runtime-specific publication policy; closures are never serialized.
+     * 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>;
+    syncConversation(conversationId: string, options?: EndpointSyncOptions): Promise<EndpointSyncPage>;
+    startRecovery(options?: EndpointRecoveryOptions): () => void;
+    /** Immutable operator-reviewed or server-proven cutover for new rooms/admissions. */
+    configureRecoveryBaseline(config: EndpointRecoveryBaseline): Promise<void>;
+    getRecoveryBaseline(): Promise<EndpointRecoveryBaseline | undefined>;
+    refreshRecovery(): Promise<void>;
+    planRecoveryMigration(baseline: EndpointRecoveryBaseline, conversationIds?: string[]): Promise<EndpointRecoveryMigration>;
+    importRecoveryMigration(manifest: EndpointRecoveryMigration, reviewedSha256: string): Promise<EndpointMigrationReceipt>;
+    getInbound(id: string): Promise<EndpointInboundRecord | undefined>;
+    claimInbound(id: string | string[]): Promise<boolean>;
+    claimExternalInbound(id: string, requestId: string, authorizedEvent: EndpointEvent): Promise<EndpointExternalInboundClaimResult>;
+    reserveExternalInboundReply(id: string, requestId: string, intent: import('../backend-contracts/index.js').EndpointExternalInboundReplyIntent): Promise<boolean>;
+    /** Trusted host preparation; persists fresh admission with the engine's immutable send identity. */
+    prepareExternalInboundReply(id: string, requestId: string, operationId: string, prepare: () => Promise<{
+        event: EndpointEvent;
+        intent: EndpointIntent;
+    }>): Promise<{
+        event: EndpointEvent;
+        replayed: boolean;
+    }>;
+    settleExternalInbound(id: string, requestId: string, outcome: EndpointExternalInboundOutcome, replyFingerprint?: string): Promise<boolean>;
+    acquireInbound(id: string): Promise<EndpointInboundHandoff | null>;
+    startInbound<T>(handles: EndpointInboundHandoff | readonly EndpointInboundHandoff[], submit: () => T | Promise<T>): Promise<EndpointInboundStartResult<T>>;
+    /** Trusted host only: its durable journal must positively prove the provider
+     * submission boundary never ran. Absence of a remote receipt is not proof.
+     * Fences an exact uncertain generation; never infers or verifies that proof. */
+    reconcileInboundNotSubmitted(id: string, expected: {
+        expectedHandoffGeneration: string;
+        expectedInstallationId: string;
+    }): Promise<boolean>;
+    acceptInbound(options: EndpointInboundConsumerOptions): EndpointInboundConsumer;
+    setInboundState(id: string, state: EndpointInboundState, reason?: string): Promise<void>;
+    listInbound(options?: {
+        states?: EndpointInboundState[];
+        after?: string;
+        limit?: number;
+    }): Promise<EndpointInboundRecord[]>;
+    discardPending(): Promise<void>;
+    logout(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function mergeConversationSnapshot<T extends EndpointConversation>(current: T | undefined, incoming: T): T;
+export declare function createEndpoint(options: EndpointOptions): Endpoint;

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

@@ -0,0 +1,8 @@
+import type { Endpoint } from './engine.js';
+export interface EndpointEphemeralObserver {
+    observe(path: string, listener: (value: unknown) => void, onError?: (error: unknown) => void): () => void;
+    close(): void;
+}
+/** One in-memory transient projection and SSE owner per endpoint. Snapshots
+ * bootstrap active scopes; disconnected fallback reads are shared and bounded. */
+export declare function createEndpointEphemeralObserver(endpoint: Pick<Endpoint, 'query' | 'observeEvents'>): EndpointEphemeralObserver;

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

@@ -0,0 +1,32 @@
+import { type EndpointTransport } from './transport.js';
+export interface EndpointTransportEvent {
+    id?: string;
+    kind: string;
+    data: Record<string, unknown>;
+}
+/** `artifacts` streams `artifact.changed` hints for rooms the principal belongs to. */
+export type EndpointEventFamily = 'messages' | 'contacts' | 'typing_presence' | 'runtime_turn' | 'voice' | 'artifacts';
+export interface EndpointEventObserver {
+    families?: EndpointEventFamily[];
+    /** Explicit principal projections; room projections follow membership. */
+    principalScopes?: string[];
+    onConnected?(): void;
+    onDisconnected?(): void;
+    onError?(error: Error): void;
+}
+/** One reconnect loop and replay token per endpoint, shared by every observer. */
+export declare function createEndpointEventHub(input: {
+    transport: EndpointTransport;
+    invalidate(event?: EndpointTransportEvent): void;
+    onEvent?(event: EndpointTransportEvent): Promise<void>;
+    onDisconnected?(): void;
+}): {
+    isConnected: () => boolean;
+    observe(listener: (event: EndpointTransportEvent) => void, hooks?: EndpointEventObserver): () => void;
+    close(): Promise<void>;
+};
+/** Incremental SSE parsing handles CRLF and UTF-8 boundaries without Node APIs. */
+export declare function readEndpointEvents(response: Response, options: {
+    signal: AbortSignal;
+    idleTimeoutMs?: number;
+}): AsyncGenerator<EndpointTransportEvent>;