@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,27 @@
+import type { EndpointEventObserver, EndpointTransportEvent } from './events.js';
+import type { EndpointSyncOptions, EndpointSyncPage } from './sync.js';
+import type { EndpointStore } from './store.js';
+export interface EndpointRecoveryOptions {
+    intervalMs?: number;
+    onError?(error: unknown, conversationId?: string): void;
+}
+export interface EndpointRecoveryBaseline {
+    cutoverAt: string;
+    migrationId: string;
+}
+/** One account scan and recovery queue, independent of runtime/session count. */
+export declare function createEndpointRecovery(input: {
+    store: EndpointStore;
+    ready(): Promise<unknown>;
+    query<T>(name: string, parameters: Record<string, unknown>): Promise<T>;
+    sync(conversationId: string, options?: EndpointSyncOptions): Promise<EndpointSyncPage>;
+    isProtocolReady?(conversationId: string): Promise<boolean | undefined>;
+    observe(listener: (event: EndpointTransportEvent) => void, hooks: EndpointEventObserver): () => void;
+}): {
+    getBaseline(): Promise<EndpointRecoveryBaseline | undefined>;
+    configureBaseline(config: EndpointRecoveryBaseline): Promise<void>;
+    start(options?: EndpointRecoveryOptions): () => void;
+    refresh: () => Promise<void>;
+    assertReady(conversationId: string): Promise<void>;
+    close(): Promise<void>;
+};

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

@@ -0,0 +1,7 @@
+import type { EndpointOperation } from './engine.js';
+import type { EndpointStore } from './store.js';
+export declare function compactOperation(operation: EndpointOperation): EndpointOperation;
+/** Age out duplicate plaintext, retaining small idempotency tombstones. */
+export declare function compactExpiredPayloads(store: EndpointStore, clock: number): Promise<void>;
+/** Logout erases local plaintext without turning uncertain external work into new work. */
+export declare function eraseEndpointPlaintext(store: EndpointStore): Promise<void>;

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

@@ -0,0 +1,22 @@
+/** Transaction callbacks may be retried. They must perform only store operations. */
+export interface EndpointStoreTransaction {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan<T>(prefix: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<Array<{
+        key: string;
+        value: T;
+    }>>;
+}
+export interface EndpointStore {
+    transaction<T>(work: (transaction: EndpointStoreTransaction) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export declare function copyJson<T>(value: T): T;
+/** Tests and explicitly ephemeral callers only. Production endpoints supply durable storage. */
+export declare function createMemoryEndpointStore(): EndpointStore;
+/** Shared canonical serialization for prepared payloads and legacy fingerprints. */
+export { canonicalEndpointJson as canonicalJson } from '../backend-contracts/index.js';

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

@@ -0,0 +1,33 @@
+import type { EndpointEvent } from '../backend-contracts/index.js';
+import { type EndpointStore } from './store.js';
+export interface EndpointSyncPage {
+    changes: EndpointEvent[];
+    cursor: string | null;
+    hasMore: boolean;
+    admissionId: string | null;
+    bootstrap: boolean;
+    reset?: boolean;
+}
+export interface EndpointSyncOptions {
+    /** Required on first use. Checkpoint is only for history proven not to be new work. */
+    bootstrap?: 'receive' | 'checkpoint';
+    limit?: number;
+    /** Preserve a sticky pause instead of silently creating a new admission baseline. */
+    pauseOnAdmissionChange?: boolean;
+    /** Explicitly choose a fresh boundary after a sticky pause. Ignored otherwise. */
+    resumeAdmissionChange?: 'checkpoint';
+}
+export declare function createConversationSynchronizer(input: {
+    store: EndpointStore;
+    query<T>(query: string, parameters: Record<string, unknown>): Promise<T>;
+    ready(): Promise<unknown>;
+    clock(): number;
+    invalidate(conversationId: string): void;
+    admitRecoveredMessages?: boolean;
+    preparationGeneration?(): number;
+    /** Apply ordered MLS controls through the same lifecycle before app recovery. */
+    prepareProtocol?(conversationId: string): Promise<boolean>;
+    syncProtocol?(conversationId: string, options: EndpointSyncOptions): Promise<EndpointSyncPage | undefined>;
+}): ((conversationId: string, options?: EndpointSyncOptions) => Promise<EndpointSyncPage>) & {
+    close(): Promise<void>;
+};

package/dist/internal/endpoint/transient-publisher.d.ts

@@ -0,0 +1,8 @@
+import type { Endpoint } from './engine.js';
+/** Transient writes are coalesced here; they never enter the durable outbox. */
+export declare function createEndpointTransientPublisher(endpoint: Pick<Endpoint, 'publish'>, clock?: () => number): {
+    pulseTyping(conversationId: string): void;
+    stopTyping: (conversationId: string) => void;
+    setPresence(state: "online" | "offline" | "hidden"): void;
+    close(): void;
+};

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

@@ -0,0 +1,63 @@
+import { type CanonClientIdentity, type EndpointContentLane, type EndpointOperationRequest, type EndpointOperationReceipt, type EndpointCapabilities } from '../backend-contracts/index.js';
+import { type EndpointTransportEvent, type EndpointEventFamily } from './events.js';
+import { type MlsDevDeviceHttpOptions, type MlsDevDeviceTransport } from './mls-dev-transport.js';
+export declare class EndpointError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly operationId?: string;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        retryable?: boolean;
+        operationId?: string;
+        retryAfterMs?: number;
+    });
+}
+/** HTTP failures and SSE close frames carry the same error details. A changed
+ * authorization reconnects through authentication; a rejected handshake stops. */
+export declare function decodeEndpointError(value: unknown, options?: {
+    status?: number;
+    retryAfter?: string | null;
+    stream?: boolean;
+}): EndpointError;
+export interface EndpointCredentials {
+    getToken(forceRefresh?: boolean): Promise<string>;
+}
+/** Shared transport enforces the reviewed lane inventory in both directions.
+ * Content remains JSON; field classification never grants authorization. */
+export declare function validateEndpointContentBoundary(lane: EndpointContentLane, name: string, payload: unknown): void;
+export interface EndpointTransport {
+    mlsDevDevice?: MlsDevDeviceTransport;
+    capabilities?(): Promise<EndpointCapabilities>;
+    execute(request: EndpointOperationRequest, signal?: AbortSignal): Promise<EndpointOperationReceipt>;
+    getOperation(operationId: string, installationId: string, signal?: AbortSignal): Promise<EndpointOperationReceipt | null>;
+    query<T>(query: string, parameters: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    publish<T>(action: string, body: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    events?(options: {
+        lastEventId?: string;
+        signal: AbortSignal;
+        families?: EndpointEventFamily[];
+        principalScopes?: string[];
+        onConnected?(): void;
+    }): AsyncIterable<EndpointTransportEvent>;
+}
+export declare function createHttpEndpointTransport(options: {
+    baseUrl: string;
+    environmentId: string;
+    credentials: EndpointCredentials;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    streamUrl?: string;
+    /** Identifies one logical subscriber within its authenticated principal.
+     * Resolve once per transport; independent tabs/devices must use distinct IDs. */
+    streamId?: string | (() => string | Promise<string>);
+    ownershipVersion?: number | (() => number | undefined);
+    mlsDevDevice?: MlsDevDeviceHttpOptions;
+    /** Names this client on every request and stream (`X-Canon-Client`), so Canon can apply its client floor. */
+    client?: CanonClientIdentity;
+    /** Canon refused this client as below its floor (`426 CLIENT_UPDATE_REQUIRED`), on any request or stream. Called
+     * before the error is thrown, so a host can stop wherever the refusal surfaces. */
+    onClientUpdateRequired?(error: EndpointError): void;
+}): EndpointTransport;

package/dist/media.d.ts

@@ -1,4 +1,4 @@
-import { CanonClient, type CanonReplyContext, type CanonMessage, type MediaAttachment, type ResumableMediaUploadResult, type SendMessageOptions } from '@canonmsg/core';
+import { CanonClient, type CanonReplyContext, type CanonMessage, type MediaAttachment, type ResumableMediaUploadResult, type SendMessageOptions } from './internal/core/index.js';
 export interface MaterializeMediaOptions {
     agentId: string;
     conversationId: string;